--- title: Design an Integration slug: subscriptions/integration-steps excerpt: Plan your subscription integration architecture hidden: false sidebar_order: 3 metadata: title: Design Subscription Integration β€” Architecture Planning | Pine Labs description: >- Plan your subscription integration architecture covering mandate registration, pre-debit notifications, and debit execution. Understand workflows for one-time, on-demand, and recurring mandates. keywords: >- subscription integration, architecture planning, mandate registration, pre-debit notification, integration design, Pine Labs subscriptions robots: index --- ## Integration Steps Learn how to integrate subscription APIs to automate plan creation, subscription management, and scheduled payments. The integration process involves the following steps: ### 1. Mandate Registration - This step is common to all three mandate types. - It involves registering the customer’s consent and mandate details. ### 2. Pre-Debit Notification & Debit Execution Request - This step is applicable only for One-Time and On-Demand mandates. - It includes notifying the customer before initiating a debit and executing the debit transaction. > πŸ“˜ Note: > > - For recurring mandates (e.g., **Weekly**, **Monthly**, etc.), Pine Labs handles both **Pre-Debit Notification** and **debit execution** automatically. > - Pine Labs will debit and automatically refund `β‚Ή2` if no amount is charged during the mandate registration process, as per the plan details. --- ## Mandate Registration Follow the below steps to integrate with Pine Labs Online subscription APIs for Mandate Registration. 1. [Generate Token](#generate-token) 2. [Create Plan](#create-plan) 3. [Create Subscription](#create-subscription) 4. [Create Payment](#create-payment) 5. [Handle Payment](#handle-payment) 1. [Store Payment Details on Your Server](#store-payment-details) 2. [Verify Payment Signature](#verify-signature) > πŸ“˜ Note > > - Ensure you store your Client ID and Secret in your Backend securely. > - Integrate our APIs on your backend system. > - We strictly recommend not to call our APIs from the frontend. > - Failure to adhere to the above guidelines may result in legal implications. In such cases, you will be held responsible for any damage or loss arising from non-compliance. ---

1. [Prerequisite] Generate Token

Integrate our Generate Token API in your backend servers to generate the access token. Use the token generated to authenticate Pine Labs Online APIs. Below are the sample requests and response for the Generate Token API. ```curl cURL – UAT curl --request POST \ --url https://pluraluat.v2.pinepg.in/api/auth/v1/token \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --header 'Request-Timestamp: 2024-07-09T07:57:08.022Z' \ --header 'Request-ID: c17ce30f-f88e-4f81-ada1-c3b4909ed235' \ --data ' { "client_id": "a17ce30e-f88e-4f81-ada1-c3b4909ed232", "client_secret": "fgwei7egyhuggwp39w8rh", "grant_type": "client_credentials" } ' ``` ```curl cURL – PROD curl --request POST \ --url https://api.pluralpay.in/api/auth/v1/token \ --header 'accept: application/json' \ --header 'content-type: application/json' \ --header 'Request-Timestamp: 2024-07-09T07:57:08.022Z' \ --header 'Request-ID: c17ce30f-f88e-4f81-ada1-c3b4909ed235' \ --data ' { "client_id": "a17ce30e-f88e-4f81-ada1-c3b4909ed232", "client_secret": "fgwei7egyhuggwp39w8rh", "grant_type": "client_credentials" } ' ``` ```json Sample Response { "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c", "expires_in": 3600 } ``` Refer to our [Generate Token API](/api/authentication/generate-token) documentation to learn more. ---

2. Create Plan

Use this API to Create a Plan. To authenticate this API, use the generated access token in the Authorization headers of the API request. Below are the sample requests and response for the Create Plan API. ```curl cURL – UAT curl --request POST \ --url https://pluraluat.v2.pinepg.in/api/v1/public/plans \ --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c' \ --header 'Content-Type: application/json' \ --header 'Request-ID: c17ce30f-f88e-4f81-ada1-c3b4909ed235' \ --header 'Request-Timestamp: 2024-07-09T07:57:08.022Z' \ --header 'accept: application/json' \ --data ' { "plan_name": "Monthly Plan 2025-06-12T06:16:47.175Z", "plan_description": "Diwali dhammaka plan intended to attract customers on diwali time", "frequency": "Month", "amount": { "value": 100, "currency": "INR" }, "max_limit_amount": { "value": 210, "currency": "INR" }, "initial_debit_amount": { "value": 110, "currency": "INR" }, "trial_period_in_days": 0, "end_date": "2026-10-21T12:02:28Z", "merchant_metadata": { "key1": "DD" }, "merchant_plan_reference": "9856c70c-a0c3-4c03-b537-9ed7c80bc97e", "auto_debit_ot" : false } ' ``` ```curl cURL – PROD curl --request POST \ --url https://api.pluralpay.in/api/v1/public/plans \ --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c' \ --header 'Content-Type: application/json' \ --header 'Request-ID: c17ce30f-f88e-4f81-ada1-c3b4909ed235' \ --header 'Request-Timestamp: 2024-07-09T07:57:08.022Z' \ --header 'accept: application/json' \ --data ' { "plan_name": "Monthly Plan 2025-06-12T06:16:47.175Z", "plan_description": "Diwali dhammaka plan intended to attract customers on diwali time", "frequency": "Month", "amount": { "value": 100, "currency": "INR" }, "max_limit_amount": { "value": 210, "currency": "INR" }, "initial_debit_amount": { "value": 110, "currency": "INR" }, "trial_period_in_days": 0, "end_date": "2026-10-21T12:02:28Z", "merchant_metadata": { "key1": "DD" }, "merchant_plan_reference": "9856c70c-a0c3-4c03-b537-9ed7c80bc97e", "auto_debit_ot" : false } ' ``` ```json Sample Response { "plan_id": "v1-pla-250612061639-aa-666Zge", "status": "ACTIVE", "plan_name": "Monthly Plan 2025-06-12T06:16:37.364Z", "plan_description": "Diwali dhammaka plan intended to attract customers on diwali time", "frequency": "Month", "amount": { "value": 100, "currency": "INR" }, "max_limit_amount": { "value": 210, "currency": "INR" }, "trial_period_in_days": 0, "start_date": "2025-06-12T06:16:39.92710492Z", "end_date": "2026-10-21T12:02:28Z", "merchant_metadata": { "key1": "DD" }, "merchant_plan_reference": "b41770ac-cd3a-48d3-9e93-7dc9246b4751", "created_at": "2025-06-12T06:16:39.933117Z", "modified_at": "2025-06-12T06:16:39.93313Z", "initial_debit_amount": { "value": 110, "currency": "INR" }, "auto_debit_ot": false } ``` Refer to our [Create Plan API](/api/subscriptions-plans/create-plan) documentation to learn more. > πŸ“˜ Note: > > - **auto\_debit\_ot** is only applicable for One-Time (OT) frequency. > - **initial\_debit\_amount** is only valid for non-OT frequency. ---

3. Create Subscription

To Create Subscription, use our Create subscription API, use the `plan_id `returned in the response of a Create Plan API to link the subscription with a plan. For authentication use the generated access token in the headers of the API request. Below are the sample requests and response for the Create subscription API. ```curl cURL – UAT curl --request POST \ --url https://pluraluat.v2.pinepg.in/api/v1/public/subscriptions \ --header 'Authorization: Bearer https://pluraluat.v2.pinepg.in/api/v1/public/plans' \ --header 'Content-Type: application/json' \ --header 'Request-ID: c17ce30f-f88e-4f81-ada1-c3b4909ed235' \ --header 'Request-Timestamp: 2024-07-09T07:57:08.022Z' \ --header 'accept: application/json' \ --data ' { "merchant_subscription_reference": "38ed3d71-1b0f-469e-b5e4-67606406f676", "plan_id": "v1-pla-250612061639-aa-666Zge", "enable_notification": true, "start_date": "2025-06-12T06:22:21Z", "end_date": "2025-06-21T17:32:28Z", "customer_id": "cust-v1-250519171901-aa-dPF6mg", "allowed_payment_methods": [ "UPI" ], "integration_mode": "REDIRECT", "merchant_metadata": { "key1": "DD", "key2": "XOF" }, "is_tpv_enabled": false, "callback_url": "www.google.com", "failure_callback_url":"www.example.com/failure" } ' ``` ```curl cURL – PROD curl --request POST \ --url https://api.pluralpay.in/api/v1/public/subscriptions \ --header 'Authorization: Bearer https://pluraluat.v2.pinepg.in/api/v1/public/plans' \ --header 'Content-Type: application/json' \ --header 'Request-ID: c17ce30f-f88e-4f81-ada1-c3b4909ed235' \ --header 'Request-Timestamp: 2024-07-09T07:57:08.022Z' \ --header 'accept: application/json' \ --data ' { "merchant_subscription_reference": "38ed3d71-1b0f-469e-b5e4-67606406f676", "plan_id": "v1-pla-250612061639-aa-666Zge", "enable_notification": true, "start_date": "2025-06-12T06:22:21Z", "end_date": "2025-06-21T17:32:28Z", "customer_id": "cust-v1-250519171901-aa-dPF6mg", "allowed_payment_methods": [ "UPI" ], "integration_mode": "REDIRECT", "merchant_metadata": { "key1": "DD", "key2": "XOF" }, "is_tpv_enabled": false, "callback_url": "www.google.com", "failure_callback_url":"www.example.com/failure" } ' ``` ```json Sample Response { "callback_url": "www.google.com", "failure_callback_url": "www.example.com/failure", "redirect_url": "https://api.pluralonline.com/api/v3/checkout-bff/redirect/checkout?token=V3_ye7V868X7DP92HQCSnVq7XZNlxvVhOQ3OgXGt96Buwfc53BwN9mUDwJsOcr%2Fw5uq&subscription_id=v1-sub-250612062122-aa-3HLXL5", "order_id": "v1-250612062122-aa-UZyPbu", "subscription_id": "v1-sub-250612062122-aa-3HLXL5", "merchant_subscription_reference": "f5d77ef9-fa11-4f58-a9f4-543e4a7022c5", "enable_notification": true, "plan_details": { "plan_id": "v1-pla-250612061639-aa-666Zge", "status": "ACTIVE", "plan_name": "Monthly Plan 2025-06-12T06:16:37.364Z", "plan_description": "Diwali dhammaka plan intended to attract customers on diwali time", "frequency": "Month", "amount": { "value": 100, "currency": "INR" }, "max_limit_amount": { "value": 210, "currency": "INR" }, "trial_period_in_days": 0, "start_date": "2025-06-12T06:16:39.927105Z", "end_date": "2026-10-21T12:02:28Z", "merchant_metadata": { "key1": "DD" }, "merchant_plan_reference": "b41770ac-cd3a-48d3-9e93-7dc9246b4751", "created_at": null, "modified_at": null, "initial_debit_amount": { "value": 110, "currency": "INR" }, "auto_debit_ot": false }, "start_date": "2025-06-12T06:22:21Z", "end_date": "2025-06-21T17:32:28Z", "customer_id": "cust-v1-250519171901-aa-dPF6mg", "payment_mode": null, "allowed_payment_methods": [ "UPI" ], "integration_mode": "REDIRECT", "merchant_metadata": { "key1": "DD", "key2": "XOF" }, "status": "CREATED", "is_tpv_enabled": false, "bank_account": { "account_number": null, "name": null, "ifsc": null }, "created_at": "2025-06-12T06:21:22.242344Z", "modified_at": "2025-06-12T06:21:22.267111Z", "order_amount": { "value": 210, "currency": "INR" } } ``` Refer to our [Create subscription API](/api/subscriptions-subscriptions/create-subscription) documentation to learn more. ---

4. Create Payment

To create a payment, use our Create Payment API, use the `order_id` returned in the response of a Create Subscription API to link the payment against an order. The initial debit amount is the first charge applied to your customers to verify the UPI transaction details. Once the transaction is successful, the subscription will be marked as 'ACTIVE.' You can determine the initial debit amount based on your business needs. > πŸ“˜ Note: > > - The `payment_amount.value` must match the `max_limit_amount.value` specified in the `Create Plan API`. > - Currently, subscriptions are supported only through `UPI` payments. You can use either the `UPI Intent` or `UPI Collect` flow for processing these payments. Below are the sample requests and sample response for a Create Payment API via Intent Flow. ```curl cURL - UAT curl --location 'https://pluraluat.v2.pinepg.in/api/pay/v1/orders/{order_id}/payments' \ --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c' \ --header 'Content-Type: application/json' \ --header 'Request-ID: c17ce30f-f88e-4f81-ada1-c3b4909ed235' \ --header 'Request-Timestamp: 2024-07-09T07:57:08.022Z' \ --header 'accept: application/json' \ --data ' { "payments": [ { "payment_method": "UPI", "merchant_payment_reference": "108cf506-c6a1-4535-9e7f-3af9c6d3d90c", "payment_amount": { "value": 100, "currency": "INR" }, "payment_option": { "upi_details": { "txn_mode": "INTENT" } }, "mandate_info": { "request_type": "CREATE_MANDATE" } } ] } ' ``` ```curl cURL - PROD curl --location 'https://api.pluralpay.in/api/pay/v1/orders/{order_id}/payments' \ --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c' \ --header 'Content-Type: application/json' \ --header 'Request-ID: c17ce30f-f88e-4f81-ada1-c3b4909ed235' \ --header 'Request-Timestamp: 2024-07-09T07:57:08.022Z' \ --header 'accept: application/json' \ --data ' { "payments": [ { "payment_method": "UPI", "merchant_payment_reference": "108cf506-c6a1-4535-9e7f-3af9c6d3d90c", "payment_amount": { "value": 100, "currency": "INR" }, "payment_option": { "upi_details": { "txn_mode": "INTENT" } }, "mandate_info": { "request_type": "CREATE_MANDATE" } } ] } ' ``` ```json Sample Response { "data": { "order_id": "v1-250408102515-aa-x2F8Qw", "merchant_order_reference": "8b5e2b5b-9fde-4010-af9c-281f9e2fa5af", "type": "CHARGE", "status": "PENDING", "challenge_url": "upi://mandate?pa=PinelabsUat1@icici&pn=PinelabsUat&tr=EZM2025032516184000196272&am=1000.00&cu=INR&orgid=400011&mc=5732&purpose=01&tn=remark&validitystart=25032025&validityend=21062025&amrule=EXACT&Recur=ONETIME&Rev=Y&Share=Y&Block=Y&txnType=CREATE&mode=13&sign=MEYCIQCHkSEsp0e+y2chLL5s+bvkY06b4NbA9gcl9fMykq4WaAIhAJEMQ9h5SOi6/Z+q/9gHGX4cH7RnwacTU5OpZ3nU3C3i", "callback_url": "www.google.com", "failure_callback_url": "www.example.com/failure", "merchant_id": "106639", "order_amount": { "value": 100000, "currency": "INR" }, "pre_auth": false, "allowed_payment_methods": [ "UPI" ], "purchase_details": { "customer": { "email_id": "kevin.bob@gmail.com", "first_name": "kevin", "last_name": "bob", "mobile_number": "9667195458", "country_code": "91", "billing_address": { "address1": "10 Downing Street Westminster London", "address2": "Oxford Street Westminster London", "address3": "Baker Street Westminster London", "pincode": "51524036", "city": "Westminster", "state": "Westminster", "country": "London", "full_name": "Kevin Bob", "adddress_type": "Home", "address_category": "billing" }, "shipping_address": { "address1": "10 Downing Street Westminster London", "address2": "Oxford Street Westminster London", "address3": "Baker Street Westminster London", "pincode": "51524036", "city": "Westminster", "state": "Westminster", "country": "London", "full_name": "Kevin Bob", "adddress_type": "Home", "address_category": "shipping" }, "is_edit_customer_details_allowed": false }, "merchant_metadata": { "key1": "DD", "key2": "XOF" } }, "payments": [ { "id": "v1-250408102515-aa-x2F8Qw-up-c", "merchant_payment_reference": "6b4d003f-0918-45d3-aef0-e21af0f36771", "status": "PENDING", "payment_amount": { "value": 100000, "currency": "INR" }, "payment_method": "UPI", "payment_option": { "upi_data": { "txn_mode": "INTENT" } }, "acquirer_data": { "approval_code": "", "acquirer_reference": "", "rrn": "", "is_aggregator": true }, "created_at": "2025-04-08T11:54:56.092Z", "updated_at": "2025-04-08T11:55:00.001Z", "mandate_info": { "request_type": "CREATE_MANDATE" } } ], "created_at": "2025-04-08T10:25:15.093Z", "updated_at": "2025-04-08T11:55:00.001Z", "integration_mode": "REDIRECT", "payment_retries_remaining": 7 } } ``` Refer to our [Create Payment API](/api/card-payments/create-payment) documentation to learn more. ---

5. Handle Payment

In create payment API response we return a `challenge_url`, use this challenge url to navigate your customers to the checkout page to accept payment. > πŸ“˜ Note: > > - This `challenge_url` is applicable only for UPI Intent flow. > - For UPI Collect flow, the customer will receive a notification in their UPI app to authorize the payment. > πŸ“˜ Note: > > - On successful payment we send the webhook event `ORDER_AUTHORIZED` and the status of the payment is updated to `authorized`. > - You can capture or cancel an order only when the order status is `authorized`.

5.1 Store Payment Details on Your Server

On a successful and failed payment, we return the following fields to the return url. - We recommend you to store the payment details on your server. - You must validate the authenticity of the payment details returned. You can authenticate by verifying the signature. ```json Success Callback Response { "order_id": "v1-4405071524-aa-qlAtAf", "status": "AUTHORIZED", "signature": "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad" } ``` ```json Failure Callbak Response { "order_id": "v1-4405071524-aa-qlAtAf", "status": "AUTHORIZED", "error_code": "USER_AUTHENTICATION_REQUIRED", "error_message": "Consumer Authentication Required", "signature": "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad" } ```

5.2 Verify Payment Signature

Ensure you follow this as a mandatory step to verify the authenticity of the details returned to the checkout form for successful payments. Follow the below steps to verify the signature. 1. Create a signature on your server using the following parameters using the SHA256 algorithm. 1. `order_id`: Unique Identifier generated for an order request on Pine Labs Online database. 2. `payment_status`: Payment status. 3. `error_code`: Short code for the error returned. 4. `error_message`: Corresponding error message for the code. 5. `secret_key`: The Onboarding team has provided you with this information as part of the onboarding process. Use the below sample code to construct HashMap signature using the SHA256 algorithm. ```java Java import java.io.UnsupportedEncodingException; import java.security.InvalidKeyException; import java.security.NoSuchAlgorithmException; import javax.crypto.Mac; import javax.crypto.spec.SecretKeySpec; public class hash { public static void main(String[] args) { // Test the GenerateHash method String input = ""; String secretKey = ""; // Example key in hex String hash = GenerateHash(input, secretKey); System.out.println("Generated Hash: " + hash); } public static String GenerateHash(String input, String strSecretKey) { String strHash = ""; try { if (!isValidString(input) || !isValidString(strSecretKey)) { return strHash; } byte[] convertedHashKey = new byte[strSecretKey.length() / 2]; for (int i = 0; i < strSecretKey.length() / 2; i++) { convertedHashKey[i] = (byte)Integer.parseInt(strSecretKey.substring(i * 2, (i*2)+2),16); //hexNumber radix } strHash = hmacDigest(input.toString(), convertedHashKey, "HmacSHA256"); } catch (Exception ex) { strHash = ""; } return strHash.toUpperCase(); } private static String hmacDigest(String msg, byte[] keyString, String algo) { String digest = null; try { SecretKeySpec key = new SecretKeySpec(keyString, algo); Mac mac = Mac.getInstance(algo); mac.init(key); byte[] bytes = mac.doFinal(msg.getBytes("UTF-8")); StringBuffer hash = new StringBuffer(); for (int i = 0; i < bytes.length; i++) { String hex = Integer.toHexString(0xFF & bytes[i]); if (hex.length() == 1) { hash.append('0'); } hash.append(hex); } digest = hash.toString(); } catch (UnsupportedEncodingException e) { // logger.error("Exception occured in hashing the pine payment gateway request"+e); } catch (InvalidKeyException e) { // logger.error("Exception occured in hashing the pine payment gateway request"+e); } catch (NoSuchAlgorithmException e) { // logger.error("Exception occured in hashing the pine payment gateway request"+e); } return digest; } public static boolean isValidString(String str){ if(str != null && !"".equals(str.trim())){ return true; } return false; } } ``` > πŸ“˜ Note: > > To create a request string, format the key-value pairs of data returned to the return URL. The pairs are separated by `&` and arranged in ascending order based on a lexicographical comparison of the keys. Shown below is a example to create a request string. ```text Success "key1=value1&key2=value2", ["order_id=random_order_id&status=AUTHORIZED"] ``` ```text Failed "key1=value1&key2=value2&key3=value3&key4=value4", ["error_code=USER_AUTHENTICATION_FAILED&error_message=Consumer Authentication required&order_id=&status=FAILED"] ``` 2. If the signature generated on your server matches the Pine Labs Online signature returned in the return URL, it confirms that the payment details are from Pine Labs Online. 3. Capture the status returned on your database. Once the payment status is `AUTHORIZED` you can either capture or cancel an order. --- ## Pre-Debit Notification Flow Learn how you can process the Pre-Debit notifications and debit execution request for As Presented and One Time Payments using Pine Labs Online APIs. > πŸ“˜ Note: > > - For recurring mandates (e.g., **Weekly, Monthly**, etc.), Pine Labs handles both **Pre-Debit Notification** and **debit execution automatically**. > - The process for creating a Mandate Registration remains unchanged. Once a subscription becomes **ACTIVE**, you can use the **Presentation APIs** to initiate or present payments as required. Pine Labs Online now supports the **execution of mandates** for **existing subscriptions** through the **Presentation feature**, enabling you to collect payments against `active` mandates. This functionality is available only in the following modes: - **As Presented (AS)** - **One-Time (OT)** > ❗️ Important > > - This feature can only be utilized when the subscription status is in `ACTIVE` or `HALTED`. There are two modes to initiate customer debits, depending on who controls the **Pre-Debit Notification (PDN)** process:
A. Customer Debit with PDN Controlled by Pine Labs: In this flow, Pine Labs manages the pre-debit notification and execution process. **Steps**: 1. Use the [Create Presentation API](/api/subscriptions-presentations/create-presentation) to debit the customer. 2. This API enables merchants to present a **mandate debit request** for both: 1. **As & When Presented (AS)** frequency transactions. 2. **One-Time (OT)** frequency transactions. 3. Pine Labs automatically sends the **Pre-Debit Notification (PDN)** to the customer **at least 24 hours in advance** on the merchant’s behalf. ### Create Presentation API Use this API to allow you to submit mandate debit requests for both AS and OT frequency transactions. This API is an essential part of Pine Labs Online mandate management system, enabling you to initiate debit requests based on existing customer mandates. Below are the sample requests and sample response for a Create Presentation API. ```curl cURL - UAT curl --request POST \ --url https://pluraluat.v2.pinepg.in/ps/api/v1/public/subscriptions/{subscription_id}/presentations \ --header 'Authorization: Bearer token' \ --header 'Content-Type: application/json' \ --header 'Request-ID: c17ce30f-f88e-4f81-ada1-c3b4909ed235' \ --header 'Request-Timestamp: 2024-07-09T07:57:08.022Z' \ --header 'accept: application/json' \ --data ' { "subscription_id": "v1-sub-4405071524-aa-qlAtAf", "due_date": "2022-09-21T17:32:28Z", "amount": { "value": 100, "currency": "INR" }, "merchant_presentation_reference": "1234567890" } ' ``` ```curl cURL - PROD curl --location 'https://api.pluralpay.in/ps/api/v1/public/subscriptions/{subscription_id}/presentations ' \ --header 'Authorization: Bearer token' \ --header 'Content-Type: application/json' \ --header 'Request-ID: c17ce30f-f88e-4f81-ada1-c3b4909ed235' \ --header 'Request-Timestamp: 2024-07-09T07:57:08.022Z' \ --header 'accept: application/json' \ --data ' { "subscription_id": "v1-sub-4405071524-aa-qlAtAf", "due_date": "2022-09-21T17:32:28Z", "amount": { "value": 100, "currency": "INR" }, "merchant_presentation_reference": "1234567890" } ' ``` ```json Sample Response { "subscription_id": "v1-sub-250612062122-aa-3HLXL5", "presentation_id": "v1-bil-250612063111-aa-FJIBcB", "due_date": "2025-06-05T06:14:21.72036Z", "amount": { "value": 100, "currency": "INR" }, "status": "CREATED", "merchant_presentation_reference": "9caa061f-0e50-494b-aa13-8e902b0bef03" } ``` Refer to our [Create Presentation API](/api/subscriptions-presentations/create-presentation) documentation to learn more.
---
B. Customer Debit with PDN Controlled by Merchant: In this flow, merchants manage the pre-debit notification and debit initiation process. **Steps**: 1. **Send Notification** using the [Subscription Notification API](/api/subscriptions-presentations/send-subscription-notification). 1. Merchants must send the PDN to the customer before initiating a debit. 2. **Execute Debit** Request using the [Create Debit API](/api/subscriptions-presentations/create-debit). 1. This API is used to initiate the actual debit after sending the PDN. > πŸ“˜ Note: > > - For recurring mandates (e.g., **Weekly, Monthly**, etc.), Pine Labs handles both **Pre-Debit Notification** and **execution automatically**. > - Merchants only need to manage PDN for **As Presented** and **One-Time** frequencies. ### Subscription Notification API Use this API to send a pre-debit notification for a given subscription ID. Below are the sample requests and sample response for a Subscription Notification API. ```curl cURL - UAT curl --request POST \ --url https://pluraluat.v2.pinepg.in/ps/api/v1/public/subscriptions/notify \ --header 'Authorization: Bearer token' \ --header 'Content-Type: application/json' \ --header 'Request-ID: c17ce30f-f88e-4f81-ada1-c3b4909ed235' \ --header 'Request-Timestamp: 2024-07-09T07:57:08.022Z' \ --header 'accept: application/json' \ --data ' { "subscription_id": "v1-sub-4405071524-aa-qlAtAf", "due_date": "2022-09-21T17:32:28Z", "amount": { "value": 50000, "currency": "INR" }, "merchant_presentation_reference": "1234567890", "is_merchant_retry": false } ' ``` ```curl cURL - PROD curl --location 'https://api.pluralpay.in/ps/api/v1/public/subscriptions/notify' \ --header 'Authorization: Bearer token' \ --header 'Content-Type: application/json' \ --header 'Request-ID: c17ce30f-f88e-4f81-ada1-c3b4909ed235' \ --header 'Request-Timestamp: 2024-07-09T07:57:08.022Z' \ --header 'accept: application/json' \ --data ' { "subscription_id": "v1-sub-4405071524-aa-qlAtAf", "due_date": "2022-09-21T17:32:28Z", "amount": { "value": 50000, "currency": "INR" }, "merchant_presentation_reference": "1234567890", "is_merchant_retry": false } ' ``` ```json Sample Response { "subscription_id": "v1-sub-4405071524-aa-qlAtAf", "due_date": "2022-09-21T17:32:28Z", "presentation_id": "v1-pre-4405071524-aa-qlAtAf", "amount": { "value": 50000, "currency": "INR" }, "merchant_presentation_reference": "1234567890", "status": "NOTIFIED" } ``` Refer to our [Subscription Notification API](/api/subscriptions-presentations/send-subscription-notification) documentation to learn more. *** ### Create Debit API Use this API to execute a debit against a subscription ID. Below are the sample requests and sample response for a Create Debit API. ```curl cURL - UAT curl --request POST \ --url https://pluraluat.v2.pinepg.in/ps/api/v1/public/subscriptions/execute \ --header 'Authorization: Bearer token' \ --header 'Content-Type: application/json' \ --header 'Request-ID: c17ce30f-f88e-4f81-ada1-c3b4909ed235' \ --header 'Request-Timestamp: 2024-07-09T07:57:08.022Z' \ --header 'accept: application/json' \ --data ' { "presentation_id": "v1-pre-4405071524-aa-qlAtAf", "merchant_presentation_reference": "1234567890", "is_merchant_retry": true } ' ``` ```curl cURL - PROD curl --location 'https://api.pluralpay.in/ps/api/v1/public/subscriptions/execute' \ --header 'Authorization: Bearer token' \ --header 'Content-Type: application/json' \ --header 'Request-ID: c17ce30f-f88e-4f81-ada1-c3b4909ed235' \ --header 'Request-Timestamp: 2024-07-09T07:57:08.022Z' \ --header 'accept: application/json' \ --data ' { "presentation_id": "v1-pre-4405071524-aa-qlAtAf", "merchant_presentation_reference": "1234567890", "is_merchant_retry": true } ' ``` ```json Sample Response { "subscription_id": "v1-sub-4405071524-aa-qlAtAf", "presentation_id": "v1-pre-4405071524-aa-qlAtAf", "due_date": "2024-03-15T10:30:00Z", "amount": { "value": 50000, "currency": "INR" }, "merchant_presentation_reference": "1234567890", "status": "CREATED" } ``` Refer to our [Create Debit API](/api/subscriptions-presentations/create-debit) documentation to learn more.
--- ## Manage subscription 1. **Manage Plan**: Listed below are the various options available to manage a plan. 1. `Update Plan`: Use our [Update Plan API](/api/subscriptions-plans/update-plan) to update plan details. 2. `Delete Plan`: Use our [Delete Plan API](/api/subscriptions-plans/delete-plan) to delete a plan. 2. **Manage Subscription**: Listed below are the various options available to manage subscription. 1. `Pause Subscription`: Use our [Pause Subscription API](/api/subscriptions-subscriptions/pause-subscription) to pause a subscription. 2. `Resume Subscription`: Use our [Resume Subscription API](/api/subscriptions-subscriptions/resume-subscription) to resume a subscription. 3. `Cancel Subscription`: Use our [Cancel Subscription API](/api/subscriptions-subscriptions/cancel-subscription) to cancel a subscription. 4. `Update Subscription`: Use our [Update Subscription API](/api/subscriptions-subscriptions/update-subscription) to update the subscription. 3. **Manage Presentation**: Listed below are the various options available to manage Presentation. 1. `Delete Presentation`: Use our [Delete Presentation API](/api/subscriptions-presentations/delete-presentation) to Delete a presentation. 2. `Merchant Retry`: Use our [Merchant Retry API](/api/subscriptions-presentations/create-merchant-retry). This API allows you to retry mandate execution for subscriptions that are in the `DEBIT FAILED` stage. You can retry up to three times before the mandate moves to the `HALTED` stage. After that, you can present the transaction again with a new debit date. 3. `Subscription Notification`: Use our [Subscription Notification API](/api/subscriptions-presentations/send-subscription-notification) to send a pre-debit notification for a given subscription ID. --- ## To Know Your Payment Status To check your payment status, you can rely on Webhook events. 1. **Webhook Notification**: We send Webhook notifications on the successful payment or any changes to the payments object. Refer to our [Webhooks](/developer-tools/webhooks) documentation to learn more. 2. **Use Fetch APIs**: You can use the below list of APIs to fetch the status of Plan, Subscription, and Presentation. 1. **Plans** 1. `Get Plans`: Use our [Get Plans API](/api/subscriptions-plans/list-plans) to fetch all the plan details. 2. `Get Plan by Plan ID`: Use our [Get Plan by Plan ID API](/api/subscriptions-plans/get-plan-by-id) to get the specific plan among the plans available. 3. `Get Plan by Merchant Plan Reference`: Use our [Get Plan by Merchant Plan Reference API](/api/subscriptions-plans/get-plan-by-merchant-reference) to retrieve a specific plan using its merchant Plan reference. 2. **Subscriptions** 1. `Get Subscriptions`: Use our [Get Subscriptions API](/api/subscriptions-subscriptions/list-subscriptions) to get the list of available subscriptions. 2. `Get Subscription by Subscription ID`: Use our [Get Subscription by Subscription ID API](/api/subscriptions-subscriptions/get-subscription-by-id) to get the list of available subscriptions. 3. `Get Subscription by Merchant Subscription Reference`: Use our [Get Subscription by Merchant Subscription Reference API](/api/subscriptions-subscriptions/get-subscription-by-merchant-reference) to retrieve a specific subscription using its merchant subscription reference. 3. **Presentations** 1. `Get Presentations`: Use our [Get Presentation API](/api/subscriptions-presentations/get-presentation-by-id) to get a presentation request. 2. `Get Presentation by Subscription ID`: Use our [Get Presentation by Subscription ID API](/api/subscriptions-presentations/list-presentations-by-subscription) to get a presentation request by subscription Id. 3. `Get Presentation by Merchant Presentation Reference`: Use our [Get Presentation by Merchant Presentation Reference API](/api/subscriptions-presentations/get-presentation-by-merchant-reference) to retrieve a specific presentation using its merchant presentation reference.