---
title: Custom Checkout Integration Steps
slug: custom-checkout/integration-steps
excerpt: >-
  Step-by-step guide to integrate Pine Labs Seamless Checkout. Create orders,
  submit payments per method, handle 3DS/OTP challenges, verify signatures, and
  manage transactions.
hidden: false
sidebar_order: 3
metadata:
  title: Custom Checkout Integration Steps | Pine Labs
  description: >-
    Custom Checkout integration guide: create orders, submit payments per
    method, handle 3DS/OTP challenges, verify signatures and manage
    transactions.
  keywords: >-
    custom checkout integration, seamless checkout steps, custom payment
    integration, PCI integration, client-side payment flow
  robots: index
sidebar_label: Integration Steps
---

## Integration Steps
Learn how you can integrate with Pine Labs Online APIs to start accepting payments on your website.

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

1. [Generate Token](#generate-token)
2. [Create Order](#create-order)
3. [Create Payment](#create-payment)
4. [Handle Payment](#handle-payment)
   1. [Store Payment Details on Your Server](#store-payment-details)
   2. [Verify Payment Signature](#verify-signature)
5. [Capture Order](#capture-order)
6. [Cancel Order](#cancel-order)

> 📘 Note
> 
> - Ensure you store your `client_id` and `client_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.

> 🚧 Watch Out
> 
> - To Integrate with Pine Labs Online seamless checkout flow you must have a PCI compliance certificate.
> - Some payment methods also support additional checkout options. These options are not part of the standard payment and may require additional APIs or feature enablement.

***

<h2 id="generate-token">1. Generate Token</h2>

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.

***

<h2 id="create-order">2. Create Order</h2>

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 --location '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,
  "allowed_payment_methods": [
    "CARD",
    "UPI",
    "NETBANKING",
    "POINTS",
    "WALLET"
  ],
  "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":"H.No 15, Sector 17",
        "address2":"",
        "address3":"",
        "pincode":"61232112",
        "city":"CHANDIGARH",
        "state":"PUNJAB",
        "country":"INDIA",
				"full_name": "Kevin Bob",
				"adddress_type": "Home",
				"address_category": "billing"
      },
      "shipping_address":{
        "address1":"H.No 15, Sector 17",
        "address2":"",
        "address3":"",
        "pincode":"144001123",
        "city":"CHANDIGARH",
        "state":"PUNJAB",
        "country":"INDIA",
				"full_name": "Kevin Bob",
				"adddress_type": "Home",
				"address_category": "shipping"
      }
    },
    "merchant_metadata": {
      "key1": "DD",
      "key2": "XOF"
    }
  }
}
'
```
```curl cURL - PROD
curl --location '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,
  "allowed_payment_methods": [
    "CARD",
    "UPI",
    "NETBANKING",
    "POINTS",
    "WALLET"
  ],
  "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":"H.No 15, Sector 17",
        "address2":"",
        "address3":"",
        "pincode":"61232112",
        "city":"CHANDIGARH",
        "state":"PUNJAB",
        "country":"INDIA",
				"full_name": "Kevin Bob",
				"adddress_type": "Home",
				"address_category": "billing"
      },
      "shipping_address":{
        "address1":"H.No 15, Sector 17",
        "address2":"",
        "address3":"",
        "pincode":"144001123",
        "city":"CHANDIGARH",
        "state":"PUNJAB",
        "country":"INDIA",
				"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,
    "allowed_payment_methods": [
      "CARD",
      "UPI",
      "NETBANKING",
      "POINTS",
      "WALLET"
    ],
    "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":"H.No 15, Sector 17",
        "address2":"",
        "address3":"",
        "pincode":"61232112",
        "city":"CHANDIGARH",
        "state":"PUNJAB",
        "country":"INDIA",
				"full_name": "Kevin Bob",
				"adddress_type": "Home",
				"address_category": "billing"
      },
      "shipping_address":{
        "address1":"H.No 15, Sector 17",
        "address2":"",
        "address3":"",
        "pincode":"144001123",
        "city":"CHANDIGARH",
        "state":"PUNJAB",
        "country":"INDIA",
				"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"
  }
}
```


Refer to our [Create Order API](/api/orders/create-order) documentation to learn more.

***

<h2 id="create-payment">3. Create Payment</h2>

To create a payment, 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 Card Payment API.

```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": [
    {
      "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"
        },
        "additional_payment_details": {
              "is_bank_acs_flow": true
        }
      }
    }
  ]
}
'
```
```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": [
    {
      "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"
        },
        "additional_payment_details": {
              "is_bank_acs_flow": true
        }
      }
    }
  ]
}
'
```
```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,
    "allowed_payment_methods":[
      "CARD",
      "UPI",
      "NETBANKING",
      "POINTS",
      "WALLET"
    ],
    "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":"H.No 15, Sector 17",
        "address2":"",
        "address3":"",
        "pincode":"61232112",
        "city":"CHANDIGARH",
        "state":"PUNJAB",
        "country":"INDIA",
				"full_name": "Kevin Bob",
				"adddress_type": "Home",
				"address_category": "billing"
      },
      "shipping_address":{
        "address1":"H.No 15, Sector 17",
        "address2":"",
        "address3":"",
        "pincode":"144001123",
        "city":"CHANDIGARH",
        "state":"PUNJAB",
        "country":"INDIA",
				"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",
            "last4_digit": "0001",
            "is_native_otp_eligible": true,
            "card_holder_name": "Kevin Bob",
          }
        },
        "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.

> 📘 Note:
> 
> When the pre-authorization is set to true you can capture the payment after successful delivery or service.

The above API example includes a sample request and response for a card payment. If your customer chooses another payment method, such as UPI, netbanking, wallet, or any other supported option, you must pass the payload applicable to that payment method.

Payment method-specific request and response samples are listed below:
| Payment Method | Description |
| --- | --- |
| [Card Payments](/api/card-payments) | Process card-based payments including OTP authorization. |
| [UPI Payments](/api/upi-payments) | Process UPI payments via intent and QR flows. |
| [NetBanking](/api/netbanking) | Process net banking payments. |
| [Wallets](/api/wallet) | Process wallet-based payments. |
| [Pay by Points](/api/pay-by-points) | Check balance and create payments using reward points. |
| [Buy Now and Pay Later Payments](/api/bnpl) | Check eligibility and process Buy Now Pay Later payments. |
| [EMI Payments](/api/affordability-suite/create-payment) | Discover offers, validate EMI eligibility, and process EMI payments. |
| [Brand Wallet Payments]() | Process payments using Brand Wallet balance and add money to Brand Wallets via gift cards or UPI. |


## Native OTP Flow (Optional for Card Payments)
<p>Native OTP enables merchants to provide a seamless in-app or on-site card authentication experience by allowing customers to enter the One-Time Password (OTP) directly within the merchant's checkout instead of being redirected to the issuer's Access Control Server (ACS).</p>
<p>The Native OTP flow extends the standard Custom Checkout payment flow and is initiated after the Create Payment API. Eligibility for Native OTP is determined as part of the create_payment API response.</p>
<details><summary>Click here for Integration Details</summary>

> 📘 Note:
> 
> - Follow the steps below to process the transaction using the **Native OTP Flow**. If you are using the standard redirect-based authentication flow, you can use the `chanllenge_url` to continue with the standard ACS [Access Control Server] flow.

### 3.1 Native OTP Eligibility

After invoking the Create Payment API, merchants must validate the **is_native_otp_eligible** parameter returned in the response.

#### Response Parameter
Merchants must validate the following parameter in the **create_payment** response:

```curl cURL - UAT
   "is_native_otp_eligible": true
```

| Parameter Value | Meaning |
|-----------------|---------|
| `true` | Native OTP is supported for the transaction. |
| `false` | Native OTP is not supported for the transaction. |
---

### 3.2. Generate OTP

Use this API to generate and send an OTP to the registered mobile number.

Below are the sample requests and sample response for a Generate OTP API.

```curl cURL - UAT
curl --request POST \
     --url https://pluraluat.v2.pinepg.in/api/pay/v1/otp/generate \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "payment_id": "v1-250219120455-aa-Lc5FbR-cc-a"
}
'
```
```curl cURL - PROD
curl --request POST \
     --url https://api.pluralpay.in/api/pay/v1/otp/generate \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "payment_id": "v1-250219120455-aa-Lc5FbR-cc-a"
}
'
```
```json Sample Response
{
  "next": [
    "SUBMIT_OTP",
    "RESEND_OTP"
  ],
  "meta_data": {
    "resend_after": "180"
  }
}
```

---

### 3.3. Submit OTP

Use this API to submit the OTP for verification.

Below are the sample requests and sample response for a Submit OTP API.

```curl cURL - UAT
curl --request POST \
     --url https://pluraluat.v2.pinepg.in/api/pay/v1/otp/submit \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "payment_id": "v1-250219120455-aa-Lc5FbR-cc-a",
  "otp": 1234
}
'
```
```curl cURL - PROD
curl --request POST \
     --url https://api.pluralpay.in/api/pay/v1/otp/submit \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "payment_id": "v1-250219120455-aa-Lc5FbR-cc-a",
  "otp": 1234
}
'
```
```json Sample Response

{  "status": "SUCCESS",  
   "next": ["POLL"]
}
```

---

### 3.4. Resend OTP

Use this API to resend a OTP to the registered mobile number.

Below are the sample requests and sample response for a Resend OTP API.

```curl cURL - UAT
curl --request POST \
     --url https://pluraluat.v2.pinepg.in/api/pay/v1/otp/resend \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "payment_id": "v1-250219120455-aa-Lc5FbR-cc-a"
}
'
```
```curl cURL - PROD
curl --request POST \
     --url https://api.pluralpay.in/api/pay/v1/otp/resend \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "payment_id": "v1-250219120455-aa-Lc5FbR-cc-a"
}
'
```
```json Sample Response
{
  "status": "SUCCESS",
  "next": [
    "SUBMIT_OTP",
    "RESEND_OTP"
  ],
  "meta_data": {
    "resend_after": "180"
  }
}
```

</details>

***

## Decoupled Authentication Flow (Optional)
<p>Authenticate payments using your own 3DS provider and submit the authentication results to Pine Labs for payment authorization.</p>
<details><summary>Click here for Integration Details</summary>

> 📘 Note:
> 
> - Build a fully customized payment experience using Pine Labs APIs. Control checkout design and Decoupled Authentication flows while Pine Labs securely handles payment processing and authorization.

### 3.1. Payment Authorize

Use this API to submit an authorization request for a transaction that has already completed customer authentication through a third-party 3DS provider.

Below are the sample requests and sample response for a Payment Authorize API.

```curl cURL - UAT
curl --request POST \
     --url https://pluraluat.v2.pinepg.in/api/pay/v1/orders/{orderId}/payments/{paymentId}/authorize \
     --header 'Authorization: Bearer <access_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 '
{
  "decrypted_card_details": {
    "pan": "",
    "cvv": "",
    "card_holder_name": "",
    "cryptogram": "",
    "token": "",
    "expiration_month": "",
    "expiration_year": "",
    "eci": "",
    "cavv": ""
  },
  "acquirer_payment_details": {
    "directory_server_transaction_id": "",
    "acs_transaction_id": "",
    "three_ds_server_transaction_id": "",
    "three_ds_version": ""
  },
  "authentication_type": ""
}
'
```
```curl cURL - PROD
curl --request POST \
     --url https://api.pluralpay.in/api/pay/v1/orders/{orderId}/payments/{paymentId}/authorize \
     --header 'Authorization: Bearer <access_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 '
{
  "decrypted_card_details": {
    "pan": "",
    "cvv": "",
    "card_holder_name": "",
    "cryptogram": "",
    "token": "",
    "expiration_month": "",
    "expiration_year": "",
    "eci": "",
    "cavv": ""
  },
  "acquirer_payment_details": {
    "directory_server_transaction_id": "",
    "acs_transaction_id": "",
    "three_ds_server_transaction_id": "",
    "three_ds_version": ""
  },
  "authentication_type": ""
}
'
```
```json Sample Response
{
  "data": {
    "order_id": "v1-260310084155-aa-CR55rj",
    "merchant_order_reference": "66bf0223-d038-486b-bf06-83624c465204",
    "type": "CHARGE",
    "status": "PROCESSED",
    "callback_url": "https://api-staging.pluralonline.com/api/v3/checkout-bff/form/handler",
    "failure_callback_url": "https://api-staging.pluralonline.com/api/v3/checkout-bff/form/handler",
    "merchant_id": "123212",
    "order_amount": {
      "value": 500000,
      "currency": "INR"
    },
    "pre_auth": false,
    "part_payment": false,
    "allowed_payment_methods": [],
    "purchase_details": {
      "customer": {
        "email_id": "c.b@gmail.com",
        "first_name": "alex",
        "last_name": "hales",
        "customer_id": "cust-v1-260130070316-aa-52zBqW",
        "mobile_number": "9111199932",
        "country_code": "91",
        "billing_address": {
          "address1": "H.No 15, Sector 17",
          "pincode": "61232112",
          "city": "CHANDIGARH",
          "state": "PUNJAB",
          "country": "INDIA"
        },
        "shipping_address": {
          "address1": "H.No 15, Sector 17",
          "address2": "string",
          "address3": "string",
          "pincode": "144001123",
          "city": "CHANDIGARH",
          "state": "PUNJAB",
          "country": "INDIA"
        },
        "is_edit_customer_details_allowed": false,
        "status": "ACTIVE",
        "created_at": "2026-01-30T07:03:16.282100Z",
        "updated_at": "2026-03-06T07:17:52.079224Z"
      },
      "merchant_metadata": {
        "key1": "value1",
        "key2": "value2"
      }
    },
    "payments": [
      {
        "id": "v1-260310084155-aa-CR55rj-cc-a",
        "merchant_payment_reference": "55598381-9056-4e3a-bb51-e788b8c755e9",
        "status": "PROCESSED",
        "payment_amount": {
          "value": 500000,
          "currency": "INR"
        },
        "challenge_url": "https://pluraluat.v2.pinepg.in/web/auth/landing/?token=S50zxn%2FUxkQECxdG5IeHfE2zMvS1U%2BZRS6tLrW%2F6Kpc3JPusSkggR5TJgirhG0sg%2FkI",
        "payment_method": "CARD",
        "payment_option": {
          "card_data": {
            "card_type": "CREDIT",
            "network_name": "VISA",
            "issuer_name": "ICICI BANK LIMITED",
            "card_category": "Consumer",
            "country_code": "IND",
            "token_txn_type": "ALT_TOKEN",
            "last4_digit": "1091",
            "is_native_otp_eligible": true,
            "card_holder_name": "ALEX HALES"
          }
        },
        "acquirer_data": {
          "approval_code": "831000",
          "acquirer_reference": "7731321304096602603812",
          "rrn": "606908215125",
          "is_aggregator": true,
          "acquirer_name": "Cyber_Source_AXIS"
        },
        "created_at": "2026-03-10T08:42:00.235Z",
        "updated_at": "2026-03-10T08:42:10.839Z"
      }
    ],
    "created_at": "2026-03-10T08:41:55.811Z",
    "updated_at": "2026-03-10T08:42:10.840Z",
    "integration_mode": "SEAMLESS",
    "payment_retries_remaining": 9,
    "is_domestic_txn_for_risk_enabled": false,
    "is_numeric_id_merchant_order": false,
    "is_v2_emi_transaction": false
  }
}
```

Refer to our [Payment Authorize API](/api/card-payments/decoupled-auth-z) documentation to learn more.

</details>

---

<h2 id="handle-payment">4. Handle Payment</h2>

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

<h3 id="store-payment-details">4.1 Store Payment Details on Your Server</h3>

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"
}
```

<h3 id="verify-signature">4.2 Verify Payment Signature</h3>

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>";
        String secretKey = "<secret_key>";  // 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=<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.

***

<h2 id="capture-order">5. Capture Order</h2>

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,
    "allowed_payment_methods":[
      "CARD",
      "UPI",
      "NETBANKING",
      "POINTS",
      "WALLET"
    ],
    "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":"H.No 15, Sector 17",
        "address2":"",
        "address3":"",
        "pincode":"61232112",
        "city":"CHANDIGARH",
        "state":"PUNJAB",
        "country":"INDIA",
				"full_name": "Kevin Bob",
				"adddress_type": "Home",
				"address_category": "billing"
      },
      "shipping_address":{
        "address1":"H.No 15, Sector 17",
        "address2":"",
        "address3":"",
        "pincode":"144001123",
        "city":"CHANDIGARH",
        "state":"PUNJAB",
        "country":"INDIA",
				"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.

***

<h2 id="cancel-order">6. Cancel Order</h2>

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 <access_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Request-ID: c17ce30f-f88e-4f81-ada1-c3b4909ed235' \
  --header 'Request-Timestamp: 2026-06-01T00:00:00.000Z'
```
```curl cURL - PROD
curl --request PUT \
     --url https://api.pluralpay.in/api/pay/v1/orders/{order_id}/cancel \
     --header 'Authorization: Bearer <access_token>' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Request-ID: c17ce30f-f88e-4f81-ada1-c3b4909ed235' \
  --header 'Request-Timestamp: 2026-06-01T00:00:00.000Z'
```
```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,
    "allowed_payment_methods":[
      "CARD",
      "UPI",
      "NETBANKING",
      "POINTS",
      "WALLET"
    ],
    "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":"H.No 15, Sector 17",
        "address2":"",
        "address3":"",
        "pincode":"61232112",
        "city":"CHANDIGARH",
        "state":"PUNJAB",
        "country":"INDIA",
				"full_name": "Kevin Bob",
				"adddress_type": "Home",
				"address_category": "billing"
      },
      "shipping_address":{
        "address1":"H.No 15, Sector 17",
        "address2":"",
        "address3":"",
        "pincode":"144001123",
        "city":"CHANDIGARH",
        "state":"PUNJAB",
        "country":"INDIA",
				"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.
