Product Guides

Integration Steps (COPY)

Learn how to integrate subscription APIs to automate plan creation, subscription management, and scheduled payments.

Suggest Edits

Auto-debit flow integration Steps
Follow the below steps to integrate with Plural subscription APIs.

  1. [Prerequisite] Generate Token
  2. Create Plan
  3. Create Subscription
  4. Create Payment
  5. Handle Payment
    1. Store Payment Details on Your Server
    2. Verify Payment Signature

1. [Prerequisite] Generate Token

Integrate our Generate Token API in your backend servers to generate the access token. Use the token generated to authenticate Plural 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 'accept: application/json' \
--header 'content-type: application/json' \
--header 'Request-Timestamp: 2024-07-09T07:57:08.022Z' \
--header 'Request-ID: c17ce30f-f88e-4f81-ada1-c3b4909ed235' \
--data '
{
  "client_id": "a17ce30e-f88e-4f81-ada1-c3b4909ed232",
  "client_secret": "fgwei7egyhuggwp39w8rh",
  "grant_type": "client_credentials"
}
'

curl --request POST \
--url https://api.pluralpay.in/api/auth/v1/token \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'Request-Timestamp: 2024-07-09T07:57:08.022Z' \
--header 'Request-ID: c17ce30f-f88e-4f81-ada1-c3b4909ed235' \
--data '
{
  "client_id": "a17ce30e-f88e-4f81-ada1-c3b4909ed232",
  "client_secret": "fgwei7egyhuggwp39w8rh",
  "grant_type": "client_credentials"
}
'

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "expires_in": 3600
}

Refer to our Generate Token API documentation to learn more.

Click here for request and response parameter information.
Dynamic Tabs
Request Parameters
Response Parameters

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

Parameter Type Description
client_id* string Unique client identifier in the Plural 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* 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* 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 Plural APIs.
expires_at string Access duration timestamp.

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

2. Create Plan

Use this API to Create a Plan.

To authenticate this API, use the generated access token in the Authorization headers of the API request.

Below are the sample requests and response for the Create Plan API.

curl --request POST \
     --url https://pluraluat.v2.pinepg.in/api/v1/public/plans \
     --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c' \
     --header 'Content-Type: application/json' \
     --header 'Request-ID: c17ce30f-f88e-4f81-ada1-c3b4909ed235' \
     --header 'Request-Timestamp: 2024-07-09T07:57:08.022Z' \
     --header 'accept: application/json' \
     --data '
{
  "plan_name": "Monthly Plan",
  "plan_description": "Diwali dhammaka plan intended to attract customers on diwali time",
  "frequency": "Day",
  "amount": {
    "value": 100,
    "currency": "INR"
  },
  "max_limit_amount": {
    "value": 100,
    "currency": "INR"
  },
  "trial_period_in_days": 1,
  "start_date": "2022-02-01T17:32:28Z",
  "end_date": "2022-10-21T17:32:28Z",
  "merchant_metadata": {
    "key1": "DD",
    "key2": "XOF"
  },
  "merchant_plan_reference": "1234567890"
}
'

curl --request POST \
     --url https://api.pluralpay.in/api/v1/public/plans \
     --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c' \
     --header 'Content-Type: application/json' \
     --header 'Request-ID: c17ce30f-f88e-4f81-ada1-c3b4909ed235' \
     --header 'Request-Timestamp: 2024-07-09T07:57:08.022Z' \
     --header 'accept: application/json' \
     --data '
{
  "plan_name": "Monthly Plan",
  "plan_description": "Diwali dhammaka plan intended to attract customers on diwali time",
  "notes": "string",
  "frequency_count": 1,
  "frequency": "Day",
  "amount": {
    "value": 100,
    "currency": "INR"
  },
  "max_limit_amount": {
    "value": 100,
    "currency": "INR"
  },
  "trial_period_in_days": 1,
  "start_date": "2022-02-01T17:32:28Z",
  "end_date": "2022-10-21T17:32:28Z",
  "merchant_metadata": {
    "key1": "DD",
    "key2": "XOF"
  },
  "merchant_order_reference": "1234567890"
}
'

{
  "plan_id": "v1-plan-4405071524-aa-qlAtAf",
  "status": "ACTIVE",
  "plan_name": "Monthly Plan",
  "plan_description": "Diwali dhammaka plan intended to attract customers on diwali time",
  "notes": "string",
  "frequency_count": 1,
  "frequency": "Day",
  "amount": {
    "value": 100,
    "currency": "INR"
  },
  "max_limit_amount": {
    "value": 100,
    "currency": "INR"
  },
  "trial_period_in_days": 1,
  "start_date": "2022-02-01T17:32:28Z",
  "end_date": "2022-10-21T17:32:28Z",
  "merchant_metadata": {
    "key1": "DD",
    "key2": "XOF"
  },
  "merchant_order_reference": "1234567890",
  "created_at": "2022-10-21T17:32:28Z",
  "modified_at": "2022-10-21T17:32:28Z"
}

Refer to our Create Plan API documentation to learn more.

Click here for request and response parameter information.
Dynamic Tabs
Request Parameters
Response Parameters

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

Parameter Type Description
plan_name* string Subscription plan name.

Example: Monthly Plan
plan_description string Corresponding description for a plan.

Example: Diwali Dhammaka plan intended to attract customers on Diwali time
frequency* string Frequency of recurring transactions for this particular plan.

Possible values:
  • Day
  • Week
  • Month
  • Year
  • AS
  • OT
  • Not Applicable
Example: Day
amount* object An object that contains the amount details.

Learn more about the amount child object.
max_limit_amount* object An object that contains the maximum limit amount details.

Learn more about the max_limit_amoun child object.
trial_period_in_days integer When a trial period is offered for the plan, this defines the duration of the trial period.

Example: 1
start_date string The ISO 8601 UTC Timestamp is the date when the subscription plan is active and available for use.

Example: 2022-02-01T17:32:28Z
end_date* string The ISO 8601 UTC Timestamp is the date when the subscription plan expires and can no longer be used for new subscriptions.

Example: 2022-09-21T17:32:28Z
merchant_metadata object An object of key-value pairs that can be used to store additional information.

Constraints:
  • Each pair cannot exceed 256 characters.
  • Maximum 10 key-value pairs.
Example: "key1": "DD"
merchant_plan_reference* string Unique identifier of the merchant plan reference entered while creating a plan.

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

Supported characters:
  • A-Z
  • a-z
  • 0-9
  • -
  • _

Amount [Child Object]

The table below lists the various parameters in the amount child object. This object is part of the create plan 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

Max limit amount [Child Object]

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

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

Example: INR

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

Parameter Type Description
plan_id string Unique identifier for the subscription plan in the Plural database.

Example: v1-plan-4405071524-aa-qlAtAf
status string Status of the plan.

Possible values:
  • ACTIVE: When the create plan request is successfully created.
  • INACTIVE: When the plan is disabled and cannot be used for new subscriptions.
  • CREATED: When the plan setup is completed but not yet activated.
  • EXPIRED: When the plan has surpassed its validity period and is no longer available.
  • PAUSED: When the plan is temporarily halted and can be resumed later.
  • ARCHIVED: When the plan is permanently deactivated and stored for record-keeping.
plan_name string Subscription plan name.

Example: Monthly Plan
plan_description string Corresponding description for a plan.

Example: Diwali dhammaka plan intended to attract customers on diwali time
frequency string Frequency of recurring transactions for this particular plan.

Possible values:
  • Day
  • Week
  • Month
  • Year
  • AS
  • OT
  • Not Applicable
Example: Day
amount object An object that contains the amount details.

Learn more about the amount child object.
max_limit_amount object An object that contains the maximum limit amount details.

Learn more about the max_limit_amount child object.
trial_period_in_days integer When a trial period is offered for the plan, this defines the duration of the trial period.

Example: 1

Note: The trial period is always measured in days.
start_date string The ISO 8601 UTC Timestamp is the date when the subscription plan is active and available for use.

Example: 2022-02-01T17:32:28Z
end_date string The ISO 8601 UTC Timestamp is the date when the subscription plan expires and can no longer be used for new subscriptions.

Example: 2022-09-21T17:32:28Z
merchant_metadata object 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"
merchant_plan_reference string Unique identifier of the merchant plan reference entered while creating a plan.

  • Minimum length: 1 character.
  • Maximum length: 50 characters.
Example: 1234567890
created_at string The ISO 8601 UTC Timestamp, when the create plan request was received by Plural.

Example: 2022-09-21T17:32:28Z
modified_at string The ISO 8601 UTC Timestamp, when the plan object is updated.

Example: 2022-09-21T17:32:28Z

Amount [Child Object]

The table below lists the various parameters in the amount child object. This object is part of the create plan 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

Max limit amount [Child Object]

The table below lists the various parameters in the max_limit_amount child object. This object is part of the create plan response 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

3. Create Subscription

To Create Subscription, use our Create subscription API, use the plan_id returned in the response of a Create Plan API to link the subscription with a plan.

For authentication use the generated access token in the headers of the API request.

Below are the sample requests and response for the Create subscription API.

curl --request POST \
     --url https://pluraluat.v2.pinepg.in/api/v1/public/subscriptions \
     --header 'Authorization: Bearer https://pluraluat.v2.pinepg.in/api/v1/public/plans' \
     --header 'Content-Type: application/json' \
     --header 'Request-ID: c17ce30f-f88e-4f81-ada1-c3b4909ed235' \
     --header 'Request-Timestamp: 2024-07-09T07:57:08.022Z' \
     --header 'accept: application/json' \
     --data '
{
  "merchant_subscription_reference": "1234567890",
  "enable_notification": true,
  "plan_id": "v1-plan-4405071524-aa-qlAtAf",
  "callback_url": "https://www.example.com",
  "quantity": 1,
  "start_date": "2022-07-21T17:32:28Z",
  "end_date": "2022-09-21T17:32:28Z",
  "customer_id": "123456",
  "allowed_payment_methods": [
    "UPI"
  ],
  "integration_mode": "SEAMLESS",
  "merchant_metadata": {
    "key1": "DD",
    "key2": "XOF"
  },
  "is_tpv_enabled": false,
  "bank_account": {
    "account_number": "123456789012345",
    "name": "Gaurav Kumar",
    "ifsc": "123456789012345"
  }
}
'

curl --request POST \
     --url https://api.pluralpay.in/api/v1/public/subscriptions \
     --header 'Authorization: Bearer https://pluraluat.v2.pinepg.in/api/v1/public/plans' \
     --header 'Content-Type: application/json' \
     --header 'Request-ID: c17ce30f-f88e-4f81-ada1-c3b4909ed235' \
     --header 'Request-Timestamp: 2024-07-09T07:57:08.022Z' \
     --header 'accept: application/json' \
     --data '
{
  "merchant_order_reference": "1234567890",
  "enable_notification": true,
  "plan_id": "v1-plan-4405071524-aa-qlAtAf",
  "webhook_url": "https://www.subscription-url-webhook.com",
  "quantity": 1,
  "start_date": "2022-07-21T17:32:28Z",
  "end_date": "2022-09-21T17:32:28Z",
  "customer_id": "123456",
  "payment_mode": [
    "UPI"
  ],
  "integration_mode": "SEAMLESS",
  "merchant_metadata": {
    "key1": "DD",
    "key2": "XOF"
  },
  "is_tpv_enabled": true,
  "bank_account": {
    "account_number": "123456789012345",
    "name": "Gaurav Kumar",
    "ifsc": "123456789012345"
  }
}
'

{
  "subscription_id": "v1-sub-4405071524-aa-qlAtAf",
  "merchant_order_reference": "1234567890",
  "enable_notification": true,
  "plan_details": {
    "plan_id": "v1-plan-4405071524-aa-qlAtAf",
    "status": "ACTIVE",
    "plan_name": "Monthly Plan",
    "plan_description": "Diwali dhammaka plan intended to attract customers on diwali time",
    "notes": "string",
    "frequency_count": 1,
    "frequency": "Day",
    "amount": {
      "value": 100,
      "currency": "INR"
    },
    "max_limit_amount": {
      "value": 100,
      "currency": "INR"
    },
    "trial_period_in_days": 1,
    "start_date": "2022-02-01T17:32:28Z",
    "end_date": "2022-10-21T17:32:28Z",
    "merchant_metadata": {
      "key1": "DD",
      "key2": "XOF"
    },
    "merchant_order_reference": "1234567890",
    "created_at": "2022-10-21T17:32:28Z",
    "modified_at": "2022-10-21T17:32:28Z"
  },
  "quantity": 1,
  "start_date": "2022-07-21T17:32:28Z",
  "end_date": "2022-09-21T17:32:28Z",
  "customer_id": "123456",
  "payment_mode": [
    "UPI"
  ],
  "integration_mode": "SEAMLESS",
  "webhook_url": "https://www.subscription-url-webhook.com",
  "merchant_metadata": {
    "key1": "DD",
    "key2": "XOF"
  },
  "status": "ACTIVE",
  "bank_account": {
    "account_number": "123456789012345",
    "name": "Gaurav Kumar",
    "ifsc": "123456789012345"
  },
  "is_tpv_enabled": true,
  "created_at": "2022-10-21T17:32:28Z",
  "modified_at": "2022-10-21T17:32:28Z",
  "order_id": "v1-4405071524-aa-qlAtAf",
  "redirect_url": "https://api-staging.pluralonline.com/api/v3/checkout-bff/redirect/checkout?token=V3_D7LwszJqF2XRiFq46uOXQr0sQn8XbObLh7WM9YF8OAxQDYRnCMbhYgHbgFf4vCjJ%22&subscription_id=v1-sub-4405071524-aa-qlAtAf"
}

Refer to our Create subscription API documentation to learn more.

Click here for request and response parameter information.
Dynamic Tabs
Request Parameters
Response Parameters

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

Parameter Type Description
merchant_subscription_reference* string Unique identifier of the merchant order reference entered while creating a plan.

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

Supported characters:
  • A-Z
  • a-z
  • 0-9
  • -
  • _
enable_notification boolean Indicates if notifications are enabled.

Example: true
plan_id* string Unique identifier for the subscription plan in the Plural database.

Example: v1-plan-4405071524-aa-qlAtAf
callback_url string Use this URL to redirect your customers to specific success or failure pages based on the order or product details.

Example: https\://sample-callback-url>/td>
quantity integer The quantity of the subscription for the selected plan, should be greater than 0.

Example: 1
start_date* string The ISO 8601 UTC Timestamp is the date when the subscription plan is active and available for use.

Example: 2022-02-01T17:32:28Z
end_date* string The ISO 8601 UTC Timestamp is the date when the subscription plan expires and can no longer be used for new subscriptions.

Example: 2022-09-21T17:32:28Z
customer_id* string Unique identifier of the customer in the Plural database.
  • Minimum length: 1 character.
  • Maximum length: 19 characters.
Example: 123456
allowed_payment_methods string The type of payment methods you want to offer customers.

                 Accepted values:
  • CARD
  • UPI
  • POINTS
  • NETBANKING
  • WALLET
Example: UPI
integration_mode* string The integration mode for the subscription.

Accepted values:
  • SEAMLESS
Example: SEAMLESS
merchant_metadata object An object of key-value pairs that can be used to store additional information.

Constraints:
  • Each pair cannot exceed 256 characters.
  • Maximum 10 key-value pairs.
Example: "key1": "DD"
is_tpv_enabled boolean Indicates if Third-Party Validation (TPV) is enabled.

Example: true
bank_account object An object that contains the bank amount details.

Learn more about the bank_accountchild object.

Bank Account [Child Object]

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

Parameter Type Description
account_number* string Customer's bank account number.
  • Minimum length: 1 characters
  • Maximum length: 50 characters.
Example: 04992990009595
name* string Name of Customer.

Example: Kevin Bob
ifsc* string IFSC code of the bank account.
  • Minimum: 11 characters
  • Maximum: 11 characters
Example: HDFC0001234

Supported Characters:
  • A-Z (Uppercase letters)
  • 0-9 (Digits)

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

Parameter Type Description
subscription_id string Unique identifier for the subscription plan in the plural database.
  • Maximum length: 50 characters.
Example: v1-sub-4405071524-aa-qlAtAf
order_id string Unique identifier of the order in the Plural database.

Example: v1-4405071524-aa-qlAtAf
merchant_subscription_reference string Unique identifier of the merchant subscription reference entered while creating a suscription.
  • Minimum length: 1 character.
  • Maximum length: 50 characters.
Example: 1234567890
enable_notification boolean Indicates if notifications are enabled.

Example: true
plan_details Array of Objects An array of object that contain plan details.

Learn more about the plan details child object.
quantity integer The quantity of the subscription for the selected plan, should be greater than 0.

Example: 1
start_date string The ISO 8601 UTC Timestamp is the date when the subscription plan is active and available for use.

Example: 2022-02-01T17:32:28Z
end_date string The ISO 8601 UTC Timestamp is the date when the subscription plan expires and can no longer be used for new subscriptions.

Example: 2022-09-21T17:32:28Z
customer_id string Unique identifier of the customer in the Plural database.
  • Minimum length: 1 character.
  • Maximum length: 19 characters.
Example: 123456
payment_mode string Payment methods allowed for subscription.
Accepted values:
  • CARD
  • UP
Example: UPI
allowed_payment_methods string The type of payment methods you want to offer customers.

                 Accepted values:
  • CARD
  • UPI
  • POINTS
  • NETBANKING
  • WALLET
Example: UPI
integration_mode string The integration mode for the subscription.

Accepted values:
  • SEAMLESS
Example: SEAMLESS
callback_url string Use this URL to redirect your customers to specific success or failure pages based on the order or product details.

Example: https\://sample-callback-url>/td>
merchant_metadata object An object of key-value pairs that can be used to store additional information.

Constraints:
  • Each pair cannot exceed 256 characters.
  • Maximum 10 key-value pairs.
Example: "key1": "DD
status string Status of the Subscription.

Possible values:
  • ACTIVE: When the subscription is currently active and payments are being processed as per the billing cycle.
  • INACTIVE: When the subscription has been created but is not yet activated.
  • CREATED: When the subscription has been successfully created but is not yet active.
  • REGISTERED: When the subscription has been registered successfully.
  • CANCELLED_BY_CUSTOMER_DURING_PRE_DEBIT_NOTIFICATION: When the customer canceled the subscription during the pre-debit notification stage.
  • ARCHIVED: When the subscription has been archived and is no longer active.
  • CANCELLED_BY_CUSTOMER_DURING_MANDATE_CREATION: When the customer canceled the subscription while setting up the payment mandate.
  • CANCELLED_BY_MERCHANT: When the subscription was canceled by the merchant.
  • DEBIT_FAILED: When the scheduled payment for the subscription failed.
  • PAUSED: When the subscription has been temporarily paused.
  • CANCELLED: When the subscription has been canceled and is no longer active.
  • TRIAL: When the subscription is in its trial period before regular billing starts.
  • REVOKE_INITIATED: When a request to revoke the subscription has been initiated.
  • COMPLETED: When the subscription has successfully completed its billing cycle.
  • CANCELLED_BY_CUSTOME`: When the customer has canceled the subscription.
  • PAUSED_BY_CUSTOMER: When the customer has temporarily paused the subscription.
  • RESUMED_BY_CUSTOMER: When the customer has resumed a previously paused subscription.
  • EXPIRED: When the subscription has reached its end date and expired.
  • HALTED: When the subscription has been stopped due to an issue or external intervention.
  • RESUMED: When the subscription has been resumed after being paused or halted.
bank_account object An object that contains the bank amount details.

Learn more about the bank_accountchild object.
is_tpv_enabled boolean Indicates if Third-Party Validation (TPV) is enabled.

Example: true
created_at string The ISO 8601 UTC Timestamp, when the create plan request was received by Plural.

Example: 2022-09-21T17:32:28Z
modified_at string The ISO 8601 UTC Timestamp, when the plan object is updated.

Example: 2022-09-21T17:32:28Z
redirect_url string URL for redirection after checkout.

Example: https://api-staging.pluralonline.com/api/v3/checkout-bff/redirect/checkout?...subscription_id=v1-sub-4405071524-aa-qlAtAf>

Plan details [Child Object]

The table below lists the various parameters in the plan details child object. This object is part of the Create Subscription response object.

Parameter Type Description
plan_id string Unique identifier for the subscription plan in the Plural database.

Example: v1-plan-4405071524-aa-qlAtAf
status string Status of the plan.

Possible values:
  • ACTIVE: When the create plan request is successfully created.
  • INACTIVE: When the plan is disabled and cannot be used for new subscriptions.
  • CREATED: When the plan setup is completed but not yet activated.
  • EXPIRED: When the plan has surpassed its validity period and is no longer available.
  • PAUSED: When the plan is temporarily halted and can be resumed later.
  • ARCHIVED: When the plan is permanently deactivated and stored for record-keeping.
plan_name string Subscription plan name.

Example: Monthly Plan
plan_description string Corresponding description for a plan.

Example: Diwali dhammaka plan intended to attract customers on diwali time
frequency string Frequency of recurring transactions for this particular plan.

Possible values:
  • Day
  • Week
  • Month
  • Year
  • AS
  • OT
  • Not Applicable
Example: Day
amount object An object that contains the amount details.

Learn more about the amount child object.
max_limit_amount object An object that contains the maximum limit amount details.

Learn more about the max_limit_amount child object.
trial_period_in_days integer When a trial period is offered for the plan, this defines the duration of the trial period.

Example: 1

Note: The trial period is always measured in days.
start_date string The ISO 8601 UTC Timestamp is the date when the subscription plan is active and available for use.

Example: 2022-02-01T17:32:28Z
end_date string The ISO 8601 UTC Timestamp is the date when the subscription plan expires and can no longer be used for new subscriptions.

Example: 2022-09-21T17:32:28Z
merchant_metadata object 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"
merchant_plan_reference string Unique identifier of the merchant plan reference entered while creating a plan.

  • Minimum length: 1 character.
  • Maximum length: 50 characters.
Example: 1234567890
created_at string The ISO 8601 UTC Timestamp, when the create plan request was received by Plural.

Example: 2022-09-21T17:32:28Z
modified_at string The ISO 8601 UTC Timestamp, when the plan object is updated.

Example: 2022-09-21T17:32:28Z

Amount [Child Object]

The table below lists the various parameters in the amount child object. This object is part of the create plan 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

Max limit amount [Child Object]

The table below lists the various parameters in the max_limit_amount child object. This object is part of the create plan response 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

Bank Account [Child Object]

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

Parameter Type Description
account_number string Customer's bank account number.
  • Minimum length: 1 characters
  • Maximum length: 50 characters.
Example: 04992990009595
name string Name of Customer.

Example: Kevin Bob
ifsc string IFSC code of the bank account.
  • Minimum: 11 characters
  • Maximum: 11 characters
Example: HDFC0001234

Supported Characters:
  • A-Z (Uppercase letters)
  • 0-9 (Digits)

4. Create Payment

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

Below are the sample requests and sample response for a Create Payment API via Intent Flow.

curl --location 'https://pluraluat.v2.pinepg.in/api/pay/v1/orders/{order_id}/payments' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c' \
--header 'Content-Type: application/json' \
--header 'Request-ID: c17ce30f-f88e-4f81-ada1-c3b4909ed235' \
--header 'Request-Timestamp: 2024-07-09T07:57:08.022Z' \
--header 'accept: application/json' \
--data '
{
  "payments": [
    {
      "payment_method": "UPI",
      "merchant_payment_reference": "108cf506-c6a1-4535-9e7f-3af9c6d3d90c",
      "payment_amount": {
        "value": 100,
        "currency": "INR"
      },
      "payment_option": {
        "upi_details": {
          "txn_mode": "INTENT"
        }
      },
      "mandate_info": {
        "subscription_id": "v1-sub-250225165137-aa-Ukzs80",
        "request_type": "CREATE_MANDATE"
      }
    }
  ]
}
'

curl --location 'https://api.pluralpay.in/api/pay/v1/orders/{order_id}/payments' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c' \
--header 'Content-Type: application/json' \
--header 'Request-ID: c17ce30f-f88e-4f81-ada1-c3b4909ed235' \
--header 'Request-Timestamp: 2024-07-09T07:57:08.022Z' \
--header 'accept: application/json' \
--data '
{
  "payments": [
    {
      "merchant_payment_reference": "008cf04b-a770-4777-854e-b1e6c1230609",
      "payment_method": "UPI",
      "payment_amount": {
        "value": 1100,
        "currency": "INR"
      },
      "payment_option": {
        "upi_details": {
          "txn_mode": "INTENT"
        }
      }
    }
  ]
}
'

{
  "data": {
    "order_id": "v1-240820090251-aa-xwuI7J",
    "merchant_order_reference": "8200c7f7-4490-4970-b6bb-40ffa05d47e5",
    "type": "CHARGE",
    "status": "PENDING",
    "challenge_url": "upi://pay?mode=04&pa=pinelabs.24092@hdfcbank&pn=Pine%20Test&mc=6012&cu=INR&am=1.00&tr=68706&tn=Payment%20for%20v1",
    "merchant_id": "110047",
    "order_amount": {
      "value": 100,
      "currency": "INR"
    },
    "pre_auth": false,
    "allowed_payment_methods":[
      "CARD",
      "UPI",
      "NETBANKING",
      "POINTS",
      "WALLET"
    ],    
    "notes": "order1",
    "callback_url": "https://sample-callback-url",
    "purchase_details": {
      "customer": {
        "email_id": "[email protected]",
        "first_name": "Kevin",
        "last_name": "Bob",
        "customer_id": "192212",
        "mobile_number": "9876543210",
        "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-240820090251-aa-xwuI7J-up-6",
        "merchant_payment_reference": "008cf04b-a770-4777-854e-b1e6c1230609",
        "status": "PENDING",
        "payment_amount": {
          "value": 100,
          "currency": "INR"
        },
        "payment_method": "UPI",
        "payment_option": {
          "upi_details": {
            "txn_mode": "INTENT"
          }
        },
        "acquirer_data": {
          "approval_code": "",
          "acquirer_reference": "",
          "rrn": "",
          "is_aggregator": true
        },
        "created_at": "2024-08-20T09:02:51.265Z",
        "updated_at": "2024-08-20T09:03:01.208Z"
      }
    ],
    "created_at": "2024-08-20T09:02:51.265Z",
    "updated_at": "2024-08-20T09:03:01.208Z"
  }
}
Click here for request and response parameter information.
Dynamic Tabs
Request Parameters
Response Parameters

Path Parameters

Parameter Type Description
order_id* string Unique identifier of the order in the Plural database.

Example: v1-5757575757-aa-hU1rUd

Request Parameters

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

Learn more about our payments array of objects.

Payments [Child Object]

Parameter Type Description
payment_method* string Type of payment method. Accepted value: UPI
Example: UPI
merchant_payment_reference* string Unique Payment Reference ID sent by the merchant.
Example: 008cf04b-a770-4777-854e-b1e6c1230609
payment_amount* object An object that contains the details of the payment amount.

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

Learn more about the payment_option child object.
mandate_info* object An object that contains mandate info details.

Payment Amount [Child 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

Payment Option [Child Object]

Parameter Type Description
upi_details* object An object that contains the UPI details.

UPI Details [Child Object]

Parameter Type Description
txn_mode* string The transaction mode in which you want to accept payment.
Accepted value: INTENT

Mandate Info [Child Object]

Parameter Type Description
subscription_id* integer Unique identifier for the subscription plan.
Maximum length: 50 characters.
Example: v1-plan-4405071524-aa-qlAtAf
request_type* string The type of action to be performed on a mandate.
Accepted values:
  • Creation
  • Execution
  • Notification
  • Update

Response Object

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

Parameter Type Description
order_id string Unique identifier of the order in the Plural database.

Example: v1-5757575757-aa-hU1rUd
merchant_order_reference string Unique identifier entered while creating an order.
  • Minimum length: 1 character.
  • Maximum 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 verification until the payment gets failed.
  • 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 to the checkout page.
merchant_id string Unique identifier of the merchant in Plural database.

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

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

Possible values:
  • true: When pre-authorization is needed.
  • false: When pre-authorization is not required.
Example: false

Learn more about our pre-authorization.
allowed_payment_methods array of strings The type of payment methods you want to offer your customers to accept payments.

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

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

Example: Order1
callback_url string Use this URL to redirect your customers to specific success or failure pages based on the order or product details.

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

Learn more about our purchase_details child object.

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

Learn more about our payments child object.

Note: Payments response object can vary based on the payment methods and payment status.
created_at string The ISO 8601 UTC Timestamp, when the create order request was received by Plural.

Example: 2024-07-09T07:57:08.022Z
updated_at string The ISO 8601 UTC Timestamp, when the order response object is 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 payments sample response 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

Purchase Details [Child Object]

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

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

Learn more about our 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 Plural 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 Plural 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 Plural.
  • 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 Plural.
  • 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: UPI
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 Plural.

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
upi_details object An object that contains the UPI details.

Learn more about our upi_details child object.

UPI Details [Child Object]

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

Parameter Type Description
txn_mode string Type of UPI transaction.

Accepted values:
  • COLLECT
  • INTENT
Example: INTENT

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 - Plural is responsible for settling funds related to this payment.
  • false - Plural is not responsible for settling funds related to this payment.
Note:
  • When is_aggregator is set to true, Plural 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.
created_at string The ISO 8601 UTC Timestamp, when the amount was captured.

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

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

Below are the sample requests and sample response for a Create Payment API via Collect Flow.

curl --location 'https://pluraluat.v2.pinepg.in/api/pay/v1/orders/{order_id}/payments' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c' \
--header 'Content-Type: application/json' \
--header 'Request-ID: c17ce30f-f88e-4f81-ada1-c3b4909ed235' \
--header 'Request-Timestamp: 2024-07-09T07:57:08.022Z' \
--header 'accept: application/json' \
--data '
{
    "payments": [
        {
            "payment_method": "UPI",
            "merchant_payment_reference": "56d3cd91-9bb1-459c-8358-d92ef62d38ee",
            "payment_amount": {
                "value": 100,
                "currency": "INR"
            },
            "payment_option": {
                "upi_details": {
                    "txn_mode": "COLLECT",
                    "payer": {
                        "vpa": "9280850298@oksbi",
                        "phone_number": "9876543210"
                    }
                }
            },
            "mandate_info": {
                "subscription_id": "v1-sub-250225165137-aa-Ukzs80",
                "request_type": "CREATE_MANDATE"
            }
        }
    ]
}
'

curl --location 'https://api.pluralpay.in/api/pay/v1/orders/{order_id}/payments' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c' \
--header 'Content-Type: application/json' \
--header 'Request-ID: c17ce30f-f88e-4f81-ada1-c3b4909ed235' \
--header 'Request-Timestamp: 2024-07-09T07:57:08.022Z' \
--header 'accept: application/json' \
--data '
{
  "payments": [
    {
      "merchant_payment_reference": "008cf04b-a770-4777-854e-b1e6c1230609",
      "payment_method": "UPI",
      "payment_amount": {
        "value": 100,
        "currency": "INR"
      },
      "payment_option": {
        "upi_details": {
          "txn_mode": "COLLECT",
          "payer": {
            "vpa": "[email protected]"
          }
        }
      }
    }
  ]
}
'

{
  "data": {
    "order_id": "v1-240820090251-aa-xwuI7J",
    "merchant_order_reference": "8200c7f7-4490-4970-b6bb-40ffa05d47e5",
    "type": "CHARGE",
    "status": "PENDING",
    "challenge_url": "upi://pay?mode=04&pa=pinelabs.24092@hdfcbank&pn=Pine%20Test&mc=6012&cu=INR&am=1.00&tr=68706&tn=Payment%20for%20v1",
    "merchant_id": "110047",
    "order_amount": {
      "value": 100,
      "currency": "INR"
    },
    "pre_auth": false,
    "allowed_payment_methods":[
      "CARD",
      "UPI",
      "NETBANKING",
      "POINTS",
      "WALLET"
    ],    
    "notes": "order1",
    "callback_url": "https://sample-callback-url",
    "purchase_details": {
      "customer": {
        "email_id": "[email protected]",
        "first_name": "Kevin",
        "last_name": "Bob",
        "customer_id": "192212",
        "mobile_number": "9876543210",
        "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-240820090251-aa-xwuI7J-up-6",
        "merchant_payment_reference": "008cf04b-a770-4777-854e-b1e6c1230609",
        "status": "PENDING",
        "payment_amount": {
          "value": 100,
          "currency": "INR"
        },
        "payment_method": "UPI",
        "payment_option": {
          "upi_details": {
            "txn_mode": "COLLECT",
            "payer": {
              "vpa": "kevinbob@example"
            }
          },
          "acquirer_data": {
            "approval_code": "",
            "acquirer_reference": "",
            "rrn": "",
            "is_aggregator": true
          },
          "created_at": "2024-08-20T09:02:51.265Z",
          "updated_at": "2024-08-20T09:03:01.208Z"
        }
      }
    ],
    "created_at": "2024-08-20T09:02:51.265Z",
    "updated_at": "2024-08-20T09:03:01.208Z"
  }
}
Click here for request and response parameter information.
Dynamic Tabs
Request Parameters
Response Parameters

Path Parameters

Parameter Type Description
order_id* string Unique identifier of the order in the Plural database.

Example: v1-5757575757-aa-hU1rUd

Request Parameters

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

Learn more about our payments array of objects.

Payments [Child Object]

Parameter Type Description
payment_method* string Type of payment method. Accepted value: UPI
Example: UPI
merchant_payment_reference* string Unique Payment Reference ID sent by the merchant.
Example: 008cf04b-a770-4777-854e-b1e6c1230609
payment_amount* object An object that contains the details of the payment amount.
payment_option* object An object that contains the details of the payment options.
mandate_info* object An object that contains mandate info details.

Payment Amount [Child 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

Payment Option [Child Object]

Parameter Type Description
upi_details* object An object that contains the UPI details.

UPI Details [Child Object]

Parameter Type Description
txn_mode* string The transaction mode in which you want to accept payment.

Accepted value: COLLECT
payer* object An object that contains the payer VPA handle details.

Learn more about our payer array of objects.
Payer [Child Object]

The table below lists the various parameters in the payer child object. This object is part of the upi_details object.

Parameter Type Description
vpa* string VPA handle of your customer from whom you want to accept payment.
  • Minimum length: 2 characters.
  • Maximum length: 256 characters.
Example: [email protected]

Supported characters:
  • A-Z
  • a-z
  • 0-9
  • @
  • $
phone_number string Customer's phone number.
  • Minimum length: 9 characters.
  • Maximum length: 20 characters.
Example: 9876543210

Supported characters:
  • 0-9
  • +

Mandate Info [Child Object]

Parameter Type Description
subscription_id* integer Unique identifier for the subscription plan.
Maximum length: 50 characters.
Example: v1-plan-4405071524-aa-qlAtAf
request_type* string The type of action to be performed on a mandate.
Accepted values:
  • Creation
  • Execution
  • Notification
  • Update

Response Object

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

Parameter Type Description
order_id string Unique identifier of the order in the Plural database.

Example: v1-5757575757-aa-hU1rUd
merchant_order_reference string Unique identifier entered while creating an order.
  • Minimum length: 1 character.
  • Maximum 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 verification until the payment gets failed.
  • 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 to the checkout page.
merchant_id string Unique identifier of the merchant in Plural database.

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

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

Possible values:
  • true: When pre-authorization is needed.
  • false: When pre-authorization is not required.
Example: false

Learn more about our pre-authorization.
allowed_payment_methods array of strings The type of payment methods you want to offer your customers to accept payments.

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

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

Example: Order1
callback_url string Use this URL to redirect your customers to specific success or failure pages based on the order or product details.

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

Learn more about our purchase_details child object.

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

Learn more about our payments child object.

Note: Payments response object can vary based on the payment methods and payment status.
created_at string The ISO 8601 UTC Timestamp, when the create order request was received by Plural.

Example: 2024-07-09T07:57:08.022Z
updated_at string The ISO 8601 UTC Timestamp, when the order response object is 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 payments sample response 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

Purchase Details [Child Object]

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

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

Learn more about our 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 Plural 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 Plural 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 Plural.
  • 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 Plural.
  • 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: UPI
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.
error_detail object An object that contains the error details.

Learn more about our error_detail child object.

Note: This object is returned only for failed payments.
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 Plural.

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
upi_details object An object that contains the UPI details.

Learn more about our upi_details child object.

UPI Details [Child Object]

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

Parameter Type Description
txn_mode string Type of UPI transaction.

Accepted values:
  • COLLECT
  • INTENT
Example: COLLECT
payer object An object that contains the payer details.

Learn more about our payer child object.

Note: Mandatory for UPI collect only.

Payer [Child Object]

The table below lists the various parameters in the payer child object. This object is part of the upi_details object.

Parameter Type Description
vpa string VPA handle of your customer from whom you want to accept payment.
  • Minimum length: 2 characters.
  • Maximum length: 256 characters.
Example: kevinbob@example

Supported characters:
  • A-Z
  • a-z
  • 0-9
  • @
  • $

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 - Plural is responsible for settling funds related to this payment.
  • false - Plural is not responsible for settling funds related to this payment.
Note:
  • When is_aggregator is set to true, Plural 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.

Error Detail [Child Object]

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

Parameter Type Description
code string The error short code.

Example: PAYMENT_DECLINED
message string Error description explaining why the error occurred.

Example: Transaction declined due to insufficient balance.

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

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

📘

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 Plural signature returned in the return URL, it confirms that the payment details are from Plural.
  2. Capture the status returned on your database. Once the payment status is AUTHORIZED you can either capture or cancel an order.

NOTE:If the Auto Debit payment is disabled, follow the steps to create a scheduled payment manually.

Schedule Recurring Payment

Create Presentation

To Create Presentation, use our Create Presentation API, use the subscription_id returned in the response of a Create subscription API to link the payment against a subscription.

For authentication use the generated access token in the headers of the API request.

Below are the sample requests and response for the Create Presentation API.

curl --request POST \
     --url https://pluraluat.v2.pinepg.in/api/v1/public/subscriptions/subscription_id/presentations \
     --header 'Authorization: Bearer https://pluraluat.v2.pinepg.in/api/v1/public/plans' \
     --header 'Content-Type: application/json' \
     --header 'Request-ID: c17ce30f-f88e-4f81-ada1-c3b4909ed235' \
     --header 'Request-Timestamp: 2024-07-09T07:57:08.022Z' \
     --header 'accept: application/json' \
     --data '
{
  "subscription_id": "v1-sub-4405071524-aa-qlAtAf",
  "due_date": "2022-09-21T17:32:28Z",
  "amount": {
    "value": 100,
    "currency": "INR"
  },
  "merchant_presentation_reference": "1234567890",
  "customer_id": "123456",
  "merchant_metadata": {
    "key1": "DD",
    "key2": "XOF"
  }
}
'

curl --request POST \
     --url https://api.pluralpay.in/api/v1/public/subscriptions/subscription_id/presentations \
     --header 'Authorization: Bearer https://pluraluat.v2.pinepg.in/api/v1/public/plans' \
     --header 'Content-Type: application/json' \
     --header 'Request-ID: c17ce30f-f88e-4f81-ada1-c3b4909ed235' \
     --header 'Request-Timestamp: 2024-07-09T07:57:08.022Z' \
     --header 'accept: application/json' \
     --data '
{
  "subscription_id": "v1-sub-4405071524-aa-qlAtAf",
  "due_date": "2022-09-21T17:32:28Z",
  "amount": {
    "value": 100,
    "currency": "INR"
  },
  "merchant_presentation_reference": "1234567890",
  "customer_id": "123456",
  "merchant_metadata": {
    "key1": "DD",
    "key2": "XOF"
  }
}
'

{
  "subscription_id": "v1-sub-4405071524-aa-qlAtAf",
  "presentation_id": "v1-pre-4405071524-aa-qlAtAf",
  "due_date": "2022-09-21T17:32:28Z",
  "amount": {
    "value": 100,
    "currency": "INR"
  },
  "merchant_presentation_reference": "1234567890",
  "customer_id": "123456",
  "merchant_metadata": {
    "key1": "DD",
    "key2": "XOF"
  }
}

Refer to our Create Presentation API documentation to learn more.

Click here for request and response parameter information.
Dynamic Tabs
Request Parameters
Response Parameters

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

Parameter Type Description
subscription_id string Unique identifier for the subscription plan in the plural database.
  • Maximum length: 50 characters.
Example: v1-sub-4405071524-aa-qlAtAf
due_date string The ISO 8601 UTC Timestamp is the date & time at which the payment is due.

Example: 2022-09-21T17:32:28Z
amount object An object that contains the amount details.

Learn more about the amount child object.
merchant_presentation_reference string Unique identifier of the merchant presentation reference entered while creating a presentation.

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

Supported characters:
  • A-Z
  • a-z
  • 0-9
  • -
  • _
customer_id string Unique identifier of the customer in the Plural database.
  • Minimum length: 1 character.
  • Maximum length: 19 characters.
Example: 123456
merchant_metadata object An object of key-value pairs that can be used to store additional information.

Constraints:
  • Each pair cannot exceed 256 characters.
  • Maximum 10 key-value pairs.
Example: "key1": "DD"

Amount [Child Object]

The table below lists the various parameters in the amount child object. This object is part of the Create Presentation 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

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

Parameter Type Description
subscription_id string Unique identifier for the subscription plan in the plural database.
  • Maximum length: 50 characters.
Example: v1-sub-4405071524-aa-qlAtAf
presentation_id string A Unique identifier for the presentation provided by the Plural.
  • Maximum length: 50 characters.
Example: v1-pre-4405071524-aa-qlAtAf
due_date string The ISO 8601 UTC Timestamp is the date & time at which the payment is due.

Example: 2022-09-21T17:32:28Z
amount object An object that contains the amount details.

Learn more about the amount child object.
merchant_presentation_reference string Unique identifier of the merchant presentation reference entered while creating a presentation.

  • Minimum length: 1 character.
  • Maximum length: 50 characters.
    • Example: 1234567890
    customer_id string Unique identifier of the customer in the Plural database.
    • Minimum length: 1 character.
    • Maximum length: 19 characters.
    Example: 123456
    merchant_metadata object An object of key-value pairs that can be used to store additional information.

    Constraints:
    • Each pair cannot exceed 256 characters.
    • Maximum 10 key-value pairs.
    Example: "key1": "DD"

    Amount [Child Object]

    The table below lists the various parameters in the amount child object. This object is part of the Create Presentation 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

    To Know Your Payment Status

    To check your payment status, you can either rely on Webhook events or use our Get Orders APIs for real-time updates.

    1. Webhook Notification: We send Webhook notifications on the successful payment or any changes to the payments object. Refer to our Webhooks documentation to learn more.
    2. Manage subscription: To manage the subscription. Refer to our target="_blank">Manage subscription documentation to learn more.

    Updated 15 days ago