--- title: Tokenization slug: tokenization excerpt: >- Learn how you can integrate with Pine Labs Online Token APIs to start accepting payments on your website without card details. hidden: false metadata: title: Tokenization — Secure Card Storage & Token Management | Pine Labs description: >- Process payments using network-issued tokens instead of storing sensitive card details. Comply with COFT regulations, manage tokens securely, enable frictionless recurring payments, and reduce fraud risks with Pine Labs Token APIs. keywords: >- tokenization, card tokenization, COFT compliance, secure payments, token management, recurring payments, PCI compliance, Pine Labs tokens robots: index --- Pine Labs Online Token Management allows you to securely process payments by using network-issued tokens instead of storing sensitive card details. In compliance with COFT regulations, you cannot save customer card information directly. Instead, payment networks provision tokens against a customer’s card with their consent. By integrating Pine Labs Online APIs, you can store and manage these tokens within the customer vault, enabling custom and secure transactions. These tokens can be used for future payments, simplifying the checkout experience while enhancing security and reducing risks for fraud. Token Management ensures compliance with industry standards, allowing you to offer a frictionless digital payment process without handling sensitive card data. ## How Tokens Are Stored in the System ### Token A Token is a non-sensitive replacement for the actual Primary Account Number (PAN) of a payment card. Its primary role is to store card information securely and be used for future transactions without exposing sensitive data. When a user saves a card on a Pine Labs Online platform, the system generates a Token ID. This ID can then be used for transactions, subscriptions, or recurring payments, without the need to store or transmit the actual card number. ### Service provider token A Service Provider Token is a specific token that is created and managed by an external entity - either a card network (e.g., Visa, Mastercard) or a card issuer (e.g., a bank). This token is essentially a representation of the card created by the third-party service provider to replace the actual PAN. The Service Provider Token is linked to the Token ID within the platform, but it reflects the external tokenization source used for the token creation. *** ### [Prerequisite] Sign Up on the Dashboard & Get 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. 2. **Verify Your Email** — Confirm your email address through the verification link sent to your inbox. 3. **Find Your Credentials** — Once logged in, navigate to Settings → API Keys to generate your test-mode API key and secret. 4. **Explore the Dashboard** — Use the dashboard to view test payments, refunds, settlements, and webhook configurations before going live. Once your account is ready, you can immediately start integrating hosted checkout, custom checkout, payment links, tokenization, and other Pine Labs Online payment solutions using the UAT environment — no production credentials required. > 🚧 Watch Out > > - To Integrate with Pine Labs Online custom checkout flow you must have a PCI compliance certificate. *** ## Integration Steps Follow the below steps to integrate with Pine Labs Online custom checkout APIs in your application. 1. [Generate Token](#generate-token) 2. [Create Customer](#create-customer) 3. [Create Order](#create-order) 4. [Create Payment](#create-payment) 5. [Handle Payment](#handle-payment) 1. [Store Payment Details on Your Server](#store-payment-details-on-your-server) 2. [Verify Payment Signature](#verify-payment-signature) 6. [Capture Order](#capture-order) 7. [Cancel Order](#cancel-order) > 📘 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. 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 '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 ' { "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 '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 ' { "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 Customer

Use this API to create a customer. Below are the sample requests and sample response for a Create Customer API. ```curl cURL - UAT curl --request POST \ --url https://pluraluat.v2.pinepg.in/api/v1/customer \ --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 ' { "merchant_customer_reference": "", "first_name": "Kevin", "last_name": "Bob", "country_code": "91", "mobile_number": "9876543210", "email_id": "kevin.bob@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": "shipping" }, "gstin": "", "merchant_metadata": { "key1": "XX", "key2": "DOF" } } ' ``` ```curl cURL - PROD curl --request POST \ --url https://api.pluralpay.in/api/v1/customer \ --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 ' { "merchant_customer_reference": "", "first_name": "Kevin", "last_name": "Bob", "country_code": "91", "mobile_number": "9876543210", "email_id": "kevin.bob@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": "shipping" }, "gstin": "", "merchant_metadata": { "key1": "XX", "key2": "DOF" } } ' ``` ```json Sample Response { "customer_id": "cust-v1-0811030624-aa-RBDgpR", "merchant_customer_reference": "", "first_name": "Kevin", "last_name": "Bob", "country_code": "91", "mobile_number": "9876543210", "email_id": "kevin.bob@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": "shipping" }, "gstin": "", "merchant_metadata": { "key1": "XX", "key2": "DOF" }, "status": "INACTIVE", "created_at": "2024-10-04T13:11:29.645591Z", "updated_at": "2024-10-04T13:11:29.645657Z" } ``` Refer to our [Create Customer API](/api/customers/create-customer) documentation to learn more. > 📘 Note: > > - Alternatively, you can create a customer without using the Create Customer API by providing either the `merchant_customer_reference` or the `mobile_number` along with the `country_code` in our Create Order API. ***

3. Create Order

To create an Order, use our Create Order API, for authentication use the generated access token in the headers of the API request. Below are the sample requests and response for a Create Order API. ```curl cURL - UAT curl --request POST \ --url https://pluraluat.v2.pinepg.in/api/pay/v1/orders\ --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 ' { "merchant_order_reference": 112345, "order_amount": { "value": 1100, "currency": "INR" }, "pre_auth": false, "notes": "order1", "callback_url":"https://sample-callback-url", "failure_callback_url": "https://sample-failure-callback-url", "purchase_details": { "customer": { "email_id": "kevin.bob@example.com", "first_name": "Kevin", "last_name": "Bob", "customer_id": "123456", "mobile_number": "9876543210", "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" } }, "merchant_metadata": { "key1": "DD", "key2": "XOF" } } } ' ``` ```curl cURL - PROD curl --request POST \ --url https://api.pluralpay.in/api/pay/v1/orders \ --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 ' { "merchant_order_reference": 112345, "order_amount": { "value": 1100, "currency": "INR" }, "pre_auth": false, "notes": "order1", "callback_url":"https://sample-callback-url", "failure_callback_url": "https://sample-failure-callback-url", "purchase_details": { "customer": { "email_id": "kevin.bob@example.com", "first_name": "Kevin", "last_name": "Bob", "customer_id": "123456", "mobile_number": "9876543210", "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" } }, "merchant_metadata": { "key1": "DD", "key2": "XOF" } } } ' ``` ```json Sample Response { "data": { "order_id": "v1-4405071524-aa-qlAtAf", "merchant_order_reference": "112345", "type": "CHARGE", "status": "CREATED", "merchant_id": "104359", "order_amount": { "value": 1100, "currency": "INR" }, "pre_auth": false, "notes": "order1", "callback_url":"https://sample-callback-url", "failure_callback_url": "https://sample-failure-callback-url", "purchase_details": { "customer": { "email_id": "kevin.bob@example.com", "first_name": "Kevin", "last_name": "Bob", "customer_id": "123456", "mobile_number": "9876543210", "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" } }, "merchant_metadata": { "key1": "DD", "key2": "XOF" } }, "payments": [], "created_at": "2024-07-15T05:44:51.174Z", "updated_at": "2024-07-15T05:44:51.174Z" } } ``` > 📘 Important > > - To update the customer information, use our [Updated Customer API](/api/customers/update-customer). > - If both `customer_id` and at least one of `mobile_number` or `merchant_customer_reference` are provided, we first validate the `customer_id` in our database. If it exists, we return the same customer_id without creating a new one. Refer to our [Create Order API](/api/orders/create-order) documentation to learn more. ***

4. Create Payment

With Pine Labs Online you can process a payment for the below. ### 4.1. Save Card For First Time User To create a save card payment for first time user, use our Create Payment API, use the `order_id` returned in the response of a Create Order API to link the payment against an order. Below are the sample requests and sample response for a Save Card Payment API. ```curl cURL - UAT curl --request POST \ --url 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": "CARD", "payment_amount": { "value": 50000, "currency": "INR" }, "payment_option": { "card_details": { "save": true, "name": "Kevin Bob", "card_number": "4895489548954895", "cvv": "065", "expiry_month": "12", "expiry_year": "2030" } } } ] }' ``` ```curl cURL - PROD curl --request POST \ --url 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": "CARD", "payment_amount": { "value": 50000, "currency": "INR" }, "payment_option": { "card_details": { "save": true, "name": "Kevin Bob", "card_number": "4895489548954895", "cvv": "065", "expiry_month": "12", "expiry_year": "2030" } } } ] }' ``` ```json Sample Response { "data": { "order_id": "v1-4405071524-aa-qlAtAf", "merchant_order_reference": "112345", "type": "CHARGE", "status": "PENDING", "challenge_url": "https://api.pluralpay.in/web/auth/landing/?token=S50%2B0lOoYHlA03j3y8Of4%2BZEzhD8MuFFLKP6NXx9uiaBBXlNhpCRA4wqkPd%2Bs9eRz7H", "merchant_id": "123456", "order_amount": { "value": 1100, "currency": "INR" }, "pre_auth": false, "notes": "order1", "callback_url":"https://sample-callback-url", "failure_callback_url": "https://sample-failure-callback-url", "purchase_details": { "customer": { "email_id": "kevin.bob@example.com", "first_name": "Kevin", "last_name": "Bob", "customer_id": "123456", "mobile_number": "9876543210", "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" } }, "merchant_metadata": { "key1": "value1", "key2": "value2" } }, "payments": [ { "id": "v1-5307071124-aa-dmkVNf-cc-c", "merchant_payment_reference": "008cf04b-a770-4777-854e-b1e6c1230609", "status": "PENDING", "payment_amount": { "value": 1100, "currency": "INR" }, "payment_method": "CARD", "payment_option": { "card_data": { "card_type": "CREDIT", "network_name": "VISA", "issuer_name": "KOTAK", "card_category": "CONSUMER", "country_code": "IND", "token_txn_type": "ALT_TOKEN" } }, "created_at": "2024-07-11T07:53:43.358Z", "updated_at": "2024-07-11T07:56:18.044Z" } ], "created_at": "2024-07-11T07:53:43.358Z", "updated_at": "2024-07-11T07:56:18.044Z" } } ``` Refer to our [Create Payment API](/api/card-payments/create-payment) documentation to learn more. ### 4.2. Process Payment using Token Saved Use our Create Payment API to process payment using token saved on Pine Labs Online, use the `order_id` returned in the response of a Create Order API to link the payment against an order. Below are the sample requests and sample response for a Card Payment API. ```curl cURL - UAT curl --request POST \ --url 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": "CARD", "payment_amount": { "value": 50000, "currency": "INR" }, "payment_option": { "card_token_details": { "token_id": "token-v1-0811030624-bb-RBDgpR", "cvv": "065", "token_txn_type": "NETWORK_TOKEN" } } } ] } ' ``` ```curl cURL - PROD curl --request POST \ --url 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": "CARD", "payment_amount": { "value": 50000, "currency": "INR" }, "payment_option": { "card_token_details": { "token_id": "token-v1-0811030624-bb-RBDgpR", "cvv": "065", "token_txn_type": "NETWORK_TOKEN" } } } ] } ' ``` ```json Sample Response { "data": { "order_id": "v1-4405071524-aa-qlAtAf", "merchant_order_reference": "112345", "type": "CHARGE", "status": "PENDING", "challenge_url": "https://api.pluralpay.in/web/auth/landing/?token=S50%2B0lOoYHlA03j3y8Of4%2BZEzhD8MuFFLKP6NXx9uiaBBXlNhpCRA4wqkPd%2Bs9eRz7H", "merchant_id": "123456", "order_amount": { "value": 1100, "currency": "INR" }, "pre_auth": false, "notes": "order1", "callback_url":"https://sample-callback-url", "failure_callback_url": "https://sample-failure-callback-url", "purchase_details": { "customer": { "email_id": "kevin.bob@example.com", "first_name": "Kevin", "last_name": "Bob", "customer_id": "123456", "mobile_number": "9876543210", "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" } }, "merchant_metadata": { "key1": "value1", "key2": "value2" } }, "payments": [ { "id": "v1-5307071124-aa-dmkVNf-cc-c", "merchant_payment_reference": "008cf04b-a770-4777-854e-b1e6c1230609", "status": "PENDING", "payment_amount": { "value": 1100, "currency": "INR" }, "payment_method": "CARD", "payment_option": { "card_data": { "card_type": "CREDIT", "network_name": "VISA", "issuer_name": "KOTAK", "card_category": "CONSUMER", "country_code": "IND", "token_txn_type": "ALT_TOKEN" } }, "created_at": "2024-07-11T07:53:43.358Z", "updated_at": "2024-07-11T07:56:18.044Z" } ], "created_at": "2024-07-11T07:53:43.358Z", "updated_at": "2024-07-11T07:56:18.044Z" } } ``` Refer to our [Create Payment API](/api/card-payments/create-payment) documentation to learn more. ### 4.3. Process Payment on Pine Labs Online with token created on another PA/PG To process the payment on Pine Labs Online with token created on another PA/PG follow the below steps. #### 4.3.1. Create Payment Use our Create Payment API to process payment using token created on another PA/PG, use the `order_id` returned in the response of a Create Order API to link the payment against an order. Below are the sample requests and sample response for a Card Payment API. ```curl cURL - UAT curl --request POST \ --url 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": "CARD", "payment_amount": { "value": 10000, "currency": "INR" }, "pre_auth": false, "payment_option": { "card_token_details": { "name": "SOME_RANDOM_NAME", "last4_digit": "4026", "cvv": "123", "expiry_month": "03", "expiry_year": "2030", "token": "4122980000000008", "cryptogram": "AgAAAGQkm6LscccAAAA5gz4AAAA=", "token_txn_type": "ALT_TOKEN" } }, "merchant_payment_reference": "28dbc00d-3091-47ea-83a8-33004276555f" } ] } ' ``` ```curl cURL - PROD curl --request POST \ --url 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": "CARD", "payment_amount": { "value": 50000, "currency": "INR" }, "payment_option": { "card_token_details": { "token_id": "token-v1-0811030624-bb-RBDgpR", "cvv": "065", "token_txn_type": "NETWORK_TOKEN" } } } ] } ' ``` ```json Sample Response { "data": { "order_id": "v1-4405071524-aa-qlAtAf", "merchant_order_reference": "112345", "type": "CHARGE", "status": "PENDING", "challenge_url": "https://api.pluralpay.in/web/auth/landing/?token=S50%2B0lOoYHlA03j3y8Of4%2BZEzhD8MuFFLKP6NXx9uiaBBXlNhpCRA4wqkPd%2Bs9eRz7H", "merchant_id": "123456", "order_amount": { "value": 1100, "currency": "INR" }, "pre_auth": false, "notes": "order1", "callback_url":"https://sample-callback-url", "failure_callback_url": "https://sample-failure-callback-url", "purchase_details": { "customer": { "email_id": "kevin.bob@example.com", "first_name": "Kevin", "last_name": "Bob", "customer_id": "123456", "mobile_number": "9876543210", "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" } }, "merchant_metadata": { "key1": "value1", "key2": "value2" } }, "payments": [ { "id": "v1-5307071124-aa-dmkVNf-cc-c", "merchant_payment_reference": "008cf04b-a770-4777-854e-b1e6c1230609", "status": "PENDING", "payment_amount": { "value": 1100, "currency": "INR" }, "payment_method": "CARD", "payment_option": { "card_data": { "card_type": "CREDIT", "network_name": "VISA", "issuer_name": "KOTAK", "card_category": "CONSUMER", "country_code": "IND", "token_txn_type": "ALT_TOKEN" } }, "created_at": "2024-07-11T07:53:43.358Z", "updated_at": "2024-07-11T07:56:18.044Z" } ], "created_at": "2024-07-11T07:53:43.358Z", "updated_at": "2024-07-11T07:56:18.044Z" } } ``` 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: > > - 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. > 📘 Important: > > - With pre-authorization set to true, you can capture or cancel a payment for an order. ***

6. Capture Order

Use this API to capture the payment against an order. On successful capture of an order the order status is updated as `processed`. Shown below are the sample requests and sample response for a Capture Order API. ```curl cURL - UAT curl --request PUT \ --url https://pluraluat.v2.pinepg.in/api/pay/v1/orders/order_id/capture \ --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 ' { "merchant_capture_reference": "merchant-capture-ref-r4y", "capture_amount": { "value": 4000, "currency": "INR" } } ' ``` ```curl cURL - PROD curl --request PUT \ --url https://api.pluralpay.in/api/pay/v1/orders/order_id/capture \ --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 ' { "merchant_capture_reference": "merchant-capture-ref-r4y", "capture_amount": { "value": 4000, "currency": "INR" } } ' ``` ```json Sample Response { "data": { "order_id": "v1-5757575757-aa-hU1rUd", "merchant_order_reference": "f4548bbf-a029-43d3-9209-e3385c80b1e9", "type": "CHARGE", "status": "PROCESSED", "merchant_id": "123456", "order_amount": { "value": 1100, "currency": "INR" }, "pre_auth": true, "notes": "order1", "callback_url":"https://sample-callback-url", "failure_callback_url": "https://sample-failure-callback-url", "purchase_details": { "customer": { "email_id": "kevin.bob@example.com", "first_name": "Kevin", "last_name": "Bob", "customer_id": "232323", "mobile_number": "9876543210", "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" } }, "merchant_metadata": { "key1": "DD", "key2": "XOF" } }, "payments": [ { "id": "v1-1111071924-aa-zzSkOA-cc-G", "status": "PROCESSED", "payment_amount": { "value": 1100, "currency": "INR" }, "payment_method": "CARD", "payment_option": { "card_data": { "card_type": "CREDIT", "network_name": "VISA", "issuer_name": "NONE", "card_category": "CONSUMER", "country_code": "IND", "token_txn_type": "ALT_TOKEN" } }, "acquirer_data": { "approval_code": "000000", "acquirer_reference": "202456643801053", "rrn": "420145000226" }, "capture_data": [ { "merchant_capture_reference": "f31d8c60-0dc8-4788-a577-5ced930cc175", "capture_amount": { "value": 1100, "currency": "INR" }, "created_at": "2024-07-19T11:13:21.523Z" } ], "created_at": "2024-07-19T11:11:48.944Z", "updated_at": "2024-07-19T11:13:23.962Z" } ], "created_at": "2024-07-19T11:11:48.944Z", "updated_at": "2024-07-19T11:13:23.962Z" } } ``` Refer to our [Capture Order API](/api/orders/capture-order) documentation to learn more. ***

7. Cancel Order

Use this API to cancel the payment against an order. Shown below are the sample requests and sample response for a Cancel Order API. ```curl cURL - UAT curl --request PUT \ --url https://pluraluat.v2.pinepg.in/api/pay/v1/orders/order_id/cancel \ --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' ``` ```curl cURL - PROD curl --request PUT \ --url https://api.pluralpay.in/api/pay/v1/orders/{order_id}/cancel \ --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' ``` ```json Sample Response { "data": { "order_id": "v1-5757575757-aa-hU1rUd", "merchant_order_reference": "2177120b-3be1-4330-a15f-53ce14d19841", "type": "CHARGE", "status": "CANCELLED", "merchant_id": "123456", "order_amount": { "value": 50000, "currency": "INR" }, "pre_auth": true, "notes": "order1", "callback_url":"https://sample-callback-url", "failure_callback_url": "https://sample-failure-callback-url", "purchase_details": { "customer": { "email_id": "kevin.bob@example.com", "first_name": "Kevin", "last_name": "Bob", "customer_id": "232323", "mobile_number": "9876543210", "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" } }, "merchant_metadata": { "key1": "DD", "key2": "XOF" } }, "payments": [ { "id": "v1-2711071924-aa-VxIzq1-cc-Z", "status": "CANCELLED", "payment_amount": { "value": 1100, "currency": "INR" }, "payment_method": "CARD", "payment_option": { "card_data": { "card_type": "CREDIT", "network_name": "VISA", "issuer_name": "NONE", "card_category": "CONSUMER", "country_code": "IND", "token_txn_type": "ALT_TOKEN" } }, "acquirer_data": { "approval_code": "000000", "acquirer_reference": "202456644249243", "rrn": "420123000239" }, "created_at": "2024-07-19T11:27:55.664Z", "updated_at": "2024-07-19T11:28:52.487Z" } ], "created_at": "2024-07-19T11:27:55.664Z", "updated_at": "2024-07-19T11:28:52.487Z" } } ``` Refer to our [Cancel Order API](/api/orders/cancel-order) documentation to learn more.