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

🔐 Authorization Header

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

📥 Header Required

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:

C

- `merchantId`: Assigned merchant identifier
- `type`: Operation type (`ON_DEMAND/RECURRENT`)
- `customerId`: End user/customer ID
- `processorCode`: Code of the payment processor
- `keyPayin`: Secret key assigned by Monnet

Field Description

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 defined intervals (e.g., monthly, weekly). This field helps Monnet determine the appropriate flow and behavior for the subscription lifecycle. 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) Unique identifier of the customer within the merchant’s system. In Peru, this typically corresponds to the customer's cellphone number, used to associate the subscription with the correct user 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

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

Request Body

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

JSON

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

Response Field Description

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.
ErrorDetails	Object Optional In case of error, a standardized error response will be returned.
systemCode	String (Required)
errorCode	String (Required) Represents the specific error encountered during the operation. See to the Error Codes section for a complete list.
ErrorMessage	String (Required) Description of the specific error See the Error Codes section for a complete list.

Successful Response – 200 OK

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.:

When send device MOBILE

JSON

{
  "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.

When send device WEB

JSON

{
  "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

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 Field

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

Response Body (JSON)

JSON

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

}

Error Codes

Error Code	Error Message	HTTP Code
E401	Unauthorized request	401
B401	The merchant does not exists	200
B402	The merchant does not contain the correct country settings	200
B403	The merchant does not contain the correct currency settings.	200
B404	The merchant does not contain the correct processor settings	200
B422	Subscription already exist	200
9099	error	200