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 →

Request Body

Name	Type	Description
`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.
`order_amount`	`object`required	Monetary amount with currency.
`value`	`integer`required	Amount in the smallest currency unit (e.g., paisa for INR).
`currency`	`string`required	Three-letter ISO 4217 currency code.
`pre_auth`	`boolean`	Whether pre-authorization is needed.
`allowed_payment_methods`	`string[]`	Payment methods to offer the customer.
`notes`	`string`	Note to show against the order.
`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`	Purchase details including customer information.
`customer`	`object`	Customer information.
`merchant_metadata`	`object`	Arbitrary key-value pairs for merchant use. Maximum 10 pairs, 256 characters each.
`cart_details`	`object`	Cart details for the purchase.
`split_info`	`object`	Split settlement information for marketplace flows.
`split_type`	`string`	Type of split.
`split_details`	`SplitDetail[]`	Array of split details.
`is_mcc_transaction`	`string`	Identifies the order type for MCC transactions. Set to "true" for MCC transactions.
`base_amount`	`object`	Monetary amount with currency.
`value`	`integer`required	Amount in the smallest currency unit (e.g., paisa for INR).
`currency`	`string`required	Three-letter ISO 4217 currency code.
`cart_coupon_discount_amount`	`object`	Monetary amount with currency.
`value`	`integer`required	Amount in the smallest currency unit (e.g., paisa for INR).
`currency`	`string`required	Three-letter ISO 4217 currency code.
`cross_border_details`	`object`	Cross-border payment details for Cross Border Import enabled merchants. Required when the merchant is enabled for cross-border transactions.
`settlement_currency`	`string`	The currency in which the merchant wants to receive settlement. Defaults to the default settlement currency configured during merchant onboarding.
`hs_code`	`string`	Harmonized System (HS) code for the goods/services being traded. Must be a 6-to-10 digit numeric code. Required when commodity_type is GOODS.
`hs_description`	`string`	Description of the goods/services corresponding to the HS code. Required when commodity_type is GOODS.
`iec_code`	`string`	Importer-Exporter Code (IEC) issued by DGFT, India. Must be a 1-to-10 digit numeric code.

Response

Name	Type	Description
`data`	`object`
`order_id`	`string`	Unique identifier of the order in the Pine Labs Online database.
`merchant_order_reference`	`string`	Unique identifier entered while creating the order.
`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`	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`
`payments`	`PaymentItem[]`	Array of payment details. Returned only for orders linked with a payment.
`created_at`	`string`	ISO 8601 UTC timestamp when the order was created.
`updated_at`	`string`	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`	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:

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

Run this request

Bearer token

Request body (JSON)

Status:

200 OK

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