Create Order

POST/api/pay/v1/orders

Create a new payment order. Returns an order with a challenge_url that can be used to redirect the customer for payment.

This endpoint serves both standard payment orders and affordability suite orders (EMI, Cardless EMI, BNPL). For affordability flows, include allowed_payment_methods with values like CREDIT_EMI, DEBIT_EMI, CARDLESS_EMI, or BNPL, and optionally provide cart_coupon_discount_amount.

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`	`CHARGE \| REFUND`	Payment type. `CHARGEREFUND`
`status`	`CREATED \| PENDING \| PROCESSED \| AUTHORIZED \| CANCELLED \| ATTEMPTED \| FAILED \| FULLY_REFUNDED \| PARTIALLY_REFUNDED`	Order status. `CREATEDPENDINGPROCESSEDAUTHORIZEDCANCELLEDATTEMPTEDFAILEDFULLY_REFUNDEDPARTIALLY_REFUNDED`
`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`	`SEAMLESS \| REDIRECT`	Type of integration. `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`
`401`
`422`	Unprocessable entity.
`500`

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)

200 OK

{
  "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": 50000,
      "currency": "INR"
    },
    "pre_auth": true,
    "part_payment": 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": "john@example.com",
        "first_name": "Kevin",
        "last_name": "Bob",
        "customer_id": "123456",
        "mobile_number": "9876543210",
        "country_code": "91",
        "billing_address": {
          "address1": "10 Downing Street Westminster London",
          "address2": "Oxford Street Westminster London",
          "address3": "Baker Street Westminster London",
          "pincode": "51524036",
          "city": "Westminster",
          "state": "Westminster",
          "country": "London",
          "full_name": "Kevin Bob",
          "adddress_type": "Home",
          "address_category": "billing"
        },
        "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",
          "full_name": "Kevin Bob",
          "adddress_type": "Home",
          "address_category": "billing"
        },
        "is_edit_customer_details_allowed": false
      },
      "merchant_metadata": {
        "clientId": "DD",
        "transactionReferenceNo": "pine-1223",
        "merchantId": "1234",
        "tid": "9000990",
        "acquirerName": "HDFC_FSS",
        "isOfferDisplayRequired": "true",
        "OfferData": "UHJvZHVjdF9Db2RlPSIgIiZQcm9kdWN0X05hbWU9IiImUGF5bWVudF9Nb2RlPUJhbmsgRU1JJkNhcmRfVHlwZT1EZWJpdCBDYXJkJkJhbmtfTmFtZT1IREZDIERlYml0JkVNSV9UZW51cmU9NiZJbnRlcmVzdF9SYXRlPTkuMCZJbnRlcmVzdF9BbW91bnQ9MTM4MTQwJk1vbnRobHlfSW5zdGFsbG1lbnQ9ODk0NjkwJkF1dGhvcml6YXRpb25fQW1vdW50PTEwMCZMb2FuX2Jvb2tpbmdfQW1vdW50PTUyMzAwMDAmSW50ZXJlc3RfQ2FzaGJhY2tfQW1vdW50PTAmSW50ZXJlc3RfQ2FzaGJhY2tfVHlwZT1EZWZlcnJlZCZBZGRpdGlvbmFsX0Nhc2hiYWNrPSIiJkFkZGl0aW9uYWxfQ2FzaGJhY2tfVHlwZT0iIiZEZXNjcmlwdGlvbj1CYW5rIEVNSSZQcm9kdWN0X1ZhbHVlPTUyMzAwMDA",
        "tenant_id": "PGATPOS",
        "is_offer_validation_required": "true"
      },
      "split_info": {
        "split_type": "AMOUNT",
        "split_details": [
          {
            "split_merchant_id": "1324",
            "split_settlement_id": "v1-241118074845-aa-wduUQF-ss-b",
            "merchant_settlement_reference": "kshjhfk",
            "amount": {
              "value": 50000,
              "currency": "INR"
            },
            "on_hold": true,
            "status": "HOLD",
            "updated_at": "2024-11-18T07:48:45.324Z"
          }
        ]
      },
      "cart_details": {
        "cart_items": [
          {
            "item_id": "9876",
            "item_name": "T Shirt",
            "item_description": "Shopping on Diwali Sale",
            "item_details_url": "https://chriscross.in/cdn/shop/files/95_800x.jpg",
            "item_image_url": "https://chriscross.in/cdn/shop/files/95_800x.jpg",
            "item_original_unit_price": 199,
            "item_discounted_unit_price": 149,
            "item_quantity": 2,
            "item_currency": "INR"
          }
        ]
      }
    },
    "payments": [
      {
        "id": "v1-5206071124-aa-mpLhF3-cc-l",
        "merchant_payment_reference": "pay-ref-001",
        "status": "PENDING",
        "payment_amount": {
          "value": 50000,
          "currency": "INR"
        },
        "base_amount": {
          "value": 50000,
          "currency": "INR"
        },
        "conversion_rate": 0.0123,
        "payment_method": "CARD",
        "payment_option": {
          "card_data": {
            "card_type": "CREDIT",
            "network_name": "VISA",
            "issuer_name": "HDFC",
            "product_name": "Visa Platinum",
            "card_category": "CONSUMER",
            "country_code": "IND",
            "token_txn_type": "ALT_TOKEN",
            "last4_digit": "1091",
            "save": false,
            "is_native_otp_eligible": true
          },
          "upi_details": {
            "txn_mode": "COLLECT",
            "payer": {
              "vpa": "kevinbob@okaxis"
            }
          },
          "netbanking_details": {
            "pay_code": "NB1531",
            "txn_mode": "REDIRECT"
          },
          "wallet_details": {
            "wallet_name": "PAYTM"
          },
          "bnpl_details": {
            "mobile": "9876543210",
            "bnpl_pay_code": "LAZYPAY"
          },
          "points_card_details": {
            "card_last4": "1234",
            "points_redeemed": "500"
          },
          "cardless_details": {
            "pan_number": "ABCDE****F",
            "registered_mobile_number": "9876543210"
          }
        },
        "acquirer_data": {
          "approval_code": "030376",
          "acquirer_reference": "202455840588334",
          "rrn": "419335023601",
          "is_aggregator": true
        },
        "offer_data": {
          "offer_details": {
            "tenure": {
              "issuer_offer_parameters": [],
              "details": [
                {
                  "product_offer_parameters": [],
                  "subvention": {
                    "breakup": {
                      "brand": {}
                    }
                  }
                }
              ]
            }
          }
        },
        "error_detail": {
          "code": "PAYMENT_DECLINED",
          "message": "Transaction declined due to insufficient balance"
        },
        "capture_data": [
          {
            "merchant_capture_reference": "f31d8c60-0dc8-4788-a577-5ced930cc175",
            "capture_amount": {
              "value": 50000,
              "currency": "INR"
            },
            "created_at": "2024-07-19T11:13:21.523516426Z"
          }
        ],
        "created_at": "2024-09-11T08:07:55.647Z",
        "updated_at": "2024-09-11T08:07:57.115Z"
      }
    ],
    "created_at": "2024-07-09T07:57:08.022Z",
    "updated_at": "2024-07-09T07:57:08.022Z",
    "integration_mode": "SEAMLESS",
    "image_url": "https://api.pluralpay.in/qr/image/v1-order-id",
    "payment_retries_remaining": 10,
    "is_mcc_transaction": false,
    "is_domestic_txn_for_risk_enabled": false,
    "order_token": "mzohdLMNCzZ2SN3k1Ppglkz4mmk9edyahe34BM%2Fu9gA%3D",
    "cross_border_details": {
      "flow_type": "NON_LRS",
      "purpose_code": "S0101",
      "commodity_type": "SERVICES",
      "requires_pan": true,
      "payer_data": {
        "first_name": "Rajesh",
        "last_name": "Patel",
        "email": "rajesh@techcorp.com",
        "phone": "9876543210",
        "country_code": "91",
        "pan": "KGEPS1880J",
        "dob": "1999-04-14",
        "name_on_pan": "TechCorp Private Limited",
        "address_line_1": "10 Downing Street Westminster London",
        "address_line_2": "Oxford Street Westminster London",
        "country": "IN",
        "is_tcs_declared": true
      }
    }
  }
}