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 |
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"
}
}
Request RECURRENT Body
{
"merchantId": 1073741824,
"subscriptionDetails": {
"type": "RECURRENT",
"device": "MOBILE",
"customerId": "992212092",
"processorCode": "Yape_on_file",
"periodicity":"3",
"amount":150.00
}
}
🔄 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 |