Create a Payment Order

POST/api/pay/v1/orders

An order contains the total amount and the purchase details against an order. For every order, we generate a unique order ID. It ensures that each order can be identified, referenced, and accessed without confusion or ambiguity. This order_id must be used in our payments API to accept payment against an order.

View as Markdown Open in ChatGPT Open in Claude Open in Perplexity

Requires Bearer token. Get token →

Header Parameters

Field	Details
`Request-Timestamp` `string`date-time	ISO 8601 UTC timestamp of the request. Used for idempotency and audit.
`Request-ID` `string`	Use a global unique identifier [GUID] for the request. Constraints Minimum length: 1 characterMaximum length: 50 characters

Request Bodyrequired

Field	Details
`merchant_order_reference` `string`required	Idempotency Key. Unique order reference assigned by the merchant. Duplicate requests with the same `merchant_order_reference` will return the existing order instead of creating a new one. Constraints Minimum length: 1 characterMaximum length: 50 characters
`order_amount` `object`required2 nested fields	Monetary amount with currency.
`pre_auth` `boolean`	Whether pre-authorization is needed.
`allowed_payment_methods` `string[]`	Payment methods to offer the customer. Constraints Allowed item values: `CARDUPINETBANKINGPOINTSWALLETCREDIT_EMIDEBIT_EMIBNPLCARDLESS_EMI`
`notes` `string`	Note to show against the order. Constraints Maximum length: 100 characters
`callback_url` `string`	URL to redirect customers after successful payment.
`failure_callback_url` `string`	URL to redirect customers after failed payment. If not provided, callback_url is used for both.
`purchase_details` `object`3 nested fields	Purchase details including customer information.
`split_info` `object`2 nested fields	Split settlement information for marketplace flows.
`is_mcc_transaction` `string`	Identifies the order type for MCC transactions. Set to "true" for MCC transactions.
`base_amount` `object`2 nested fields	Monetary amount with currency.
`cart_coupon_discount_amount` `object`2 nested fields	Monetary amount with currency.
`cross_border_details` `object`4 nested fields	Cross-border payment details for Cross Border Import enabled merchants. Required when the merchant is enabled for cross-border transactions.

Response

Field	Details
`data` `object`24 nested fields
`order_id` `string`	Unique identifier of the order in the Pine Labs Online database. Constraints Maximum length: 50 characters
`merchant_order_reference` `string`	Unique identifier entered while creating the order. Constraints Minimum length: 1 characterMaximum length: 50 characters
`type` `string`	Payment type. Allowed values: `CHARGEREFUNDADD_MONEY`
`status` `string`	Order status. Settled and Settlement Rejected status will be for Cross border only. Allowed values: `CREATEDPENDINGPROCESSEDAUTHORIZEDCANCELLEDATTEMPTEDFAILEDFULLY_REFUNDEDPARTIALLY_REFUNDEDSETTLEDSETTLEMENT_REJECTED`
`challenge_url` `string`	URL to accept payment. Returned only after payment is linked against the order_id.
`merchant_id` `string`	Unique identifier of the merchant in the Pine Labs Online database.
`order_amount` `object`2 nested fields	Monetary amount with currency.
`pre_auth` `boolean`	Whether pre-authorization is needed.
`part_payment` `boolean`	Whether part payment is enabled.
`allowed_payment_methods` `string[]`
`notes` `string`	Note shown against the order.
`callback_url` `string`	URL to redirect customers after successful payment.
`failure_callback_url` `string`	URL to redirect customers after failed payment.
`purchase_details` `object`4 nested fields
`payments` `PaymentItem[]`15 nested fields	Array of payment details. Returned only for orders linked with a payment.
`created_at` `string`date-time	ISO 8601 UTC timestamp when the order was created.
`updated_at` `string`date-time	ISO 8601 UTC timestamp when the order was last updated.
`integration_mode` `string`	Type of integration. Allowed values: `SEAMLESSREDIRECT`
`image_url` `string`	QR code image URL. Returned for UPI Intent with QR flow.
`payment_retries_remaining` `integer`	Number of retry attempts remaining before payment is marked as failed.
`is_mcc_transaction` `boolean`	Whether the order is a MCC transaction.
`is_domestic_txn_for_risk_enabled` `boolean`	Whether risk evaluation is enabled for domestic transactions.
`order_token` `string`	Unique identifier of the order token.
`cross_border_details` `object`6 nested fields	System-enriched cross-border details from merchant onboarding configuration. Includes payer_data and tcs_data after payment creation.

Status Codes

`200`	Order created successfully.
`400`	The request was malformed or missing required fields.
`401`	Authentication failed — missing, expired, or invalid Bearer token.
`422`	Unprocessable entity.
`500`	An unexpected error occurred on the server.

Example:

Run

Request

curl -X POST "https://api.pluralpay.in/api/pay/v1/orders" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "merchant_order_reference": "112345",
  "order_amount": {
    "value": 1100,
    "currency": "INR"
  },
  "pre_auth": false,
  "allowed_payment_methods": [
    "CARD",
    "UPI",
    "NETBANKING",
    "POINTS",
    "WALLET"
  ],
  "notes": "order1",
  "callback_url": "https://sample-callback-url",
  "failure_callback_url": "https://sample-failure-callback-url",
  "purchase_details": {
    "customer": {
      "email_id": "kevin.bob@example.com",
      "first_name": "Kevin",
      "last_name": "Bob",
      "customer_id": "123456",
      "mobile_number": "9876543210",
      "country_code": "91"
    },
    "merchant_metadata": {
      "key1": "DD",
      "key2": "XOF"
    }
  }
}'

Status:

{
  "data": {
    "order_id": "v1-5757575757-aa-hU1rUd",
    "merchant_order_reference": "112345",
    "type": "CHARGE",
    "status": "CREATED",
    "callback_url": "https://sample-callback-url",
    "failure_callback_url": "https://sample-failure-callback-url",
    "merchant_id": "123456",
    "order_amount": {
      "value": 1100,
      "currency": "INR"
    },
    "pre_auth": false,
    "part_payment": false,
    "allowed_payment_methods": [
      "CARD",
      "UPI",
      "NETBANKING",
      "POINTS",
      "WALLET"
    ],
    "notes": "order1",
    "created_at": "2024-07-09T07:57:08.022Z",
    "updated_at": "2024-07-09T07:57:08.022Z",
    "integration_mode": "SEAMLESS",
    "payment_retries_remaining": 10,
    "is_mcc_transaction": false
  }
}