API Reference

Object

Overview of the orders response object.

Shown below are the sample response returned through our Orders APIs.

{
  "data": {
    "order_id": "v1-5757575757-aa-hU1rUd",
    "merchant_order_reference": "112345",
    "type": "CHARGE",
    "status": "CREATED",
    "challenge_url": "https://api.pluralpay.in/web/auth/landing/?token=S50xnInJvpcftOzmuGWUqnLpIe694YPGJiKL%2FdBh5Yl%2Bwb8giJrl6HoTvcKljRVZa3H",
    "merchant_id": "123456",
    "order_amount": {
      "value": 1100,
      "currency": "INR"
    },
    "pre_auth": true,
    "callback_url": "https://sample-callback-url",
    "purchase_details": {
      "customer": {
        "email_id": "[email protected]",
        "first_name": "Kevin",
        "last_name": "Bob",
        "customer_id": "123456",
        "mobile_number": "9876543210",
        "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": "XX",
        "key2": "DOF"
      }
    },
    "payments": [],
    "created_at": "2024-07-09T07:57:08.022056Z",
    "updated_at": "2024-07-09T07:57:08.022065Z"
  }
}

{
  "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,
    "purchase_details": {
      "customer": {
        "email_id": "[email protected]",
        "first_name": "Kevin",
        "last_name": "Bob",
        "customer_id": "232323",
        "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": "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",
          "is_aggregator": true
        },
        "capture_data": [
          {
            "merchant_capture_reference": "f31d8c60-0dc8-4788-a577-5ced930cc175",
            "capture_amount": {
              "value": 1100,
              "currency": "INR"
            },
            "created_at": "2024-07-19T11:13:21.523516426Z"
          }
        ],
        "created_at": "2024-09-11T08:07:55.647816Z",
        "updated_at": "2024-09-11T08:07:57.115327Z"
      }
    ],
    "created_at": "2024-07-19T11:11:48.944147Z",
    "updated_at": "2024-07-19T11:13:23.962461Z"
  }
}

{
  "data": {
    "order_id": "v1-1207071124-aa-JI80eS",
    "merchant_order_reference": "dbe7e053-86a4-48a3-9250-002fe2f4c40c",
    "type": "CHARGE",
    "status": "FAILED",
    "merchant_id": "104359",
    "order_amount": {
      "value": 1000,
      "currency": "INR"
    },
    "pre_auth": false,
    "purchase_details": {
      "customer": {
        "email_id": "[email protected]",
        "first_name": "Mahesh",
        "last_name": "kumar",
        "customer_id": "192212",
        "mobile_number": "192192883",
        "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": "value1",
        "key2": "value2"
      }
    },
    "payments": [
      {
        "id": "v1-1207071124-aa-JI80eS-cc-o",
        "status": "FAILED",
        "payment_amount": {
          "value": 1000,
          "currency": "INR"
        },
        "payment_method": "CARD",
        "payment_option": {
          "card_data": {
            "card_type": "CREDIT",
            "network_name": "MASTERCARD",
            "issuer_name": "HDFC",
            "card_category": "NONE",
            "country_code": "IND",
            "token_txn_type": "ALT_TOKEN"
          }
        },
        "error_detail": {
          "code": "USER_AUTHENTICATION_FAILED",
          "message": "Consumer Authentication failed"
        },
        "created_at": "2024-09-11T08:07:55.647816Z",
        "updated_at": "2024-09-11T08:07:57.115327Z"
      }
    ],
    "created_at": "2024-07-11T07:12:33.341073Z",
    "updated_at": "2024-07-11T07:13:21.089448Z"
  }
}

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

ParameterTypeDescription
order_idstringUnique identifier of the order in the Plural database.
  • Maximum length: 50 characters.
Example: v1-5757575757-aa-hU1rUd
merchant_order_referencestringUnique identifier entered while creating a order.
  • Minimum length: 1 character.
  • Maximum length: 50 characters.
Example: 82d57572-057c-4826-5775-385a52150554
typestringPayment type.

Possible values:
  • CHARGE
  • REFUND
statusstringOrder 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_urlstringUse the generated challenge_url to accept payment.

Note: This parameter is returned only after the payment is linked against the order_id.
merchant_idstringUnique identifier of the merchant in the Plural database.

Example: 123456
order_amountobjectAn object that contains the transaction amount details.

Learn more about the order_amount child object.
notesstringThe note you want to show against an order.

Example: Electricity Bill
pre_authbooleanThe 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.
callback_urlstringUse 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_detailsobjectAn 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.
paymentsarray of objectsAn 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_atstringThe ISO 8601 UTC Timestamp, when the create order request was received by Plural.

Example: 2024-07-09T07:57:08.022056Z
updated_atstringThe ISO 8601 UTC Timestamp, when the order object is updated.

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

Order Amount [Child Object]

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

ParameterTypeDescription
valueintegerTransaction amount is Paisa.
  • Minimum value: 100 (₹1)
  • Maximum value: 100000000 (₹10 lakh).
Example: 1000
currencystringType 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 orders sample response object.

ParameterTypeDescription
customerObjectAn object that contains the customer details.

Learn more about the customer child object.
merchant_metadataobjectAn 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.

ParameterTypeDescription
email_idstringCustomer's email address.
  • Minimum length: 1 character.
  • Maximum length: 50 characters.
Example: [email protected]
first_namestringCustomer's first name.
  • Minimum length: 1 character.
  • Maximum length: 50 characters.
Example: Kevin
last_namestringCustomer's last name.
  • Minimum length: 1 character.
  • Maximum length: 50 characters.
Example: Bob
customer_idstringUnique identifier of the customer in the Plural database.
  • Minimum length: 1 character.
  • Maximum length: 19 characters.
Example: 123456
mobile_numberstringCustomer's mobile number.
  • Minimum length: 9 character.
  • Maximum length: 20 characters.
Example: 9876543210

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

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

Learn more about the 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.

ParameterTypeDescription
address1stringCustomer's billing address1.
  • Maximum length: 100 characters.
Example: 10 Downing Street Westminster London
address2stringCustomer's billing address2.
  • Maximum length: 100 characters.
Example: Oxford Street Westminster London
address3stringCustomer's billing address3.
  • Maximum length: 100 characters.
Example: Baker Street Westminster London
pincodestringPincode of the billing address.
  • Minimum length: 6 characters.
  • Maximum length: 10 characters.
Example: 51524036

Supported characters:
  • 0-9
citystringCity of the billing address.
  • Maximum length: 50 characters.
Example: Westminster
statestringState of the billing address.
  • Maximum length: 50 characters.
Example: Westminster
countrystringCountry 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.

ParameterTypeDescription
address1stringCustomer's shipping address1.
  • Maximum length: 100 characters.
Example: 10 Downing Street Westminster London
address2stringCustomer's shipping address2.
  • Maximum length: 100 characters.
Example: Oxford Street Westminster London
address3stringCustomer's shipping address3.
  • Maximum length: 100 characters.
Example: Baker Street Westminster London
pincodestringPincode of the shipping address.
  • Minimum length: 6 characters.
  • Maximum length: 10 characters.
Example: 51524036

Supported characters:
  • 0-9
citystringCity of the shipping address.
  • Maximum length: 50 characters.
Example: Westminster
statestringState of the shipping address.
  • Maximum length: 50 characters.
Example: Westminster
countrystringCountry of the shipping address.
  • Maximum 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.

ParameterTypeDescription
idstringUnique identifier of the payment in the Plural database.
  • Maximum length: 50 characters.
Example: v1-5206071124-aa-mpLhF3-cc-l
statusstringPayment 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_amountobjectAn object that contains the details of the payment amount.

Learn more about our payment_amount child object.
payment_methodstringType of payment method.

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

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

Learn more about our acquirer_data child object.
error_detailobjectAn object that contains the error details.

Learn more about our error_detail child object.

Note: This object is returned only for the failed payment.
capture_dataobjectAn 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.
additional_detailobjectAn object that contains the additional details related to the payment.

Learn more about our capture_data child object.
created_atstringThe ISO 8601 UTC Timestamp, when the create payment request was received by Plural.

Example: 2024-07-09T07:57:08.022058Z
updated_atstringThe ISO 8601 UTC Timestamp, when the payment object is updated.

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

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.

ParameterTypeDescription
valueintegerThe transaction amount is Paisa.
  • Minimum value: 100 (₹1).
  • Maximum value: 100000000 (₹10 lakh).
Example: 100
currencystringType 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.

ParameterTypeDescription
card_dataobjectAn 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.

ParameterTypeDescription
card_typestringType of card.

Possible values:
  • DEBIT
  • CREDIT
Example: CREDIT
network_namestringCard network providers.

Example: VISA
issuer_namestringCard issuer entity.

Example: HDFC
product_namestringCard name.

Example: Visa Platinum
card_categorystringThe card category type.

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

Example: IND
token_txn_typestringTransaction 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.

ParameterTypeDescription
approval_codestringAuthorization code returned from acquirer against the payment.
  • Maximum length: 50 characters.
Example: 030376
acquirer_referencestringUnique reference returned from acquirer for the payment.
  • Maximum length: 50 characters.
Example: 202455840588334
rrnstringRetrieval reference number returned from acquirer for the payment.
  • Maximum length: 50 characters.
Example: 419335023601
is_aggregatorbooleanThe 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 the 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 the 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.

ParameterTypeDescription
codestringThe error short Code.

Example: PAYMENT_DECLINED
messagestringError description. This parameter tells you 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.

ParameterTypeDescription
merchant_capture_referencestringUnique identifier passed while creating the capture payment request.
  • Minimum length: 1 character.
  • Maximum length: 50 characters.
Example: 5742ef1e-4606-4c11-5757-705f4d415b6d
capture_amountobjectAn object that contains the capture amount details.

Learn more about our capture_amount child object.
created_atstringThe ISO 8601 UTC Timestamp, when the amount is 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.

ParameterTypeDescription
valueintegerThe transaction amount is Paisa.
  • Minimum value: 100 (₹1).
  • Maximum value: 100000000 (₹10 lakh).
Example: 100
currencystringType of currency.

Example: INR

Additional Detail [Child Object]

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

ParameterTypeDescription
source_ipstringThe IP Address of the merchant.

Example: 52.66.76.63