Create Suscription

The POST /subscription endpoint allows merchants to create a One Click Payment (OCP) subscription, associating a customer with a payment processor in order to authorize future charges without requiring the customer to re-enter their payment details.

This functionality is designed to support a variety of subscription types and device contexts, providing flexibility for merchants in managing payment flows.

Endpoints

📘
URL
Certification:<https://cert.subscriptions.payin.monnet.io/api/v1/subscription
Production: <https://subscriptions.payin.monnet.io/api/v1/subscription

📝Subscription Creation Request

🔐 Authorization Header

All requests to the /subscription.create endpoint must include a custom Authorization header to ensure secure communication and proper merchant validation.

Header	Value Format	Required
Authorization	Bearer SHA512(merchantId + type + customerId + processorCode + keyPayin)	✅ Yes

The Authorization value must be a SHA-512 hash generated by concatenating the following fields:

Field	Description
merchantId	Integer (Required) Unique identifier assigned to the merchant by Monnet.
type	String (Required) Type of operation. Possible values: `ON_DEMAND` (one-time payment) or `RECURRENT` (recurring payment).
customerId	String (Required) Unique identifier of the end user or customer within the merchant’s system.
processorCode	String (Required) Code identifying the payment processor to be used for the transaction.
keyPayin	String (Required) Secret key provided by Monnet for secure authentication of payment operations.

📥 Request Data

Specifies the structure and mandatory parameters that must be included in the request body to ensure the successful creation of a subscription.

Field	Description
merchantId	Integer (Required) Unique identifier generated and assigned by Monnet to each merchant. Required for identifying the merchant across all transactions and API operations.
type	String (Required) Defines the type of subscription configured for the customer. This determines how and when the charges will be initiated. ON_DEMAND: Charges are triggered manually by the merchant when needed. RECURRENT: Charges are processed automatically at set intervals (e.g., monthly). This field defines the subscription’s processing frequency within Monnet. Example: ON_DEMAND
device	String (Required) Specifies the origin device used to initiate the subscription process. Allowed values: MOBILE, WEB Example MOBILE
customerId	String (Required) Required identifier to associate the subscription; the user's cellphone number, which must be linked to their Yape wallet, must be used. Example: 992984321
processorCode	String (Required) Code identifying the selected payment processor to be used for the transaction. This value determines the routing of the payment within the Monnet platform. Example: Yape_on_file
periodicity	String (optional) Specifies the periodicity (in months) for processing the recurring charge. This field is required when the type value is RECURRENT. Only numeric characters are accepted. Example: 3
amount	Number (Optional) Specifies the recurring amount to be charged. This field is required when the type value is RECURRENT. Accepts numeric characters and the decimal separator ('.'). The format must be #####.##. Example: 150.00
metadata	Array(optional) Collection of up to 5 key–value pairs that allows merchants to include custom complementary information when creating a subscription. Each element must contain the subfields key and value. The metadata included in the subscription creation will be replicated in subsequent operations and webhook notifications related to that subscription. If no metadata is provided, this field must be omitted.
key	String (required) Identifier of the additional data sent within the metadata. Must not exceed 20 alphanumeric characters Allowed format - Letters (`a–z`, `A–Z`), digits (`0–9`), hyphen (`-`), underscore (`_`)
value	String (required) Value associated with the corresponding key within the metadata. Must not exceed 100 characters. Allowed format - Allowed characters: letters, digits, spaces, and symbols: `- _ . : , / @` - Currency symbols allowed if needed (e.g. `S/ 150.00`, `$150.00`)

🚧
Mobile Number Validation (Merchant Recommendation)
To ensure that the mobile number being subscribed corresponds to the user’s actual Yape number, it is recommended to consider the WEB Flow when the merchant requires explicit validation of the mobile number that will be subscribed.

Flow Behavior Notes
Web Flow User manually enters mobile number within Yape authorization screen Ensures the number provided is the exact number that will be subscribed and used for future transactions
Mobile Flow (Deeplink) Subscription initiated via deeplink directly from mobile Remains valid and fully supported, but does not enforce explicit number entry

Recommendation: If the merchant needs to explicitly validate the mobile number being subscribed, the WEB Flow is the most suitable option. The Mobile Flow with Deeplinks remains available and supported.

Flow	Behavior	Notes
Web Flow	User manually enters mobile number within Yape authorization screen	Ensures the number provided is the exact number that will be subscribed and used for future transactions
Mobile Flow (Deeplink)	Subscription initiated via deeplink directly from mobile	Remains valid and fully supported, but does not enforce explicit number entry

📘
Additional Recommendation – Subscription Request Control
The provider must implement a control mechanism to ensure that only one active subscription request per mobile number can exist at any given time.
While a request for a specific number remains in a Pending state, the system must not allow submitting a new subscription request for that same number.
A new subscription request may only be initiated once the previous request has been released, rejected, or expired.

This service allows merchants to initiate the creation of a One Click Payment (OCP) subscription, associating a customer with a specific payment processor.

Request ON_DEMAND Body

The merchant must send a JSON payload with the following structure:

{
  "merchantId": 1073741824,
  "subscriptionDetails": {
    "type": "ON_DEMAND",
    "device": "MOBILE",
    "customerId": "992212092",
    "processorCode": "Yape_on_file"
  }
}

{
  "merchantId": 1073741824,
  "subscriptionDetails": {
    "type": "ON_DEMAND",
    "device": "MOBILE",
    "customerId": "992212092",
    "processorCode": "Yape_on_file"
  },
  "metadata": [
    {
      "key": "MerchantReference",
      "value": "98212321"
    }
  ]
}

Request RECURRENT Body

{
  "merchantId": 1073741824,
  "subscriptionDetails": {
    "type": "RECURRENT",
    "device": "MOBILE",
    "customerId": "992212092",
    "processorCode": "Yape_on_file",
    "periodicity":"3",
    "amount":150.00

  }
}

Request RECURRENT Body

{
  "merchantId": 1073741824,
  "subscriptionDetails": {
    "type": "RECURRENT",
    "device": "MOBILE",
    "customerId": "992212092",
    "processorCode": "Yape_on_file",
    "periodicity": "3",
    "amount": 150.00
  },
  "metadata": [
    {
      "key": "MerchantReference",
      "value": "98212321"
    }
  ]
}

🔄 Subscription Creation Response

📤 Success Response Data

Field	Description
subscriptionId	Integer (Required) Unique identifier generated and assigned by Monnet for each subscription. This value is required to manage and track subscription-related operations within your integration.
status	String (Required) Indicates the initial status of the subscription. Defaults to PENDING and is used to control the lifecycle of the subscription within the Monnet platform.
deepLink	String (Opcional) URL that the customer must access to complete the subscription flow. Applicable only when the device type is set to MOBILE.

If the subscription creation request is valid, the service will respond with a 200 OK status and return a JSON payload containing the subscription details, including a unique identifier and a deepLink for the customer to complete the authorization process.:

✅ Successful Response – 200

📱Device MOBILE

{
  "subscriptionId": 1073741824,
  "status": "PENDING",
  "deepLink": "https://yape.com.pe/app/checkout/ocp/subscription?id=17ea8134-723b-435b-8001-efb73a0c48de&service_company=QA%20Yape%20OCP%20PER&partner_code=PEX006&origin_detail=MOBILE"
}

For the mobile scenario, the merchant must perform a redirect to the deeplink provided by OCP provider as response.

💻 Device WEB

{
  "subscriptionId": 1073741824,
  "status": "PENDING",
  "deepLink": ""
}

For this scenario, you must follow the workflow and instructions provided by OCP provider when accessed from a desktop environment.

📤 Error Response Data

Field	Description
errorCode	String (Opcional) General code representing the main error type. Typically business-level. See Errors Code
errorMessage	String (Required) Human-readable description of the general error See Errors Code
errorFieldDetails	Array (Opcional) List of specific errors encountered during processing
fleld	String (Required) Refers to the affected field.
errorMessage	String (Required) Description of the specific error

This response indicates that the subscription transaction could not be processed due to a business or validation error. It provides both a general error message and a detailed list of one or more specific underlying errors.

⚠️ Error Response

❌Error Response Body

{
    "errorCode": "9099",
    "errorMessage": "error",

}

❌Error Response Body Detail

{
    "errorCode": "B400",
    "errorMessage": "Invalid request",
    "errorFieldDetails": [
        {
            "field": "subscriptionDetails.device",
            "errorMessage": "El valor 'WEBB' no es válido para el campo 'subscriptionDetails.device'. Valores esperados: [WEB, MOBILE]."
        }
    ]
}

Error Codes

Error Code	Error Message
B422	Subscription already exist
E401	Unauthorized request
B401	The merchant does not exists
B402	The merchant does not contain the correct country settings
B404	The merchant does not contain the correct processor settings
B500	Internal error
9099	error

Endpoints

📘URL

📝Subscription Creation Request

🔐 Authorization Header

📥 Request Data

🚧

Mobile Number Validation (Merchant Recommendation)

📘

Additional Recommendation – Subscription Request Control

Request ON_DEMAND Body

Request RECURRENT Body

Request RECURRENT Body

🔄 Subscription Creation Response

📤 Success Response Data

✅ Successful Response – 200

📱Device MOBILE

For the mobile scenario, the merchant must perform a redirect to the deeplink provided by OCP provider as response.

💻 Device WEB

For this scenario, you must follow the workflow and instructions provided by OCP provider when accessed from a desktop environment.

📤 Error Response Data

⚠️ Error Response

❌Error Response Body

❌Error Response Body Detail

Error Codes

📘
URL