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 ID assigned to the merchant by Monnet
type	String (Required) Subscription type. Example: **ON_DEMAND**
device	String (Required) Origin device. Allowed value: `Mobile or Web Example `Mobile
customerId	String (Required) Unique identifier of the customer within the merchant’s system Example: `992984321
processorCode	String (Required) Code identifying the selected payment processor 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 assigned to the subscription
status	String (Required) Initial status of the subscription (default is PENDING) `
deepLink	String (Opcional) URL that the customer must access to complete the subscription flow, this apply only for device "MOBILE"
ErrorDetails	Object Optional In case return error.
systemCode	String (Required)
errorCode	String (Required) Code representing the specific issue encountered. See Errors Code
ErrorMessage	String (Required) Description of the specific error See Errors Code

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

}

Errors Code

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