Pine LabsDOCS
Create Account

UPI Reserve Pay Integration Steps

Step-by-step guide to integrate UPI Reserve Pay with Pine Labs Online APIs — create SBMD subscriptions, authorize mandates, and execute partial debits.

View as MarkdownOpen in ChatGPTOpen in ClaudeOpen in Perplexity

Follow the below steps to integrate with Pine Labs Online seamless checkout APIs.

  1. Generate Token
  2. Create Customer
  3. Create SBMD Subscription
  4. Fetch SBMD Subscription
  5. Create Payment
  6. Create Presentation

[Prerequisite] — Get Your API Credentials

Before you begin integrating, create your free Pine Labs Online developer account to get access to UAT credentials, API keys, and the merchant dashboard.

  1. Sign Up — Visit the Pine Labs Online Dashboard and register with your business email.
  1. Verify Your Email — Confirm your email address through the verification link sent to your inbox.
  2. Find Your Credentials — Go to Settings → API Keys to generate your test credentials. Use the Client ID as PINELABS_CLIENT_ID and the Client Secret as PINELABS_CLIENT_SECRET.
Pine Labs Dashboard

1. 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 --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" } '

Refer to our Generate Token API documentation to learn more.

2. Create Customer

Create a new customer profile in the Pine Labs Online system. The customer profile can be used for tokenization and recurring payment operations.

cURL
curl --request POST \ --url https://pluraluat.v2.pinepg.in/api/v1/customer \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --header 'Content-Type: application/json' \ --data '{ "merchant_customer_reference": "82d57572-057c-4826-5775-385a52150554", "first_name": "Kevin", "last_name": "Bob", "country_code": "91", "mobile_number": "9876543210", "email_id": "kevin@example.com", "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": "billing" }, "gstin": "28ABCDE1234F2Z6", "merchant_metadata": { "clientId": "DD", "transactionReferenceNo": "pine-1223", "merchantId": "1234", "tid": "9000990", "acquirerName": "HDFC_FSS", "isOfferDisplayRequired": "true", "OfferData": "UHJvZHVjdF9Db2RlPSIgIiZQcm9kdWN0X05hbWU9IiImUGF5bWVudF9Nb2RlPUJhbmsgRU1JJkNhcmRfVHlwZT1EZWJpdCBDYXJkJkJhbmtfTmFtZT1IREZDIERlYml0JkVNSV9UZW51cmU9NiZJbnRlcmVzdF9SYXRlPTkuMCZJbnRlcmVzdF9BbW91bnQ9MTM4MTQwJk1vbnRobHlfSW5zdGFsbG1lbnQ9ODk0NjkwJkF1dGhvcml6YXRpb25fQW1vdW50PTEwMCZMb2FuX2Jvb2tpbmdfQW1vdW50PTUyMzAwMDAmSW50ZXJlc3RfQ2FzaGJhY2tfQW1vdW50PTAmSW50ZXJlc3RfQ2FzaGJhY2tfVHlwZT1EZWZlcnJlZCZBZGRpdGlvbmFsX0Nhc2hiYWNrPSIiJkFkZGl0aW9uYWxfQ2FzaGJhY2tfVHlwZT0iIiZEZXNjcmlwdGlvbj1CYW5rIEVNSSZQcm9kdWN0X1ZhbHVlPTUyMzAwMDA", "tenant_id": "PGATPOS", "is_offer_validation_required": "true" } } '

Refer to our Create Customer API documentation to learn more.

3. Create SBMD Subscription

Use this API to create a SBMD Subscription

Below are the sample requests and response for a Create SBMD Subscription API.

cURL
curl --location 'https://pluraluat.v2.pinepg.in/ps/api/v1/public/subscriptions/sbmd' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer {{token}}' \ --data '{ "merchant_subscription_reference" : "1f81d52c-a7f2-4ae8-bf2b-75bb0b8b420c", "customer_id" : "cust-v1-260413170440-aa-gIPYwk", // 118284 "plan_details" : { "reserve_amount" : 500, "currency" : "INR", "validity_days" : 40, "description" : "Test SBMD" }, "callback_url" : "www.google.com", "terms_accepted" : false }'

Refer to our Create SBMD Subscription API documentation to learn more.

4. Fetch SBMD Subscription

Use this API to SBMD subscription details: if the subscription is in active state, the live balance details (amount used upto date, amount that can be used would be returned).

Below are the sample requests and sample response for Fetch SBMD Subscription API.

cURL
curl --location 'https://pluraluat.v2.pinepg.in/ps/api/v1/public/subscriptions/sbmd/v1-sub-260422154824-aa-M3qU2m' \ --header 'Authorization: Bearer {{token}}'

Refer to our Fetch SBMD Subscription API documentation to learn more.

5. Create Payment

To create a payment, use our Create Payment API, use the order_id returned in the response of a Create SBMD Subscription API to link the payment against an order.

Below are the sample requests and sample response for Card Payment API.

cURL
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": [ { "merchant_payment_reference": "008cf04b-a770-4777-854e-b1e6c1230609", "payment_method": "CARD", "payment_amount": { "value": 1100, "currency": "INR" }, "payment_option": { "card_details": { "name": "Anil Reddy", "card_number": "4111111111111111", "cvv": "272", "expiry_month": "04", "expiry_year": "2029", "registered_mobile_number": "9876543210" } } } ] } '

Refer to our Create Payment API documentation to learn more.

6. Create Presentation

To debit funds from the sbmd mandate, we would be using the existing create presentation API, which initiates the payment and returns the order id. we can fetch these details using the get presentation by merchant_presentation_reference or presentation_id API’s.

Shown below are the sample requests and sample response for a Create Presentation API.

cURL
curl --location 'https://pluraluat.v2.pinepg.in/ps/api/v1/public/presentations' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer {{token}}' --data '{ "subscription_id": "v1-sub-260415093828-aa-vSZBBY", "amount": { "value": 100, "currency": "INR" }, "merchant_presentation_reference" : "ff9e97a9-9f41-452d-9463-9ea5d5a8d5ed" }'

Refer to our Create Presentation API documentation to learn more.

Handling Response

Response StatusMeaningMerchant Action
CREATEDSBMD subscription has been created and is awaiting mandate approval.Continue with mandate creation and customer approval flow.
ACTIVEMandate is approved and available for debits.Use Create Presentation API to debit funds.
PENDINGPresentation request is created and processing is pending.Fetch presentation status or wait for webhook notification.
FAILEDRequest failed.Check error code and message, correct and retry if applicable.
SUCCESSDebit or operation completed successfully.Order status and presentation updated successfully/

Webhooks

Webhook events:

EventTriggered When
Subscription ActivatedOnce UPI Reserve Pay mandate is approved by the customer
Subscription ChargedOnce UPI Reserve Pay Debit is Successfully executed
Subscription CompletedOnce UPI Reserve Pay Mandate reaches its expiry

Testing

UAT environment: Use staging endpoint https://api-staging.pluralpay.in.

OutcomeHow to Simulate
InitiatedCreate SBMD subscription and start mandate approval flow.
SuccessSetup Mandate Successfully, with allowed amount and timeline (Less than 10k and within 90 days validity)
FailedCreate a Mandate with amount greater than 20000 rupees

Error Handling

Error ScenarioExpected Message / CodeSolution
Customer already has an active SBMD mandate.ACTIVE_SBMD_EXISTSDo not create another SBMD mandate for the same customer. Use existing active mandate or ask customer to revoke it if required.
Debit amount exceeds remaining balance.INSUFFICIENT_BALANCE_FOR_SBMD_PRESENTATIONFetch live balance and retry with an amount less than or equal to remaining balance.
PreviousUPI Reserve PayNextUPI Reserve Pay (SBMD) FAQs