Create Order

POST /pg/orders/

cURL

hosted_payment

curl --request POST \
  --url https://api-staging.eximpe.com/pg/orders/ \
  --header 'Content-Type: application/json' \
  --header 'X-Client-ID: <api-key>' \
  --header 'X-Client-Secret: <api-key>' \
  --header 'X-Merchant-ID: <api-key>' \
  --data '
{
  "amount": "1000.00",
  "currency": "INR",
  "reference_id": "ORDER_123456",
  "return_url": "https://yourdomain.com/payment/callback",
  "collection_mode": "hosted_payment",
  "mop_type": "UPI",
  "buyer": {
    "name": "Alice Smith",
    "email": "[e-mail]",
    "phone": "[phone]",
    "address": {
      "line_1": "221B Baker Street",
      "line_2": "Near Central Park",
      "city": "Mumbai",
      "state": "Maharashtra",
      "postal_code": "400001"
    }
  },
  "product": {
    "name": "Wireless Headphones",
    "description": "Noise-cancelling over-ear headphones",
    "hs_code": "85183000",
    "hs_code_description": "Headphones and earphones, whether or not combined with a microphone",
    "type_of_goods": "goods"
  },
  "invoice": {
    "number": "INV_20240621",
    "date": "2024-06-21"
  }
}
'

200

hosted_payment

{
  "success": true,
  "message": "Checkout session created successfully",
  "data": {
    "session_id": "session_abc123def456",
    "order_id": "OD2000992103"
  }
}

​

Overview

The Create Order endpoint is the first step in the payment flow. It creates a new order with all the necessary details including buyer information, product details, and payment preferences.

After creating an order successfully, you’ll receive a session_id and order_id. Use the session_id to redirect the customer to the payment gateway for completing the transaction.

​

Payment Collection Modes

EximPe supports multiple payment collection modes:

​

1. Hosted Payment (Default)

The standard hosted payment flow where customers are redirected to EximPe’s secure payment page.

​

2. S2S UPI Intent

Server-to-server UPI intent flow that generates a UPI intent link for direct app-to-app payments.

​

3. S2S UPI Collection

Server-to-server UPI collection flow that sends a payment request directly to the customer’s VPA (Virtual Payment Address).

​

Request Parameters

​

Required Parameters

• amount: Payment amount in decimal format
• currency: 3-letter ISO currency code (e.g., INR)
• reference_id: Unique identifier for the order
• buyer: Buyer details object
• product: Product details object

​

Optional Parameters

• collection_mode: Payment collection mode (hosted_payment or s2s)
• mop_type: Method of payment (UPI, CREDIT_CARD, DEBIT_CARD, NET_BANKING, QR)
• upi_flow_type: UPI flow type (intent or collection) - required when using S2S with UPI
• vpa: Virtual Payment Address - required when upi_flow_type is collection
• upi_app_name: Preferred UPI app - optional, defaults to others
• return_url: URL to redirect after payment completion
• invoice: Invoice details object

​

Response

​

Hosted Payment Response

For hosted payment mode, the response includes:

• session_id: Use this to redirect customers to the payment page
• order_id: Unique order identifier

​

S2S UPI Intent Response

For S2S UPI Intent mode, the response includes:

• order_id: Unique order identifier
• intent_uri: UPI intent link that can be used to open UPI apps directly

​

S2S UPI Collection Response

For S2S UPI Collection mode, the response includes:

• order_id: Unique order identifier
• message: Confirmation message about the collection request sent to the VPA

​

Examples

Hosted Payment

{
  "amount": "1000.00",
  "currency": "INR", 
  "reference_id": "ORDER_123456",
  "collection_mode": "hosted_payment",
  "return_url": "https://yourdomain.com/payment/callback",
  "mop_type": "UPI",
  "buyer": {
    "name": "Alice Smith",
    "email": "[e-mail]",
    "phone": "[phone]",
    "address": {
      "line_1": "221B Baker Street",
      "city": "Mumbai",
      "state": "Maharashtra", 
      "postal_code": "400001"
    }
  },
  "product": {
    "name": "Wireless Headphones",
    "type_of_goods": "goods"
  }
}

​

Response Examples

Hosted Payment Response

{
  "success": true,
  "message": "Checkout session created successfully",
  "data": {
    "session_id": "session_abc123def456",
    "order_id": "OD2000992103"
  }
}

​

Notes

• For S2S UPI Intent: The response will include a UPI intent link that can be used to open UPI apps directly
• For S2S UPI Collection: A payment request will be sent to the provided VPA, and the customer will receive a notification
• The upi_app_name parameter helps optimize the intent link for specific UPI applications
• VPA format must follow the pattern: username@bank (e.g., user@paytm, 9876543210@ybl)

Authorizations

X-Client-ID · string · header · required

Client app ID. You can find your app id in the merchant dashboard.

X-Client-Secret · string · header · required

Client secret key. You can find your secret in the merchant dashboard.

X-Merchant-ID · string · header · required

Merchant ID. You can find your merchant ID in the merchant section of the merchant dashboard.

Body

application/json

Order creation request

amount · string · required

Amount in decimal format (e.g., "100.00")

Pattern: ^\d+\.\d{2}$

currency · string · required

3-letter ISO currency code (e.g., INR, USD)

Pattern: ^[A-Z]{3}$

reference_id · string · required

Unique identifier for the order

buyer · object · required

Show child attributes

product · object · required

Show child attributes

return_url · string<uri>

URL to redirect after payment

collection_mode · enum<string>

Payment collection mode

Available options: hosted_payment, s2s

mop_type · enum<string>

Method of payment type (e.g., UPI)

Available options: UPI, CREDIT_CARD, NETBANKING, DEBIT_CARD, QR

upi_flow_type · enum<string>

UPI flow type (required when collection_mode is s2s and mop_type is UPI)

Available options: intent, collection

vpa · string

Virtual Payment Address (required when upi_flow_type is collection)

Pattern: ^[a-zA-Z0-9._-]+@[a-zA-Z0-9.-]+$

upi_app_name · enum<string>

UPI app name (optional, defaults to 'others')

Available options: bhim, paytm, google_pay, phonepe, cred, amazon_pay, whatsapp, others

invoice · object

Show child attributes

Response

200

application/json

Order created successfully

success · boolean · required

Indicates if the request was successful

message · string · required

Response message

data · object · required

Show child attributes