Product Guides

Tokenization

Learn how you can integrate with Pine Labs Online Token APIs to start accepting payments on your website without card details.

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

Integration Steps

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

  1. [Prerequisite] Generate Token
  2. Create Customer
  3. Create Order
  4. Create Payment
    1. Save Card For First Time User
    2. Process Payment using Token Saved
    3. Process Payment on Pine Labs Online with token created on another PA/PG
  5. Handle Payment
    1. Store Payment Details on Your Server
    2. Verify Payment Signature
  6. Capture Order
  7. 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.

🚧

Watch Out

  • To Integrate with Pine Labs Online seamless checkout flow you must have a PCI compliance certificate.

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

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "expires_in": 3600
}
Click here for request and response parameter information.
Request Parameters
Response Parameters

The table below lists the request parameters of our Generate Token API.

Parameter Type Description
client_id required string Unique client identifier in the Pine Labs Online database.

Example: a17ce30e-f88e-4f81-ada1-c3b4909ed232

Note: The Onboarding team has provided you with this information as part of the onboarding process.
client_secret required string Unique client secret key provided while onboarding.

Example: fgwei7egyhuggwp39w8rh

Note: The Onboarding team has provided you with this information as part of the onboarding process.
grant_type required string The grant type to generate an access token.

Accepted value: client_credentials

The table below lists the response parameters of our Generate Token API.

Parameter Type Description
access_token string The access token generated by the system.

• Minimum length: 1 character.
• Maximum length: 8192 characters.

Example: eyJhbGciOiJIUzI1NiIsIn

Note: Use this token in the authorization headers to authenticate Pine Labs Online APIs.
expires_at string Access duration timestamp.

Example: 2024-06-28T13:26:06.909140Z

Refer to our Generate Token API 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 --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": "[email protected]",
  "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"
  },
  "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"
  },
  "gstin": "",
  "merchant_metadata": {
    "key1": "XX",
    "key2": "DOF"
  }
}
'

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": "[email protected]",
  "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"
  },
  "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"
  },
  "gstin": "",
  "merchant_metadata": {
    "key1": "XX",
    "key2": "DOF"
  }
}
'

{
  "customer_id": "cust-v1-0811030624-aa-RBDgpR",
  "merchant_customer_reference": "",
  "first_name": "Kevin",
  "last_name": "Bob",
  "country_code": "91",
  "mobile_number": "9876543210",
  "email_id": "[email protected]",
  "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"
  },
  "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"
  },
  "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"
}
Click here for request and response parameter information.
Request Parameters
Response Parameters

The table below lists the request parameters of our Create Customer API.

Parameter Type Description
merchant_customer_reference required string Mandatory if the country_code and mobile_number are not provided.

Enter a unique identifier for the customer request.
  • Minimum: 1 characters.
  • Maximum: 50 characters.
Example: 1234567890

Supported characters:
  • A-Z
  • a-z
  • 0-9
  • -
  • _
first_name string Customer's first name.
  • Minimum length: 1 character.
  • Maximum length: 50 characters.
Example: Kevin
last_name string Customer's last name.
  • Minimum length: 1 character.
  • Maximum length: 50 characters.
Example: Bob
country_code string Mandatory if the merchant_customer_reference is not provided.

Country code of the registered mobile number.

Example: 91
mobile_number string Mandatory if the merchant_customer_reference is not provided.

Customer's mobile number.
  • Minimum length: 10 character.
  • Maximum length: 20 characters.
Example: 9876543210

Supported characters:
  • 0-9
email_id string Customer's email address.
  • Maximum length: 50 characters.
Example: [email protected]

Supported characters:
  • A-Z
  • a-z
  • 0-9
  • +
  • _
  • .
  • -
  • @
billing_address string An object that contains the details of the billing address.

Learn more about the billing_address child data.
shipping_address string An object that contains the shipping address details.

Learn more about the shipping_address child data.
gstin string Customers unique GSTIN.

Example: 28ABCDE1234F2Z6
merchant_metadata string An object of key value pair that can be used to store additional information.
  • Each pair cannot exceed 256 characters.
  • Maximum 10 key-value pairs.
Example: "key1": "DD"

Billing Address [Child Object]

The table below lists the various parameters in the billing_address child object. This is part of the Create Customer request object.

Parameter Type Description
address1stringCustomer's billing address1.
  • Max length: 100 characters.
Example: 10 Downing Street Westminster London
address2stringCustomer's billing address2.
  • Max length: 100 characters.
Example: Oxford Street Westminster London
address3stringCustomer's billing address3.
  • Max length: 100 characters.
Example: Baker Street Westminster London
pincodestringPincode of the billing address.
  • Min length: 6 characters.
  • Max length: 10 characters.
Example: 51524036
citystringCity of the billing address.
  • Max length: 50 characters.
Example: Westminster
statestringState of the billing address.
  • Max length: 50 characters.
Example: Westminster
countrystringCountry of the billing address.
  • Max length: 50 characters.
Example: London

Shipping Address [Child Object]

The table below lists the various parameters in the shipping_address child object. This is part of the Create Customer request object.

Parameter Type Description
address1stringCustomer's shipping address1.
  • Max length: 100 characters.
Example: 10 Downing Street Westminster London
address2stringCustomer's shipping address2.
  • Max length: 100 characters.
Example: Oxford Street Westminster London
address3stringCustomer's shipping address3.
  • Max length: 100 characters.
Example: Baker Street Westminster London
pincodestringPincode of the shipping address.
  • Min length: 6 characters
  • Max length: 10 characters.
Example: 51524036
citystringCity of the shipping address.
  • Max length: 50 characters.
Example: Westminster
statestringState of the shipping address.
  • Max length: 50 characters.
Example: Westminster
countrystringCountry of the shipping address.
  • Max length: 50 characters.
Example: London

The table below lists the various parameters returned in the orders response objects.

Parameter Type Description
customer_id string Unique identifier of the customer in the Pine Labs Online database.
  • Maximum length: 50 characters.
Example: cust-v1-0811030624-aa-RBDgpR
merchant_customer_reference string Unique identifier entered while creating a customer.
  • Minimum length: 1 character.
  • Maximum length: 50 characters.
Example: 82d57572-057c-4826-5775-385a52150554
first_name string Customer's first name.
  • Minimum length: 1 character.
  • Maximum length: 50 characters.
Example: Kevin
last_name string Customer's last name.
  • Minimum length: 1 character.
  • Maximum length: 50 characters.
Example: Bob
country_code string Country code of the registered mobile number.

Example: 91
mobile_number string Customer's mobile number.
  • Minimum length: 9 characters.
  • Maximum length: 20 characters.
Example: 9876543210

Supported characters:
  • 0-9
  • +
billing_address object An object that contains the details of the billing address.

Learn more about the billing_address child object.
shipping_address object An object that contains the shipping address details.

Learn more about the shipping_address child object.
gstin boolean Customer's unique GSTIN.

Example: 28ABCDE1234F2Z6
merchant_metadata object An object of key-value pair that can be used to store additional information.

Example: "key1": "DD"
status object Customer status.

Possible values:
  • Inactive: The customer profile is created but not yet activated.
  • Active: The customer is verified and can use saved tokens for transactions.
  • Suspended: The customer is temporarily restricted from transactions.
  • Deleted: The customer profile is removed and cannot be reactivated.
created_at string The ISO 8601 UTC Timestamp, when the create customer request was received by Pine Labs Online.

Example: 2024-10-04T13:11:29.645591Z
updated_at string The ISO 8601 UTC Timestamp, when the customer object is updated.

Example: 2024-10-04T13:11:29.645657Z

Billing Address [Child Object]

The table below lists the various parameters in the billing_address child object. This is part of the customer object.

Parameter Type Description
address1 string Customer's billing address1.
  • Maximum length: 100 characters.
Example: 10 Downing Street Westminster London
address2 string Customer's billing address2.
  • Maximum length: 100 characters.
Example: Oxford Street Westminster London
address3 string Customer's billing address3.
  • Maximum length: 100 characters.
Example: Baker Street Westminster London
pincode string Pincode of the billing address.
  • Minimum length: 6 characters.
  • Maximum length: 10 characters.
Example: 51524036

Supported characters:
  • 0-9
city string City of the billing address.
  • Maximum length: 50 characters.
Example: Westminster
state string State of the billing address.
  • Maximum length: 50 characters.
Example: Westminster
country string Country of the billing address.
  • Maximum length: 50 characters.
Example: London

Shipping Address [Child Object]

The table below lists the various parameters in the shipping_address child object. This is part of the customer object.

Parameter Type Description
address1 string Customer's shipping address1.
  • Maximum length: 100 characters.
Example: 10 Downing Street Westminster London
address2 string Customer's shipping address2.
  • Maximum length: 100 characters.
Example: Oxford Street Westminster London
address3 string Customer's shipping address3.
  • Maximum length: 100 characters.
Example: Baker Street Westminster London
pincode string Pincode of the shipping address.
  • Minimum length: 6 characters.
  • Maximum length: 10 characters.
Example: 51524036

Supported characters:
  • 0-9
city string City of the shipping address.
  • Maximum length: 50 characters.
Example: Westminster
state string State of the shipping address.
  • Maximum length: 50 characters.
Example: Westminster
country string Country of the shipping address.
  • Maximum length: 50 characters.
Example: London

Refer to our Create Customer API 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 --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": "[email protected]",
      "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"
      },
      "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"
      }
    },
    "merchant_metadata": {
      "key1": "DD",
      "key2": "XOF"
    }
  }
}
'

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": "[email protected]",
      "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"
      },
      "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"
      }
    },
    "merchant_metadata": {
      "key1": "DD",
      "key2": "XOF"
    }
  }
}
'

{
  "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": "[email protected]",
        "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"
        },
        "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"
        }
      },
      "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.
  • 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.
Click here for request and response parameter information.
Request Parameters
Response Parameters

The table below lists the request parameters of our create order API.

Parameter Type Description
merchant_order_reference required string Enter a unique identifier for the order request.

  • Minimum: 1 character.
  • Maximum: 50 characters.
Example: 1234567890

Supported characters:
  • A-Z
  • a-z
  • 0-9
  • -
  • _
order_amount required object An object that contains the transaction amount details.

Learn more about the order_amount child object.
pre_auth boolean The pre-authorization type.

Possible values:
  • false (default): When pre-authorization is not required.
  • true: When pre-authorization is needed.
allowed_payment_methods array of strings The type of payment methods you want to offer customers.

Accepted values:
  • CARD
  • UPI
  • POINTS
  • NETBANKING
  • WALLET
  • CREDIT_EMI
  • DEBIT_EMI
Example: CARD

Note: Before selecting a payment method, ensure it is configured for you.
notes string Note to show against an order.

Example: Order1
callback_url string URL to redirect customers based on order details.

Example: https://sample-callback-url
purchase_details object An object that contains purchase details.

Learn more about the purchase_details child object.

Order Amount [Child Object]

The table below lists the various parameters in the order_amount child object. This object is part of the create order request object.

Parameter Type Description
value required integer Transaction amount in Paisa.

  • Minimum value: 100 (₹1).
  • Maximum value: 100000000 (₹10 lakh).
Example: 1000
currency required string Type of currency.

Example: INR

Purchase Details [Child Object]

The table below lists the various parameters in the purchase_details child object. This object is part of the create order request object.

Parameter Type Description
customer object An object that contains the customer details.

Learn more about the customer child object.
merchant_metadata object An object of key-value pair that can be used to store additional information.

Example: "key1": "DD"

Customer [Child Object]

The table below lists the various parameters in the customer child object. This is part of the purchase_details object.

Parameter Type Description
email_id string Customer's email address.
  • Minimum length: 1 character.
  • Maximum length: 50 characters.
Example: [email protected]
first_name string Customer's first name.
  • Minimum length: 1 character.
  • Maximum length: 50 characters.
Example: Kevin
last_name string Customer's last name.
  • Minimum length: 1 character.
  • Maximum length: 50 characters.
Example: Bob
customer_id string Unique identifier of the customer in the Pine Labs Online database.
  • Minimum length: 1 character.
  • Maximum length: 19 characters.
Example: 123456
mobile_number string Customer's mobile number.
  • Minimum length: 9 characters.
  • Maximum length: 20 characters.
Example: 9876543210
billing_address object An object that contains the details of the billing address.

Learn more about our billing_address child object.
shipping_address object An object that contains the shipping address details.

Learn more about our shipping_address child object.

Billing Address [Child Object]

The table below lists the various parameters in the billing_address child object. This is part of the customer object.

Parameter Type Description
address1stringCustomer's billing address1.
  • Max length: 100 characters.
Example: 10 Downing Street Westminster London
address2stringCustomer's billing address2.
  • Max length: 100 characters.
Example: Oxford Street Westminster London
address3stringCustomer's billing address3.
  • Max length: 100 characters.
Example: Baker Street Westminster London
pincodestringPincode of the billing address.
  • Min length: 6 characters.
  • Max length: 10 characters.
Example: 51524036
citystringCity of the billing address.
  • Max length: 50 characters.
Example: Westminster
statestringState of the billing address.
  • Max length: 50 characters.
Example: Westminster
countrystringCountry of the billing address.
  • Max length: 50 characters.
Example: London

Shipping Address [Child Object]

The table below lists the various parameters in the shipping_address child object. This is part of the customer object.

Parameter Type Description
address1stringCustomer's shipping address1.
  • Max length: 100 characters.
Example: 10 Downing Street Westminster London
address2stringCustomer's shipping address2.
  • Max length: 100 characters.
Example: Oxford Street Westminster London
address3stringCustomer's shipping address3.
  • Max length: 100 characters.
Example: Baker Street Westminster London
pincodestringPincode of the shipping address.
  • Min length: 6 characters
  • Max length: 10 characters.
Example: 51524036
citystringCity of the shipping address.
  • Max length: 50 characters.
Example: Westminster
statestringState of the shipping address.
  • Max length: 50 characters.
Example: Westminster
countrystringCountry of the shipping address.
  • Max length: 50 characters.
Example: London

The table below lists the various parameters returned in the Create order response objects.

Parameter Type Description
order_id string Unique identifier of the order in the Pine Labs Online database.
  • Max length: 50 characters.
Example: v1-5757575757-aa-hU1rUd
merchant_order_reference string Unique identifier entered while creating an order.
  • Min length: 1 character.
  • Max length: 50 characters.
Example: 82d57572-057c-4826-5775-385a52150554
type string Payment type.

Possible values:
  • CHARGE
  • REFUND
status string Order status.

Possible values:
  • CREATED: When the order is successfully created.
  • PENDING: When the order is linked against a payment request.
  • PROCESSED: When the payment is received successfully.
  • AUTHORIZED: Only when pre_auth is true. When the payment is ready for authorization.
  • CANCELLED: When the payment gets cancelled.
  • ATTEMPTED: When the payment is unsuccessful due to incorrect OTP. You can retry OTP
  • FAILED: Payment acceptance failed for reasons such as cancel transactions, maximum retries for OTP verification etc.
  • FULLY_REFUNDED: When the payment is completely refunded.
  • PARTIALLY_REFUNDED: When the partial refund is successful.
challenge_url string Use the generated challenge_url to accept payment.

Note: This parameter is returned only after the payment is linked against the order_id.
merchant_id string Unique identifier of the merchant in the Pine Labs Online database.

Example: 123456
order_amount object An object that contains the transaction amount details.

Learn more about our order_amount child object.
notes string The note you want to show against an order.

Example: Order1
pre_auth boolean The pre-authorization type.

Possible values:
  • true: When pre-authorization is needed.
  • false: When pre-authorization is not required.
Example: false
allowed_payment_methods array of strings The type of payment methods you want to offer customers.

Accepted values:
  • CARD
  • UPI
  • POINTS
  • NETBANKING
  • WALLET
  • CREDIT_EMI
  • DEBIT_EMI
Example: CARD

Note: Before selecting a payment method, ensure it is configured for you.
callback_url string URL to redirect customers to success or failure pages.

Example: https://sample-callback-url
purchase_details object An object that contains the purchase details.

Learn more about the purchase_details child object.

Note: The presence of the object key-values depends on the Input request.
payments array of objects An array of objects that contains the payment details.

Note: Payment object is returned only for the orders linked with a payment.
created_at string The ISO 8601 UTC Timestamp when the order request was received.

Example: 2024-07-09T07:57:08.022Z
updated_at string The ISO 8601 UTC Timestamp when the order object was updated.

Example: 2024-07-09T07:57:08.022Z

Order Amount [Child Object]

The table below lists the various parameters in the order_amount child object. This object is part of the create order response object.

Parameter Type Description
value integer Transaction amount in Paisa.

  • Minimum value: 100 (₹1).
  • Maximum value: 100000000 (₹10 lakh).
Example: 1000
currency string Type of currency.

Example: INR

Purchase Details [Child Object]

The table below lists the various parameters in the purchase_details child object. This object is part of the create order response object.

Parameter Type Description
customer object An object that contains the customer details.

Learn more about the customer child object.
merchant_metadata object An object of key-value pair that can be used to store additional information.

Example: "key1": "DD"

Customer [Child Object]

The table below lists the various parameters in the customer child object. This is part of the purchase_details object.

Parameter Type Description
email_id string Customer's email address.
  • Minimum length: 1 character.
  • Maximum length: 50 characters.
Example: [email protected]
first_name string Customer's first name.
  • Minimum length: 1 character.
  • Maximum length: 50 characters.
Example: Kevin
last_name string Customer's last name.
  • Minimum length: 1 character.
  • Maximum length: 50 characters.
Example: Bob
customer_id string Unique identifier of the customer in the Pine Labs Online database.
  • Minimum length: 1 character.
  • Maximum length: 19 characters.
Example: 123456
mobile_number string Customer's mobile number.
  • Minimum length: 9 characters.
  • Maximum length: 20 characters.
Example: 9876543210
billing_address object An object that contains the details of the billing address.

Learn more about our billing_address child object.
shipping_address object An object that contains the shipping address details.

Learn more about our shipping_address child object.

Billing Address [Child Object]

The table below lists the various parameters in the billing_address child object. This is part of the customer object.

Parameter Type Description
address1stringCustomer's billing address1.
  • Max length: 100 characters.
Example: 10 Downing Street Westminster London
address2stringCustomer's billing address2.
  • Max length: 100 characters.
Example: Oxford Street Westminster London
address3stringCustomer's billing address3.
  • Max length: 100 characters.
Example: Baker Street Westminster London
pincodestringPincode of the billing address.
  • Min length: 6 characters.
  • Max length: 10 characters.
Example: 51524036
citystringCity of the billing address.
  • Max length: 50 characters.
Example: Westminster
statestringState of the billing address.
  • Max length: 50 characters.
Example: Westminster
countrystringCountry of the billing address.
  • Max length: 50 characters.
Example: London

Shipping Address [Child Object]

The table below lists the various parameters in the shipping_address child object. This is part of the customer object.

Parameter Type Description
address1stringCustomer's shipping address1.
  • Max length: 100 characters.
Example: 10 Downing Street Westminster London
address2stringCustomer's shipping address2.
  • Max length: 100 characters.
Example: Oxford Street Westminster London
address3stringCustomer's shipping address3.
  • Max length: 100 characters.
Example: Baker Street Westminster London
pincodestringPincode of the shipping address.
  • Min length: 6 characters
  • Max length: 10 characters.
Example: 51524036
citystringCity of the shipping address.
  • Max length: 50 characters.
Example: Westminster
statestringState of the shipping address.
  • Max length: 50 characters.
Example: Westminster
countrystringCountry of the shipping address.
  • Max length: 50 characters.
Example: London

Refer to our Create Order API 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 --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 --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"
        }
      }
    }
  ]
}'

{
  "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": "[email protected]",
        "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"
        },
        "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"
        }
      },
      "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"
  }
}
Click here for request and response parameter information.
Request Parameters
Response Parameters

Path Parameter

The table below lists the path parameters of our Save Card Payment API.

Parameter Type Description
order_id required string Unique identifier of the order in the Pine Labs Online database.

Example: v1-5757575757-aa-hU1rUd

Request Parameters

The table below lists the request parameters of our Save Card Payment API.

Parameter Type Description
Payments required array of objects An array of objects that contains the payment details.

Learn more about our payments child object

Payments [Child Object]

The table below lists the various parameters in the payments child object. This object is part of the create card payment request object.

Parameter Type Description
payment_method required string Type of payment method you want to use to accept a payment.

Accepted values:
  • CARD
  • UPI
  • Netbanking
  • POINTS
Example: Netbanking
payment_amount required object An object that contains the details of the payment amount.

Learn more about our payment_amount child object.
payment_option required object An object that contains the details of the payment options.

Learn more about our payment_option child object.

Payment Amount [Child Object]

The table below lists the various parameters in the payment_amount child object. This object is part of the payments object.

Parameter Type Description
value required integer The payment amount is Paisa.
  • Minimum value: 100 (₹1).
  • Maximum value: 100000000 (₹10 lakh).
Example: 100
currency required string Type of currency.

Example: INR

Payment Option [Child Object]

The table below lists the various parameters in the payment_option child object. This object is part of the payments object.

Parameter Type Description
card_details object An object that contains the card details.

Learn more about the card_details child object.
< id="card-details-child-object"h4>card_details [Child Object]

The table below lists the various parameters in the card_details child object. This object is part of the payment_option object.

Parameter Type Description
pay_code required string Bank code in the Pine Labs Online database.

Accepted values:
  • NB1531
Example: NB1531

Refer to our Supported Banks to know more.
save string Save card transaction status.

Possible values:
  • true: Save card details.
  • false: Do not save card details.
name required string Name on the card.
  • Maximum length: 100 characters.
  • Minimum length: 1 characters.
Example: Kevin
card_number required string Card Number.
  • Maximum length: 23 characters.
  • Minimum length: 12 characters.
Example: 123456789012

Supported characters: 0-9
cvv required string Card Verification Value [cvv] of the card.
  • Maximum length: 4 digits.
  • Minimum length: 3 digits.
Example: 123

Supported characters: 0-9
expiry_month required string Card expiry month as on the card.

Has to be 2 digits.

Example: 08

Supported characters: 0-9
expiry_year required string Card expiry year as on the card.

Has to be 4 digits.

Example: 2024

Supported characters: 0-9

The table below lists the various parameters returned in the Save Card Payment API response objects.

Parameter Type Description
order_id string Unique identifier of the order in the Pine Labs Online database.
  • Max length: 50 characters.
Example: v1-5757575757-aa-hU1rUd
merchant_order_reference string Unique identifier entered while creating an order.
  • Min length: 1 character.
  • Max length: 50 characters.
Example: 82d57572-057c-4826-5775-385a52150554
type string Payment type.

Possible values:
  • CHARGE
  • REFUND
status string Order status.

Possible values:
  • CREATED: When the order is successfully created.
  • PENDING: When the order is linked against a payment request.
  • PROCESSED: When the payment is received successfully.
  • AUTHORIZED: Only when pre_auth is true. When the payment is ready for authorization.
  • CANCELLED: When the payment gets cancelled.
  • ATTEMPTED: When the payment is unsuccessful due to incorrect OTP. You can retry OTP
  • FAILED: Payment acceptance failed for reasons such as cancel transactions, maximum retries for OTP verification etc.
  • FULLY_REFUNDED: When the payment is completely refunded.
  • PARTIALLY_REFUNDED: When the partial refund is successful.
challenge_url string Use the generated challenge_url URL to navigate your users the checkout page.
merchant_id string Unique identifier of the merchant in the Pine Labs Online database.

Example: 123456
order_amount object An object that contains the transaction amount details.

Learn more about our order_amount child object.
notes string The note you want to show against an order.

Example: Order1
pre_auth boolean The pre-authorization type.

Possible values:
  • true: When pre-authorization is needed.
  • false: When pre-authorization is not required.
Example: false
purchase_details object An object that contains the purchase details.

Learn more about the purchase_details child object.

Note: The presence of the object key-values depends on the Input request.
payments array of objects An array of objects that contains the payment details.

Learn more about the payments child object.

Note: Payment object is returned only for the orders linked with a payment.
created_at string The ISO 8601 UTC Timestamp when the order request was received.

Example: 2024-07-09T07:57:08.022Z
updated_at string The ISO 8601 UTC Timestamp when the order object was updated.

Example: 2024-07-09T07:57:08.022Z

Order Amount [Child Object]

The table below lists the various parameters in the order_amount child object. This object is part of the create payment request object.

Parameter Type Description
value integer Transaction amount in Paisa.

  • Minimum value: 100 (₹1).
  • Maximum value: 100000000 (₹10 lakh).
Example: 1000
currency string Type of currency.

Example: INR

Purchase Details [Child Object]

The table below lists the various parameters in the purchase_details child object. This object is part of the create payment request object.

Parameter Type Description
customer object An object that contains the customer details.

Learn more about the customer child object.
merchant_metadata object An object of key-value pair that can be used to store additional information.

Example: "key1": "DD"

Customer [Child Object]

The table below lists the various parameters in the customer child object. This is part of the purchase_details object.

Parameter Type Description
email_id string Customer's email address.
  • Minimum length: 1 character.
  • Maximum length: 50 characters.
Example: [email protected]
first_name string Customer's first name.
  • Minimum length: 1 character.
  • Maximum length: 50 characters.
Example: Kevin
last_name string Customer's last name.
  • Minimum length: 1 character.
  • Maximum length: 50 characters.
Example: Bob
customer_id string Unique identifier of the customer in the Pine Labs Online database.
  • Minimum length: 1 character.
  • Maximum length: 19 characters.
Example: 123456
mobile_number string Customer's mobile number.
  • Minimum length: 9 characters.
  • Maximum length: 20 characters.
Example: 9876543210
billing_address object An object that contains the details of the billing address.

Learn more about our billing_address child object.
shipping_address object An object that contains the shipping address details.

Learn more about our shipping_address child object.
Billing Address [Child Object]

The table below lists the various parameters in the billing_address child object. This is part of the customer object.

Parameter Type Description
address1stringCustomer's billing address1.
  • Max length: 100 characters.
Example: 10 Downing Street Westminster London
address2stringCustomer's billing address2.
  • Max length: 100 characters.
Example: Oxford Street Westminster London
address3stringCustomer's billing address3.
  • Max length: 100 characters.
Example: Baker Street Westminster London
pincodestringPincode of the billing address.
  • Min length: 6 characters.
  • Max length: 10 characters.
Example: 51524036
citystringCity of the billing address.
  • Max length: 50 characters.
Example: Westminster
statestringState of the billing address.
  • Max length: 50 characters.
Example: Westminster
countrystringCountry of the billing address.
  • Max length: 50 characters.
Example: London
Shipping Address [Child Object]

The table below lists the various parameters in the shipping_address child object. This is part of the customer object.

Parameter Type Description
address1stringCustomer's shipping address1.
  • Max length: 100 characters.
Example: 10 Downing Street Westminster London
address2stringCustomer's shipping address2.
  • Max length: 100 characters.
Example: Oxford Street Westminster London
address3stringCustomer's shipping address3.
  • Max length: 100 characters.
Example: Baker Street Westminster London
pincodestringPincode of the shipping address.
  • Min length: 6 characters
  • Max length: 10 characters.
Example: 51524036
citystringCity of the shipping address.
  • Max length: 50 characters.
Example: Westminster
statestringState of the shipping address.
  • Max length: 50 characters.
Example: Westminster
countrystringCountry of the shipping address.
  • Max length: 50 characters.
Example: London

Payments [Child Object]

The table below lists the various parameters in the payments child object. This object is part of the payments sample response object.

Parameter Type Description
id string Unique identifier of the payment in the Pine Labs Online database.
  • Maximum length: 50 characters.
Example: v1-5206071124-aa-mpLhF3-cc-l
merchant_payment_reference string A unique Payment Reference id sent by merchant.

Example: 008cf04b-a770-4777-854e-b1e6c1230609
status string Payment status.

Possible values:
    PENDING: When the create payment API request is successfully received by Pine Labs Online.
  • AUTHORIZED: Only when pre_auth is true. When the payment is ready for authorization.
  • CANCELLED: When the payment gets cancelled.
  • PROCESSED: When the payment is successfully received by Pine Labs Online.
  • FAILED: When the payment fails, this can be for many reasons such as canceling payments, etc.
Example: PENDING
payment_amount object An object that contains the details of the payment amount.

Learn more about our payment_amount child object.
payment_method string Type of payment method.

Accepted values:
  • CARD
  • UPI
  • Netbanking
  • POINTS
Example: Netbanking
payment_option object An object that contains the details of the payment options.

Learn more about our payment_option child object.
created_at string The ISO 8601 UTC Timestamp, when the create payment request was received by Pine Labs Online.

Example: 2024-07-11T06:52:12.484Z
updated_at string The ISO 8601 UTC Timestamp, when the payment response object is updated.

Example: 2024-07-11T06:59:38.260Z

Payment Amount [Child Object]

The table below lists the various parameters in the payment_amount child object. This object is part of the payments object.

Parameter Type Description
value integer The transaction amount is Paisa.
  • Minimum value: 100 (₹1).
  • Maximum value: 100000000 (₹10 lakh).
Example: 100
currency string Type of currency.

Example: INR

Payment Option [Child Object]

The table below lists the various parameters in the payment_option child object. This object is part of the payments object.

Parameter Type Description
card_data object An object that contains the card data details.

Learn more about card_data child object.

Card Data [Child Object]

The table below lists the various parameters in the card_data child object. This object is part of the payment_option object.

Parameter Type Description
card_type string Type of card.

Possible values:
  • DEBIT
  • CREDIT
Example: CREDIT
network_name string Card network providers.

Example: VISA
issuer_name string Card issuer entity.

Example: HDFC
card_category string The card category type.

Possible values:
  • CONSUMER
  • COMMERCIAL
  • PREMIUM
  • SUPER_PREMIUM
  • PLATINUM
  • OTHER
  • BUSINESS
  • GOVERNMENT_NOTES
  • PAYOUTS
  • ELITE
  • STANDARD
country_code string Card issuers Country.

Example: IND
token_txn_type string Transaction token type.

Possible values:
  • ALT_TOKEN
  • NETWORK_TOKEN
  • ISSUER_TOKEN
Example: ALT_TOKEN

Refer to our Create Payment API 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 --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 --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"
        }
      }
    }
  ]
}
'

{
  "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": "[email protected]",
        "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"
        },
        "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"
        }
      },
      "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"
  }
}
Click here for request and response parameter information.
Request Parameters
Response Parameters

Path Parameter

The table below lists the path parameters of our Card Payment API.

Parameter Type Description
order_id required string Unique identifier of the order in the Pine Labs Online database.

Example: v1-5757575757-aa-hU1rUd

Request Parameters

The table below lists the request parameters of our Card Payment API.

Parameter Type Description
Payments required array of objects An array of objects that contains the payment details.

Learn more about our payments child object

Payments [Child Object]

The table below lists the various parameters in the payments child object. This object is part of the create card payment request object.

Parameter Type Description
payment_method required string Type of payment method you want to use to accept a payment.

Accepted values:
  • CARD
  • UPI
  • Netbanking
  • POINTS
Example: Netbanking
payment_amount required object An object that contains the details of the payment amount.

Learn more about our payment_amount child object.
payment_option required object An object that contains the details of the payment options.

Learn more about our payment_option child object.

Payment Amount [Child Object]

The table below lists the various parameters in the payment_amount child object. This object is part of the payments object.

Parameter Type Description
value required integer The payment amount is Paisa.
  • Minimum value: 100 (₹1).
  • Maximum value: 100000000 (₹10 lakh).
Example: 100
currency required string Type of currency.

Example: INR

Payment Option [Child Object]

The table below lists the various parameters in the payment_option child object. This object is part of the payments object.

Parameter Type Description
card_token_details object An object that contains the card token details.

Learn more about the card_token_details child object.

card_token_details [Child Object]

The table below lists the various parameters in the card_token_details child object. This object is part of the payment_option object.

Parameter Type Description
token_id required string Unique identifier of the token in the Pine Labs Online database.
  • Maximum length: 50 characters.
Example: ec71b52e-c21f-4ac5-8624-385d6b6bdccc
cvv required string Card Verification Value [cvv] of the card.
  • Maximum length: 4 digits.
  • Minimum length: 3 digits.
Example: 123

Supported characters: 0-9
token_txn_type required string Transaction token type.

Possible values:
  • ALT_TOKEN
  • NETWORK_TOKEN
  • ISSUER_TOKEN
Example: ALT_TOKEN

The table below lists the various parameters returned in the Card Payment response objects.

Parameter Type Description
order_id string Unique identifier of the order in the Pine Labs Online database.
  • Max length: 50 characters.
Example: v1-5757575757-aa-hU1rUd
merchant_order_reference string Unique identifier entered while creating an order.
  • Min length: 1 character.
  • Max length: 50 characters.
Example: 82d57572-057c-4826-5775-385a52150554
type string Payment type.

Possible values:
  • CHARGE
  • REFUND
status string Order status.

Possible values:
  • CREATED: When the order is successfully created.
  • PENDING: When the order is linked against a payment request.
  • PROCESSED: When the payment is received successfully.
  • AUTHORIZED: Only when pre_auth is true. When the payment is ready for authorization.
  • CANCELLED: When the payment gets cancelled.
  • ATTEMPTED: When the payment is unsuccessful due to incorrect OTP. You can retry OTP
  • FAILED: Payment acceptance failed for reasons such as cancel transactions, maximum retries for OTP verification etc.
  • FULLY_REFUNDED: When the payment is completely refunded.
  • PARTIALLY_REFUNDED: When the partial refund is successful.
challenge_url string Use the generated challenge_url URL to navigate your users the checkout page.
merchant_id string Unique identifier of the merchant in the Pine Labs Online database.

Example: 123456
order_amount object An object that contains the transaction amount details.

Learn more about our order_amount child object.
notes string The note you want to show against an order.

Example: Order1
pre_auth boolean The pre-authorization type.

Possible values:
  • true: When pre-authorization is needed.
  • false: When pre-authorization is not required.
Example: false
purchase_details object An object that contains the purchase details.

Learn more about the purchase_details child object.

Note: The presence of the object key-values depends on the Input request.
payments array of objects An array of objects that contains the payment details.

Learn more about the payments child object.

Note: Payment object is returned only for the orders linked with a payment.
created_at string The ISO 8601 UTC Timestamp when the order request was received.

Example: 2024-07-09T07:57:08.022Z
updated_at string The ISO 8601 UTC Timestamp when the order object was updated.

Example: 2024-07-09T07:57:08.022Z

Order Amount [Child Object]

The table below lists the various parameters in the order_amount child object. This object is part of the create payment request object.

Parameter Type Description
value integer Transaction amount in Paisa.

  • Minimum value: 100 (₹1).
  • Maximum value: 100000000 (₹10 lakh).
Example: 1000
currency string Type of currency.

Example: INR

Purchase Details [Child Object]

The table below lists the various parameters in the purchase_details child object. This object is part of the create payment request object.

Parameter Type Description
customer object An object that contains the customer details.

Learn more about the customer child object.
merchant_metadata object An object of key-value pair that can be used to store additional information.

Example: "key1": "DD"

Customer [Child Object]

The table below lists the various parameters in the customer child object. This is part of the purchase_details object.

Parameter Type Description
email_id string Customer's email address.
  • Minimum length: 1 character.
  • Maximum length: 50 characters.
Example: [email protected]
first_name string Customer's first name.
  • Minimum length: 1 character.
  • Maximum length: 50 characters.
Example: Kevin
last_name string Customer's last name.
  • Minimum length: 1 character.
  • Maximum length: 50 characters.
Example: Bob
customer_id string Unique identifier of the customer in the Pine Labs Online database.
  • Minimum length: 1 character.
  • Maximum length: 19 characters.
Example: 123456
mobile_number string Customer's mobile number.
  • Minimum length: 9 characters.
  • Maximum length: 20 characters.
Example: 9876543210
billing_address object An object that contains the details of the billing address.

Learn more about our billing_address child object.
shipping_address object An object that contains the shipping address details.

Learn more about our shipping_address child object.
Billing Address [Child Object]

The table below lists the various parameters in the billing_address child object. This is part of the customer object.

Parameter Type Description
address1stringCustomer's billing address1.
  • Max length: 100 characters.
Example: 10 Downing Street Westminster London
address2stringCustomer's billing address2.
  • Max length: 100 characters.
Example: Oxford Street Westminster London
address3stringCustomer's billing address3.
  • Max length: 100 characters.
Example: Baker Street Westminster London
pincodestringPincode of the billing address.
  • Min length: 6 characters.
  • Max length: 10 characters.
Example: 51524036
citystringCity of the billing address.
  • Max length: 50 characters.
Example: Westminster
statestringState of the billing address.
  • Max length: 50 characters.
Example: Westminster
countrystringCountry of the billing address.
  • Max length: 50 characters.
Example: London
Shipping Address [Child Object]

The table below lists the various parameters in the shipping_address child object. This is part of the customer object.

Parameter Type Description
address1stringCustomer's shipping address1.
  • Max length: 100 characters.
Example: 10 Downing Street Westminster London
address2stringCustomer's shipping address2.
  • Max length: 100 characters.
Example: Oxford Street Westminster London
address3stringCustomer's shipping address3.
  • Max length: 100 characters.
Example: Baker Street Westminster London
pincodestringPincode of the shipping address.
  • Min length: 6 characters
  • Max length: 10 characters.
Example: 51524036
citystringCity of the shipping address.
  • Max length: 50 characters.
Example: Westminster
statestringState of the shipping address.
  • Max length: 50 characters.
Example: Westminster
countrystringCountry of the shipping address.
  • Max length: 50 characters.
Example: London

Payments [Child Object]

The table below lists the various parameters in the payments child object. This object is part of the payments sample response object.

Parameter Type Description
id string Unique identifier of the payment in the Pine Labs Online database.
  • Maximum length: 50 characters.
Example: v1-5206071124-aa-mpLhF3-cc-l
merchant_payment_reference string A unique Payment Reference id sent by merchant.

Example: 008cf04b-a770-4777-854e-b1e6c1230609
status string Payment status.

Possible values:
    PENDING: When the create payment API request is successfully received by Pine Labs Online.
  • AUTHORIZED: Only when pre_auth is true. When the payment is ready for authorization.
  • CANCELLED: When the payment gets cancelled.
  • PROCESSED: When the payment is successfully received by Pine Labs Online.
  • FAILED: When the payment fails, this can be for many reasons such as canceling payments, etc.
Example: PENDING
payment_amount object An object that contains the details of the payment amount.

Learn more about our payment_amount child object.
payment_method string Type of payment method.

Accepted values:
  • CARD
  • UPI
  • Netbanking
  • POINTS
Example: Netbanking
payment_option object An object that contains the details of the payment options.

Learn more about our payment_option child object.
created_at string The ISO 8601 UTC Timestamp, when the create payment request was received by Pine Labs Online.

Example: 2024-07-11T06:52:12.484Z
updated_at string The ISO 8601 UTC Timestamp, when the payment response object is updated.

Example: 2024-07-11T06:59:38.260Z

Payment Amount [Child Object]

The table below lists the various parameters in the payment_amount child object. This object is part of the payments object.

Parameter Type Description
value integer The transaction amount is Paisa.
  • Minimum value: 100 (₹1).
  • Maximum value: 100000000 (₹10 lakh).
Example: 100
currency string Type of currency.

Example: INR

Payment Option [Child Object]

The table below lists the various parameters in the payment_option child object. This object is part of the payments object.

Parameter Type Description
card_data object An object that contains the card data details.

Learn more about card_data child object.

Card Data [Child Object]

The table below lists the various parameters in the card_data child object. This object is part of the payment_option object.

Parameter Type Description
card_type string Type of card.

Possible values:
  • DEBIT
  • CREDIT
Example: CREDIT
network_name string Card network providers.

Example: VISA
issuer_name string Card issuer entity.

Example: HDFC
card_category string The card category type.

Possible values:
  • CONSUMER
  • COMMERCIAL
  • PREMIUM
  • SUPER_PREMIUM
  • PLATINUM
  • OTHER
  • BUSINESS
  • GOVERNMENT_NOTES
  • PAYOUTS
  • ELITE
  • STANDARD
country_code string Card issuers Country.

Example: IND
token_txn_type string Transaction token type.

Possible values:
  • ALT_TOKEN
  • NETWORK_TOKEN
  • ISSUER_TOKEN
Example: ALT_TOKEN

Refer to our Create Payment API 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 --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 --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"
        }
      }
    }
  ]
}
'

{
  "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": "[email protected]",
        "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"
        },
        "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"
        }
      },
      "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"
  }
}
Click here for request and response parameter information.
Request Parameters
Response Parameters

Path Parameter

The table below lists the path parameters of our Card Payment API.

Parameter Type Description
order_id required string Unique identifier of the order in the Pine Labs Online database.

Example: v1-5757575757-aa-hU1rUd

Request Parameters

The table below lists the request parameters of our Card Payment API.

Parameter Type Description
Payments required array of objects An array of objects that contains the payment details.

Learn more about our payments child object

Payments [Child Object]

The table below lists the various parameters in the payments child object. This object is part of the create card payment request object.

Parameter Type Description
payment_method required string Type of payment method you want to use to accept a payment.

Accepted values:
  • CARD
  • UPI
  • Netbanking
  • POINTS
Example: Netbanking
payment_amount required object An object that contains the details of the payment amount.

Learn more about our payment_amount child object.
payment_option required object An object that contains the details of the payment options.

Learn more about our payment_option child object.

Payment Amount [Child Object]

The table below lists the various parameters in the payment_amount child object. This object is part of the payments object.

Parameter Type Description
value required integer The payment amount is Paisa.
  • Minimum value: 100 (₹1).
  • Maximum value: 100000000 (₹10 lakh).
Example: 100
currency required string Type of currency.

Example: INR

Payment Option [Child Object]

The table below lists the various parameters in the payment_option child object. This object is part of the payments object.

Parameter Type Description
card_token_details object An object that contains the card token details.

Learn more about the card_token_details child object.

card_token_details [Child Object]

The table below lists the various parameters in the card_token_details child object. This object is part of the payment_option object.

Parameter Type Description
name required string Name of the Card holder.
  • Maximum length: 100 characters.
  • Minimum length: 1 characters.
Example: Kevin
last4_digit required string The last four digits of your card number.

Has to be 4 digits.

Example: 1234

Supported characters: 0-9
cvv required string Card Verification Value [cvv] of the card.
  • Maximum length: 4 digits.
  • Minimum length: 3 digits.
Example: 123

Supported characters: 0-9
expiry_month required string Card token expiry month.

Has to be 2 digits.

Example: 08

Supported characters: 0-9
expiry_year required string Card token year of expiry.

Has to be 4 digits.

Example: 2025

Supported characters: 0-9
token required string Unique identifier of the card as per the token transaction type.
  • Minimum: 1 characters.
  • Maximum: 50 characters
Example: 0342ef1e0342ef1e

Supported characters:
  • A-Z
  • a-z
  • 0-9
  • .
  • /
  • \
  • -
  • _
  • ,
  • (
  • )
  • '
cryptogram required string Unique encrypted text.
  • Minimum: 1 characters.
  • Maximum: 50 characters
Example: wAAAAAAl9SX1HsAmWKSgqwAAAA
token_txn_type required string Transaction token type.

Possible values:
  • ALT_TOKEN
  • NETWORK_TOKEN
  • ISSUER_TOKEN
Example: ALT_TOKEN

The table below lists the various parameters returned in the Card Payment response objects.

Parameter Type Description
order_id string Unique identifier of the order in the Pine Labs Online database.
  • Max length: 50 characters.
Example: v1-5757575757-aa-hU1rUd
merchant_order_reference string Unique identifier entered while creating an order.
  • Min length: 1 character.
  • Max length: 50 characters.
Example: 82d57572-057c-4826-5775-385a52150554
type string Payment type.

Possible values:
  • CHARGE
  • REFUND
status string Order status.

Possible values:
  • CREATED: When the order is successfully created.
  • PENDING: When the order is linked against a payment request.
  • PROCESSED: When the payment is received successfully.
  • AUTHORIZED: Only when pre_auth is true. When the payment is ready for authorization.
  • CANCELLED: When the payment gets cancelled.
  • ATTEMPTED: When the payment is unsuccessful due to incorrect OTP. You can retry OTP
  • FAILED: Payment acceptance failed for reasons such as cancel transactions, maximum retries for OTP verification etc.
  • FULLY_REFUNDED: When the payment is completely refunded.
  • PARTIALLY_REFUNDED: When the partial refund is successful.
challenge_url string Use the generated challenge_url URL to navigate your users the checkout page.
merchant_id string Unique identifier of the merchant in the Pine Labs Online database.

Example: 123456
order_amount object An object that contains the transaction amount details.

Learn more about our order_amount child object.
notes string The note you want to show against an order.

Example: Order1
pre_auth boolean The pre-authorization type.

Possible values:
  • true: When pre-authorization is needed.
  • false: When pre-authorization is not required.
Example: false
purchase_details object An object that contains the purchase details.

Learn more about the purchase_details child object.

Note: The presence of the object key-values depends on the Input request.
payments array of objects An array of objects that contains the payment details.

Learn more about the payments child object.

Note: Payment object is returned only for the orders linked with a payment.
created_at string The ISO 8601 UTC Timestamp when the order request was received.

Example: 2024-07-09T07:57:08.022Z
updated_at string The ISO 8601 UTC Timestamp when the order object was updated.

Example: 2024-07-09T07:57:08.022Z

Order Amount [Child Object]

The table below lists the various parameters in the order_amount child object. This object is part of the create payment request object.

Parameter Type Description
value integer Transaction amount in Paisa.

  • Minimum value: 100 (₹1).
  • Maximum value: 100000000 (₹10 lakh).
Example: 1000
currency string Type of currency.

Example: INR

Purchase Details [Child Object]

The table below lists the various parameters in the purchase_details child object. This object is part of the create payment request object.

Parameter Type Description
customer object An object that contains the customer details.

Learn more about the customer child object.
merchant_metadata object An object of key-value pair that can be used to store additional information.

Example: "key1": "DD"

Customer [Child Object]

The table below lists the various parameters in the customer child object. This is part of the purchase_details object.

Parameter Type Description
email_id string Customer's email address.
  • Minimum length: 1 character.
  • Maximum length: 50 characters.
Example: [email protected]
first_name string Customer's first name.
  • Minimum length: 1 character.
  • Maximum length: 50 characters.
Example: Kevin
last_name string Customer's last name.
  • Minimum length: 1 character.
  • Maximum length: 50 characters.
Example: Bob
customer_id string Unique identifier of the customer in the Pine Labs Online database.
  • Minimum length: 1 character.
  • Maximum length: 19 characters.
Example: 123456
mobile_number string Customer's mobile number.
  • Minimum length: 9 characters.
  • Maximum length: 20 characters.
Example: 9876543210
billing_address object An object that contains the details of the billing address.

Learn more about our billing_address child object.
shipping_address object An object that contains the shipping address details.

Learn more about our shipping_address child object.
Billing Address [Child Object]

The table below lists the various parameters in the billing_address child object. This is part of the customer object.

Parameter Type Description
address1stringCustomer's billing address1.
  • Max length: 100 characters.
Example: 10 Downing Street Westminster London
address2stringCustomer's billing address2.
  • Max length: 100 characters.
Example: Oxford Street Westminster London
address3stringCustomer's billing address3.
  • Max length: 100 characters.
Example: Baker Street Westminster London
pincodestringPincode of the billing address.
  • Min length: 6 characters.
  • Max length: 10 characters.
Example: 51524036
citystringCity of the billing address.
  • Max length: 50 characters.
Example: Westminster
statestringState of the billing address.
  • Max length: 50 characters.
Example: Westminster
countrystringCountry of the billing address.
  • Max length: 50 characters.
Example: London
Shipping Address [Child Object]

The table below lists the various parameters in the shipping_address child object. This is part of the customer object.

Parameter Type Description
address1stringCustomer's shipping address1.
  • Max length: 100 characters.
Example: 10 Downing Street Westminster London
address2stringCustomer's shipping address2.
  • Max length: 100 characters.
Example: Oxford Street Westminster London
address3stringCustomer's shipping address3.
  • Max length: 100 characters.
Example: Baker Street Westminster London
pincodestringPincode of the shipping address.
  • Min length: 6 characters
  • Max length: 10 characters.
Example: 51524036
citystringCity of the shipping address.
  • Max length: 50 characters.
Example: Westminster
statestringState of the shipping address.
  • Max length: 50 characters.
Example: Westminster
countrystringCountry of the shipping address.
  • Max length: 50 characters.
Example: London

Payments [Child Object]

The table below lists the various parameters in the payments child object. This object is part of the payments sample response object.

Parameter Type Description
id string Unique identifier of the payment in the Pine Labs Online database.
  • Maximum length: 50 characters.
Example: v1-5206071124-aa-mpLhF3-cc-l
merchant_payment_reference string A unique Payment Reference id sent by merchant.

Example: 008cf04b-a770-4777-854e-b1e6c1230609
status string Payment status.

Possible values:
    PENDING: When the create payment API request is successfully received by Pine Labs Online.
  • AUTHORIZED: Only when pre_auth is true. When the payment is ready for authorization.
  • CANCELLED: When the payment gets cancelled.
  • PROCESSED: When the payment is successfully received by Pine Labs Online.
  • FAILED: When the payment fails, this can be for many reasons such as canceling payments, etc.
Example: PENDING
payment_amount object An object that contains the details of the payment amount.

Learn more about our payment_amount child object.
payment_method string Type of payment method.

Accepted values:
  • CARD
  • UPI
  • Netbanking
  • POINTS
Example: Netbanking
payment_option object An object that contains the details of the payment options.

Learn more about our payment_option child object.
created_at string The ISO 8601 UTC Timestamp, when the create payment request was received by Pine Labs Online.

Example: 2024-07-11T06:52:12.484Z
updated_at string The ISO 8601 UTC Timestamp, when the payment response object is updated.

Example: 2024-07-11T06:59:38.260Z

Payment Amount [Child Object]

The table below lists the various parameters in the payment_amount child object. This object is part of the payments object.

Parameter Type Description
value integer The transaction amount is Paisa.
  • Minimum value: 100 (₹1).
  • Maximum value: 100000000 (₹10 lakh).
Example: 100
currency string Type of currency.

Example: INR

Payment Option [Child Object]

The table below lists the various parameters in the payment_option child object. This object is part of the payments object.

Parameter Type Description
card_data object An object that contains the card data details.

Learn more about card_data child object.

Card Data [Child Object]

The table below lists the various parameters in the card_data child object. This object is part of the payment_option object.

Parameter Type Description
card_type string Type of card.

Possible values:
  • DEBIT
  • CREDIT
Example: CREDIT
network_name string Card network providers.

Example: VISA
issuer_name string Card issuer entity.

Example: HDFC
card_category string The card category type.

Possible values:
  • CONSUMER
  • COMMERCIAL
  • PREMIUM
  • SUPER_PREMIUM
  • PLATINUM
  • OTHER
  • BUSINESS
  • GOVERNMENT_NOTES
  • PAYOUTS
  • ELITE
  • STANDARD
country_code string Card issuers Country.

Example: IND
token_txn_type string Transaction token type.

Possible values:
  • ALT_TOKEN
  • NETWORK_TOKEN
  • ISSUER_TOKEN
Example: ALT_TOKEN

Refer to our Create Payment API 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.
{
  "order_id": "v1-4405071524-aa-qlAtAf",
  "status": "AUTHORIZED",
  "signature": "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"
}

{
  "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.

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.

"key1=value1&key2=value2", ["order_id=random_order_id&status=AUTHORIZED"]

"key1=value1&key2=value2&key3=value3&key4=value4", ["error_code=USER_AUTHENTICATION_FAILED&error_message=Consumer Authentication required&order_id=<order_id>&status=FAILED"]
  1. 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.
  2. 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 --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 --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"
  }
}
'

{
  "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": "[email protected]",
        "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"
        },
        "shipping_address": {
          "address1": "H.No 15, Sector 17",
          "address2": "string",
          "address3": "string",
          "pincode": "144001123",
          "city": "CHANDIGARH",
          "state": "PUNJAB",
          "country": "INDIA"
        }
      },
      "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"
  }
}
Click here for request and response parameter information.
Request Parameters
Response Parameters

The table below lists the path parameter of our Capture Order API.

Parameter Type Description
order_id required string Unique identifier of the order in the Pine Labs Online database.

Example: v1-5757575757-aa-hU1rUd

The table below lists the request parameter of our Capture Order API.

Parameter Type Description
merchant_capture_reference required string Enter a unique identifier for the capture order request.
  • Maximum length: 50 characters.
  • Minimum length: 1 character.
Example: 123456789

Supported characters:
  • A-Z
  • a-z
  • 0-9
  • -
  • \
  • _
capture_amount object Mandatory for a partial capture request.

An object that contains the capture amount details.

Learn more about our capture_amount child object.

Capture Amount [Child Object]

The table below lists the various parameters in the capture_amount child object. This object is part of the capture_order request object.

Parameter Type Description
value required integer The split amount in Paisa.
  • Minimum value: 100 (₹1).
  • Maximum value: 100000000 (₹10 lakh).
Example: 100
currency required string Type of currency.

Example: INR

The table below lists the various parameters returned in the orders response objects.

Parameter Type Description
order_id string Unique identifier of the order in the Pine Labs Online database.
  • Max length: 50 characters.
Example: v1-5757575757-aa-hU1rUd
merchant_order_reference string Unique identifier entered while creating an order.
  • Min length: 1 character.
  • Max length: 50 characters.
Example: 82d57572-057c-4826-5775-385a52150554
type string Payment type.

Possible values:
  • CHARGE
  • REFUND
status string Order status.

Possible values:
  • CREATED: When the order is successfully created.
  • PENDING: When the order is linked against a payment request.
  • PROCESSED: When the payment is received successfully.
  • AUTHORIZED: Only when pre_auth is true. When the payment is ready for authorization.
  • CANCELLED: When the payment gets cancelled.
  • ATTEMPTED: When the payment is unsuccessful due to incorrect OTP. You can retry OTP
  • FAILED: Payment acceptance failed for reasons such as cancel transactions, maximum retries for OTP verification etc.
  • FULLY_REFUNDED: When the payment is completely refunded.
  • PARTIALLY_REFUNDED: When the partial refund is successful.
merchant_id string Unique identifier of the merchant in the Pine Labs Online database.

Example: 123456
order_amount object An object that contains the transaction amount details.

Learn more about our order_amount child object.
notes string The note you want to show against an order.

Example: Order1
pre_auth boolean The pre-authorization type.

Possible values:
  • true: When pre-authorization is needed.
  • false: When pre-authorization is not required.
Example: false
allowed_payment_methods array of strings The type of payment methods you want to offer customers.

Accepted values:
  • CARD
  • UPI
  • POINTS
  • NETBANKING
  • WALLET
  • CREDIT_EMI
  • DEBIT_EMI
Example: CARD

Note: Before selecting a payment method, ensure it is configured for you.
callback_url string URL to redirect customers to success or failure pages.

Example: https://sample-callback-url
purchase_details object An object that contains the purchase details.

Learn more about the purchase_details child object.

Note: The presence of the object key-values depends on the Input request.
payments array of objects An array of objects that contains the payment details.

Learn more about the payments child object.

Note: Payment object is returned only for the orders linked with a payment.
created_at string The ISO 8601 UTC Timestamp when the order request was received.

Example: 2024-07-09T07:57:08.022Z
updated_at string The ISO 8601 UTC Timestamp when the order object was updated.

Example: 2024-07-09T07:57:08.022Z
integration_mode string> Type of integration.

Example: SEAMLESS
payment_retries_remaining integer> Number of retry attempts left.

Example: 9

Order Amount [Child Object]

The table below lists the various parameters in the order_amount child object.

This object is part of the create order request object.

Parameter Type Description
value integer Transaction amount in Paisa.

  • Minimum value: 100 (₹1).
  • Maximum value: 100000000 (₹10 lakh).
Example: 1000
currency string Type of currency.

Example: INR

Purchase Details [Child Object]

The table below lists the various parameters in the purchase_details child object. This object is part of the create order request object.

Parameter Type Description
customer object An object that contains the customer details.

Learn more about the customer child object.
merchant_metadata object An object of key-value pair that can be used to store additional information.

Example: "key1": "DD"

Customer [Child Object]

The table below lists the various parameters in the customer child object. This is part of the purchase_details object.

Parameter Type Description
email_id string Customer's email address.
  • Minimum length: 1 character.
  • Maximum length: 50 characters.
Example: [email protected]
first_name string Customer's first name.
  • Minimum length: 1 character.
  • Maximum length: 50 characters.
Example: Kevin
last_name string Customer's last name.
  • Minimum length: 1 character.
  • Maximum length: 50 characters.
Example: Bob
customer_id string Unique identifier of the customer in the Pine Labs Online database.
  • Minimum length: 1 character.
  • Maximum length: 19 characters.
Example: 123456
mobile_number string Customer's mobile number.
  • Minimum length: 9 characters.
  • Maximum length: 20 characters.
Example: 9876543210
billing_address object An object that contains the details of the billing address.

Learn more about our billing_address child object.
shipping_address object An object that contains the shipping address details.

Learn more about our shipping_address child object.

Billing Address [Child Object]

The table below lists the various parameters in the billing_address child object. This is part of the customer object.

Parameter Type Description
address1stringCustomer's billing address1.
  • Max length: 100 characters.
Example: 10 Downing Street Westminster London
address2stringCustomer's billing address2.
  • Max length: 100 characters.
Example: Oxford Street Westminster London
address3stringCustomer's billing address3.
  • Max length: 100 characters.
Example: Baker Street Westminster London
pincodestringPincode of the billing address.
  • Min length: 6 characters.
  • Max length: 10 characters.
Example: 51524036
citystringCity of the billing address.
  • Max length: 50 characters.
Example: Westminster
statestringState of the billing address.
  • Max length: 50 characters.
Example: Westminster
countrystringCountry of the billing address.
  • Max length: 50 characters.
Example: London

Shipping Address [Child Object]

The table below lists the various parameters in the shipping_address child object. This is part of the customer object.

Parameter Type Description
address1stringCustomer's shipping address1.
  • Max length: 100 characters.
Example: 10 Downing Street Westminster London
address2stringCustomer's shipping address2.
  • Max length: 100 characters.
Example: Oxford Street Westminster London
address3stringCustomer's shipping address3.
  • Max length: 100 characters.
Example: Baker Street Westminster London
pincodestringPincode of the shipping address.
  • Min length: 6 characters
  • Max length: 10 characters.
Example: 51524036
citystringCity of the shipping address.
  • Max length: 50 characters.
Example: Westminster
statestringState of the shipping address.
  • Max length: 50 characters.
Example: Westminster
countrystringCountry of the shipping address.
  • Max length: 50 characters.
Example: London

Payments [Child Object]

The table below lists the various parameters in the payments child object. This object is part of the payments sample response object.

Parameter Type Description
id string Unique identifier of the payment in the Pine Labs Online database.
  • Maximum length: 50 characters.
Example: v1-5206071124-aa-mpLhF3-cc-l
merchant_payment_reference string A unique Payment Reference id sent by merchant.

Example: 008cf04b-a770-4777-854e-b1e6c1230609
status string Payment status.

Possible values:
    PENDING: When the create payment API request is successfully received by Pine Labs Online.
  • AUTHORIZED: Only when pre_auth is true. When the payment is ready for authorization.
  • CANCELLED: When the payment gets cancelled.
  • PROCESSED: When the payment is successfully received by Pine Labs Online.
  • FAILED: When the payment fails, this can be for many reasons such as canceling payments, etc.
Example: PENDING
payment_amount object An object that contains the details of the payment amount.

Learn more about our payment_amount child object.
payment_method string Type of payment method.

Accepted values:
  • CARD
  • UPI
  • POINTS
Example: CARD
payment_option object An object that contains the details of the payment options.

Learn more about our payment_option child object.
acquirer_data object An object that contains the details of the acquirer data.

Learn more about our acquirer_data child object.
capture_data object An object that contains the details of the capture data.

Learn more about our capture_data child object.

Note: The presence of the key-value pairs against this object depends on the pre-authorization type.
created_at string The ISO 8601 UTC Timestamp, when the create payment request was received by Pine Labs Online.

Example: 2024-07-11T06:52:12.484Z
updated_at string The ISO 8601 UTC Timestamp, when the payment response object is updated.

Example: 2024-07-11T06:59:38.260Z

Payment Amount [Child Object]

The table below lists the various parameters in the payment_amount child object. This object is part of the payments object.

Parameter Type Description
value integer The transaction amount is Paisa.
  • Minimum value: 100 (₹1).
  • Maximum value: 100000000 (₹10 lakh).
Example: 100
currency string Type of currency.

Example: INR

Payment Option [Child Object]

The table below lists the various parameters in the payment_option child object. This object is part of the payments object.

Parameter Type Description
card_data object An object that contains the card details.

Learn more about our card_data child object.

Card Data [Child Object]

The table below lists the various parameters in the card_data child object. This object is part of the payment_option object.

Parameter Type Description
card_type string Type of card.

Possible values:
  • DEBIT
  • CREDIT
Example: CREDIT
network_name string Card network providers.

Example: VISA
issuer_name string Card issuer entity.

Example: HDFC
card_category string The card category type.

Possible values:
  • CONSUMER
  • COMMERCIAL
  • PREMIUM
  • SUPER_PREMIUM
  • PLATINUM
  • OTHER
  • BUSINESS
  • GOVERNMENT_NOTES
  • PAYOUTS
  • ELITE
  • STANDARD
country_code string Card issuer's country.

Example: IND
token_txn_type string Transaction token type.

Possible values:
  • ALT_TOKEN
  • NETWORK_TOKEN
  • ISSUER_TOKEN
Example: ALT_TOKEN

Acquirer Data [Child Object]

The table below lists the various parameters in the acquirer_data child object. This object is part of the payments object.

Parameter Type Description
approval_code string Authorization code returned from acquirer against the payment.

Example: 030376
acquirer_reference string Unique reference returned from acquirer for the payment.

Example: 202455840588334
rrn string Retrieval reference number returned from acquirer for the payment.

Example: 419335023601
is_aggregator boolean The selected aggregator model type.

Accepted values:
  • true - Pine Labs Online is responsible for settling funds related to this payment.
  • false - Pine Labs Online is not responsible for settling funds related to this payment.
Note:
  • When is_aggregator is set to true, Pine Labs Online acts as the acquirer on behalf of merchants, receiving funds from banks into a designated "Nodal Account".
  • When is_aggregator is set to false, the Merchant has a direct relationship with the bank, and the responsibility for settlement of funds lies with both of those parties.

Capture Data [Child Object]

The table below lists the various parameters in the capture_data child object. This object is part of the payments object.

Parameter Type Description
merchant_capture_reference string Unique identifier passed while creating the capture payment request.

Example: 5742ef1e-4606-4c11-5757-705f4d415b6d
capture_amount object An object that contains the capture amount details.

Learn more about our capture_amount child object.
created_at string The ISO 8601 UTC Timestamp, when the amount was captured.

Example: 2024-07-11T11:52:12.484105Z
Capture Amount [Child Object]

The table below lists the various parameters in the capture_amount child object. This object is part of the capture_data object.

Parameter Type Description
value integer The transaction amount is in Paisa.
  • Minimum value: 100 (₹1).
  • Maximum value: 100000000 (₹10 lakh).
Example: 100
currency string Type of currency.

Example: INR

Refer to our Capture Order API 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 --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 --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'

{
  "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": "[email protected]",
        "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"
        },
        "shipping_address": {
          "address1": "H.No 15, Sector 17",
          "address2": "",
          "address3": "",
          "pincode": "144001123",
          "city": "CHANDIGARH",
          "state": "PUNJAB",
          "country": "INDIA"
        }
      },
      "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"
  }
}
Click here for request and response parameter information.
Request Parameters
Response Parameters

The table below lists the path parameter of our Capture Order API.

Parameter Type Description
order_id required string Unique identifier of the order in the Pine Labs Online database.

Example: v1-5757575757-aa-hU1rUd

The table below lists the various parameters returned in the orders response objects.

Parameter Type Description
order_id string Unique identifier of the order in the Pine Labs Online database.
  • Max length: 50 characters.
Example: v1-5757575757-aa-hU1rUd
merchant_order_reference string Unique identifier entered while creating an order.
  • Min length: 1 character.
  • Max length: 50 characters.
Example: 82d57572-057c-4826-5775-385a52150554
type string Payment type.

Possible values:
  • CHARGE
  • REFUND
status string Order status.

Possible values:
  • CREATED: When the order is successfully created.
  • PENDING: When the order is linked against a payment request.
  • PROCESSED: When the payment is received successfully.
  • AUTHORIZED: Only when pre_auth is true. When the payment is ready for authorization.
  • CANCELLED: When the payment gets cancelled.
  • ATTEMPTED: When the payment is unsuccessful due to incorrect OTP. You can retry OTP
  • FAILED: Payment acceptance failed for reasons such as cancel transactions, maximum retries for OTP verification etc.
  • FULLY_REFUNDED: When the payment is completely refunded.
  • PARTIALLY_REFUNDED: When the partial refund is successful.
merchant_id string Unique identifier of the merchant in the Pine Labs Online database.

Example: 123456
order_amount object An object that contains the transaction amount details.

Learn more about our order_amount child object.
notes string The note you want to show against an order.

Example: Order1
pre_auth boolean The pre-authorization type.

Possible values:
  • true: When pre-authorization is needed.
  • false: When pre-authorization is not required.
Example: false
callback_url string URL to redirect customers to success or failure pages.

Example: https://sample-callback-url
purchase_details object An object that contains the purchase details.

Learn more about the purchase_details child object.

Note: The presence of the object key-values depends on the Input request.
payments array of objects An array of objects that contains the payment details.

Learn more about the payments child object.

Note: Payment object is returned only for the orders linked with a payment.
created_at string The ISO 8601 UTC Timestamp when the order request was received.

Example: 2024-07-09T07:57:08.022Z
updated_at string The ISO 8601 UTC Timestamp when the order object was updated.

Example: 2024-07-09T07:57:08.022Z
integration_mode string> Type of integration.

Example: SEAMLESS
payment_retries_remaining integer> Number of retry attempts left.

Example: 9

Order Amount [Child Object]

The table below lists the various parameters in the order_amount child object. This object is part of the create order request object.

Parameter Type Description
value integer Transaction amount in Paisa.

  • Minimum value: 100 (₹1).
  • Maximum value: 100000000 (₹10 lakh).
Example: 1000
currency string Type of currency.

Example: INR

Purchase Details [Child Object]

The table below lists the various parameters in the purchase_details child object. This object is part of the create order request object.

Parameter Type Description
customer object An object that contains the customer details.

Learn more about the customer child object.
merchant_metadata object An object of key-value pair that can be used to store additional information.

Example: "key1": "DD"

Customer [Child Object]

The table below lists the various parameters in the customer child object. This is part of the purchase_details object.

Parameter Type Description
email_id string Customer's email address.
  • Minimum length: 1 character.
  • Maximum length: 50 characters.
Example: [email protected]
first_name string Customer's first name.
  • Minimum length: 1 character.
  • Maximum length: 50 characters.
Example: Kevin
last_name string Customer's last name.
  • Minimum length: 1 character.
  • Maximum length: 50 characters.
Example: Bob
customer_id string Unique identifier of the customer in the Pine Labs Online database.
  • Minimum length: 1 character.
  • Maximum length: 19 characters.
Example: 123456
mobile_number string Customer's mobile number.
  • Minimum length: 9 characters.
  • Maximum length: 20 characters.
Example: 9876543210
billing_address object An object that contains the details of the billing address.

Learn more about our billing_address child object.
shipping_address object An object that contains the shipping address details.

Learn more about our shipping_address child object.

Billing Address [Child Object]

The table below lists the various parameters in the billing_address child object. This is part of the customer object.

Parameter Type Description
address1stringCustomer's billing address1.
  • Max length: 100 characters.
Example: 10 Downing Street Westminster London
address2stringCustomer's billing address2.
  • Max length: 100 characters.
Example: Oxford Street Westminster London
address3stringCustomer's billing address3.
  • Max length: 100 characters.
Example: Baker Street Westminster London
pincodestringPincode of the billing address.
  • Min length: 6 characters.
  • Max length: 10 characters.
Example: 51524036
citystringCity of the billing address.
  • Max length: 50 characters.
Example: Westminster
statestringState of the billing address.
  • Max length: 50 characters.
Example: Westminster
countrystringCountry of the billing address.
  • Max length: 50 characters.
Example: London

Shipping Address [Child Object]

The table below lists the various parameters in the shipping_address child object. This is part of the customer object.

Parameter Type Description
address1stringCustomer's shipping address1.
  • Max length: 100 characters.
Example: 10 Downing Street Westminster London
address2stringCustomer's shipping address2.
  • Max length: 100 characters.
Example: Oxford Street Westminster London
address3stringCustomer's shipping address3.
  • Max length: 100 characters.
Example: Baker Street Westminster London
pincodestringPincode of the shipping address.
  • Min length: 6 characters
  • Max length: 10 characters.
Example: 51524036
citystringCity of the shipping address.
  • Max length: 50 characters.
Example: Westminster
statestringState of the shipping address.
  • Max length: 50 characters.
Example: Westminster
countrystringCountry of the shipping address.
  • Max length: 50 characters.
Example: London

Payments [Child Object]

The table below lists the various parameters in the payments child object. This object is part of the payments sample response object.

Parameter Type Description
id string Unique identifier of the payment in the Pine Labs Online database.
  • Maximum length: 50 characters.
Example: v1-5206071124-aa-mpLhF3-cc-l
merchant_payment_reference string A unique Payment Reference id sent by merchant.

Example: 008cf04b-a770-4777-854e-b1e6c1230609
status string Payment status.

Possible values:
    PENDING: When the create payment API request is successfully received by Pine Labs Online.
  • AUTHORIZED: Only when pre_auth is true. When the payment is ready for authorization.
  • CANCELLED: When the payment gets cancelled.
  • PROCESSED: When the payment is successfully received by Pine Labs Online.
  • FAILED: When the payment fails, this can be for many reasons such as canceling payments, etc.
Example: PENDING
payment_amount object An object that contains the details of the payment amount.

Learn more about our payment_amount child object.
payment_method string Type of payment method.

Accepted values:
  • CARD
  • UPI
  • POINTS
Example: CARD
payment_option object An object that contains the details of the payment options.

Learn more about our payment_option child object.
acquirer_data object An object that contains the details of the acquirer data.

Learn more about our acquirer_data child object.
created_at string The ISO 8601 UTC Timestamp, when the create payment request was received by Pine Labs Online.

Example: 2024-07-11T06:52:12.484Z
updated_at string The ISO 8601 UTC Timestamp, when the payment response object is updated.

Example: 2024-07-11T06:59:38.260Z

Payment Amount [Child Object]

The table below lists the various parameters in the payment_amount child object. This object is part of the payments object.

Parameter Type Description
value integer The transaction amount is Paisa.
  • Minimum value: 100 (₹1).
  • Maximum value: 100000000 (₹10 lakh).
Example: 100
currency string Type of currency.

Example: INR

Payment Option [Child Object]

The table below lists the various parameters in the payment_option child object. This object is part of the payments object.

Parameter Type Description
card_data object An object that contains the card details.

Learn more about our card_data child object.

Card Data [Child Object]

The table below lists the various parameters in the card_data child object. This object is part of the payment_option object.

Parameter Type Description
card_type string Type of card.

Possible values:
  • DEBIT
  • CREDIT
Example: CREDIT
network_name string Card network providers.

Example: VISA
issuer_name string Card issuer entity.

Example: HDFC
card_category string The card category type.

Possible values:
  • CONSUMER
  • COMMERCIAL
  • PREMIUM
  • SUPER_PREMIUM
  • PLATINUM
  • OTHER
  • BUSINESS
  • GOVERNMENT_NOTES
  • PAYOUTS
  • ELITE
  • STANDARD
country_code string Card issuer's country.

Example: IND
token_txn_type string Transaction token type.

Possible values:
  • ALT_TOKEN
  • NETWORK_TOKEN
  • ISSUER_TOKEN
Example: ALT_TOKEN

Acquirer Data [Child Object]

The table below lists the various parameters in the acquirer_data child object. This object is part of the payments object.

Parameter Type Description
approval_code string Authorization code returned from acquirer against the payment.

Example: 030376
acquirer_reference string Unique reference returned from acquirer for the payment.

Example: 202455840588334
rrn string Retrieval reference number returned from acquirer for the payment.

Example: 419335023601
is_aggregator boolean The selected aggregator model type.

Accepted values:
  • true - Pine Labs Online is responsible for settling funds related to this payment.
  • false - Pine Labs Online is not responsible for settling funds related to this payment.
Note:
  • When is_aggregator is set to true, Pine Labs Online acts as the acquirer on behalf of merchants, receiving funds from banks into a designated "Nodal Account".
  • When is_aggregator is set to false, the Merchant has a direct relationship with the bank, and the responsibility for settlement of funds lies with both of those parties.

Refer to our Cancel Order API documentation to learn more.

Updated 23 days ago

Ask AI
Assistant
Hourly Limit
0 / 20000 tokens used Resets in: 60m 0s
Order Lifecycle
Refunds
Settlements
Checkout
Dashboard
International Payments
How do I implement webhook notifications for payment status updates, and what's the recommended way to verify webhook authenticity?
How do I integrate Pine Labs payment gateway with my React Native mobile app and what are the required API credentials?
Can I customize the payment UI for card transactions, and what parameters can I pass to modify the checkout experience for my customers?
Assistant