Create Order - EximPe Docs

curl --request POST \
  --url https://api-pacb-uat.eximpe.com/pg/orders/ \
  --header 'Content-Type: application/json' \
  --header 'X-API-Version: <api-key>' \
  --header 'X-Client-ID: <api-key>' \
  --header 'X-Client-Secret: <api-key>' \
  --header 'X-Merchant-ID: <api-key>' \
  --data '
{
  "amount": "2499.99",
  "currency": "INR",
  "reference_id": "ORD_2024_WH_001234",
  "return_url": "https://electronicshub.com/payment/success",
  "collection_mode": "hosted_payment",
  "mop_type": "upi",
  "buyer": {
    "name": "Priya Sharma",
    "email": "[email protected]",
    "phone": "+919876543210",
    "address": {
      "line_1": "403, Crystal Tower, Linking Road",
      "line_2": "Near Metro Station",
      "city": "Mumbai",
      "state": "Maharashtra",
      "postal_code": "400050"
    }
  },
  "product": {
    "name": "Sony WH-1000XM5 Wireless Headphones",
    "description": "Premium noise-cancelling wireless headphones with 30-hour battery life",
    "hs_code": "85183000",
    "hs_code_description": "Headphones and earphones, whether or not combined with a microphone",
    "type_of_goods": "physical_goods"
  },
  "invoice": {
    "number": "INV_WH_2024_0621",
    "date": "2024-06-21"
  }
}
'

{
  "success": true,
  "message": "Checkout session created successfully",
  "data": {
    "session_id": "session_wh_5f8e3d7a9b2c1",
    "order_id": "OD2024120456789"
  }
}

POST

orders

curl --request POST \
  --url https://api-pacb-uat.eximpe.com/pg/orders/ \
  --header 'Content-Type: application/json' \
  --header 'X-API-Version: <api-key>' \
  --header 'X-Client-ID: <api-key>' \
  --header 'X-Client-Secret: <api-key>' \
  --header 'X-Merchant-ID: <api-key>' \
  --data '
{
  "amount": "2499.99",
  "currency": "INR",
  "reference_id": "ORD_2024_WH_001234",
  "return_url": "https://electronicshub.com/payment/success",
  "collection_mode": "hosted_payment",
  "mop_type": "upi",
  "buyer": {
    "name": "Priya Sharma",
    "email": "[email protected]",
    "phone": "+919876543210",
    "address": {
      "line_1": "403, Crystal Tower, Linking Road",
      "line_2": "Near Metro Station",
      "city": "Mumbai",
      "state": "Maharashtra",
      "postal_code": "400050"
    }
  },
  "product": {
    "name": "Sony WH-1000XM5 Wireless Headphones",
    "description": "Premium noise-cancelling wireless headphones with 30-hour battery life",
    "hs_code": "85183000",
    "hs_code_description": "Headphones and earphones, whether or not combined with a microphone",
    "type_of_goods": "physical_goods"
  },
  "invoice": {
    "number": "INV_WH_2024_0621",
    "date": "2024-06-21"
  }
}
'

{
  "success": true,
  "message": "Checkout session created successfully",
  "data": {
    "session_id": "session_wh_5f8e3d7a9b2c1",
    "order_id": "OD2024120456789"
  }
}

Overview

The Create Order endpoint is the first step in the payment flow across all collection modes. It creates a new order with buyer details, product information, and your preferred payment collection settings (Hosted Payment, Server-to-Server, Payment Link, etc.). After creating an order, the response depends on the selected mode:

Hosted Payment: returns a session_id and order_id for redirecting customers to the checkout page
S2S UPI Intent: returns an order_id and intent_uri
S2S Card: returns an order_id and an acs_template (Base64) for 3D Secure
S2S Net Banking: returns an order_id and an acs_template (Base64) for bank redirect

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 Card Payment

Server-to-server card payment flow with 3D Secure authentication. For new cards, the system initiates 3D Secure verification and returns an ACS template that must be rendered on the client side to complete authentication. Card details are securely processed and can be tokenized using the Create Token API after successful payment.

4. S2S Net Banking

Server-to-server net banking flow. EximPe returns an ACS template (Base64-encoded HTML) that you render in the customer’s browser, automatically redirecting them to their bank’s net banking portal to authorise the payment.

Request Parameters

Required Parameters

reference_id: Unique identifier for the order
amount: Payment amount in decimal format
currency: 3-letter ISO currency code (e.g., INR)
return_url: URL to redirect after payment completion
buyer: Buyer details object
product: Product details object
invoice: Invoice 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) - required when using S2S with UPI
card_details: Card information object - required when mop_type is credit_card or debit_card
netbanking_details: Net banking details object - required when mop_type is net_banking

Card Payment Specific Parameters

When using card payments (mop_type is credit_card or debit_card), additional buyer information is required:

buyer.ip_address: Customer’s IP address (used for fraud prevention)
buyer.user_agent: Customer’s browser user agent (used for fraud prevention)

Card Details Options

You can provide card information in two ways:

New Card Details (for first-time payments):
- Include full card information: number, cardholder_name, expiry_month, expiry_year, cvv, network
- Required for new cards not previously saved
- Use the Create Token API after successful payment to tokenize for future use
Saved Card Token (for repeat payments):
- Use token: Previously saved card token from the Create Token API
- Include identifier: Customer identifier used when saving the card
- Include network: Card network (visa, mastercard, etc.)
- No sensitive card data required - token handles authentication

Parameter Definitions

The following tables define all request parameters, including nested objects, types, requirements, and constraints.

Top-level

Name	Type	Required	Description	Constraints
amount	string	Yes	Amount to charge, decimal string.	Format: `^[0-9]+(\.[0-9]{1,2})?$`; amount must be > 0 and ≤ 10,000,000.00
currency	string	Yes	3-letter ISO currency code.	Supported: `INR`
reference_id	string	Yes	Merchant-side unique reference for the order.	1–50 chars; use letters, numbers, and dashes; unique per merchant while order is active
collection_mode	string	No	Mode of payment collection.	Enum: `hosted_payment`, `s2s`; default `hosted_payment`
mop_type	string	No	Method of payment.	Enum: `upi`, `credit_card`, `debit_card`, `net_banking`, `wallet`, `qr`
upi_flow_type	string	Conditionally	UPI flow when `mop_type` is `UPI` and `collection_mode` is `s2s`.	Required if `mop_type=UPI` and `collection_mode=s2s`; Enum: `intent`, `collection`
return_url	string	Yes	URL to redirect after payment/auth completion.	HTTPS URL recommended
buyer	object	Yes	Buyer/customer details.	See Buyer object
product	object	Yes	Product or service being purchased.	See Product object
invoice	object	Yes	Invoice metadata.	See Invoice object
card_details	object	Conditionally	Card details or token for card payments.	Required if `mop_type` is `credit_card` or `debit_card`; See Card Details
netbanking_details	object	Conditionally	Net banking details.	Required if `mop_type` is `net_banking`; See Net Banking Details

Notes:

“Conditionally” required means the field is required only when the stated condition is met.

Buyer

Name	Type	Required	Description	Constraints
name	string	Yes	Full name of the buyer.	Max 255 chars; letters, spaces, and common name punctuation (.,-’ )
email	string	Yes	Email of the buyer.	RFC 5322 email format
phone	string	Yes	Phone number with country code.	Valid phone number; E.164 preferred (e.g., `+9198xxxxxxxx`)
address	object	Yes	Buyer address.	See Address object
ip_address	string	Optional	Customer IP address for card fraud checks.	IPv4/IPv6
user_agent	string	Optional	Browser/device user agent for card fraud checks.	typical browser user agent string

Address (Buyer.address)

Name	Type	Required	Description	Constraints
line_1	string	No	Address line 1.	Text up to ~255 chars; use standard address characters (letters, numbers, spaces, , . - / #)
line_2	string	No	Address line 2.	Text up to ~255 chars; use standard address characters (letters, numbers, spaces, , . - / #)
city	string	No	City.	Alphabetic only; Max 255 chars
state	string	No	State/Province.	Alphabetic only; Max 255 chars
postal_code	string	Yes	Postal/ZIP code.	6 chars; numbers

Product

Name	Type	Required	Description	Constraints
name	string	Yes	Product or service name.	Max 255 chars; letters, numbers, spaces, and common punctuation
description	string	No	Description of the product/service.	Max 1024 chars; letters, numbers, spaces, and common punctuation
type_of_goods	string	Yes	Nature of goods/services.	Enum: `digital_goods`, `physical_goods`, `service`
hs_code	string	Conditional	8-digit HS Code. Required for physical goods	Max 8 chars; numbers
hs_code_description	string	No	HS Code description.	Max 1024 chars; letters, numbers, spaces, and common punctuation

Invoice

Name	Type	Required	Description	Constraints
number	string	Yes	Invoice number.	Max 255 chars; letters, numbers, dashes/slashes
date	string	No	Invoice date (ISO 8601).	Format: `YYYY-MM-DD`

Card Details

Provide one of the following variants when mop_type is credit_card or debit_card:

New card (full PAN):
- number (string, required): PAN; numeric 12-19 digits
- cardholder_name (string, required): Name on card; max 128 chars
- expiry_month (string, required): MM format; 01-12
- expiry_year (string, required): YYYY; current year or later
- cvv (string, required): 3-4 digits
- network (string, required): Enum: visa, mastercard, rupay, amex, diners, discover
- nickname (string, required): Friendly label; max 64 chars
- identifier (string, required): Customer identifier used for future reference
Saved card (tokenized):
- token (string, required): Token from Create Token API
- identifier (string, required): Customer identifier used when saving the card
- network (string, required): Card network; same enum as above

Security:

Do not log or store raw PAN/CVV. Use HTTPS and comply with applicable PCI requirements.

Net Banking Details

Provide the following when mop_type is net_banking:

Name	Type	Required	Description	Constraints
bank_name	string	Yes	Name of the customer’s bank.	Must be one of the supported bank names — see Supported Banks

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 Card Payment Response

For S2S Card Payment mode, the response includes:

order_id: Unique order identifier
acs_template: Base64-encoded HTML template for 3D Secure authentication

Important: The acs_template must be decoded from Base64 and rendered in the customer’s browser to complete the 3D Secure authentication process.

S2S Net Banking Response

For S2S Net Banking mode, the response includes:

order_id: Unique order identifier
acs_template: Base64-encoded HTML form that redirects the customer to their bank’s net banking portal

Important: Decode the acs_template from Base64 and render it in the customer’s browser. The embedded form auto-submits to the bank’s portal.

Examples

{
  "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": "[email protected]",
    "phone": "+919812345678",
    "address": {
      "line_1": "221B Baker Street",
      "city": "Mumbai",
      "state": "Maharashtra", 
      "postal_code": "400001"
    }
  },
  "product": {
    "name": "Wireless Headphones",
    "type_of_goods": "physical_goods"
  }
}

Response Examples

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

Implementation Notes

UPI Payments

S2S UPI Intent: The response includes a UPI intent link that can be used to open UPI apps directly

Card Payments

3D Secure Flow: For new cards, the system initiates 3D Secure verification
ACS Template Processing:
1. Decode the Base64 acs_template from the response
2. Render the decoded HTML in the customer’s browser
3. The form will auto-submit to complete 3D Secure authentication
4. Customer will be redirected back to your return_url after authentication
Card Tokenization: Use the Create Token API after successful payment to securely tokenize cards for future use
Saved Card Usage: Use previously saved card tokens for faster, more secure repeat payments
Fraud Prevention: ip_address and user_agent are required for fraud detection and prevention

New vs Saved Cards

New Cards: Require full card details and may trigger 3D Secure authentication
Saved Cards: Use tokens for faster processing, reduced 3D Secure requirements, and enhanced security
Token Benefits: No sensitive data exposure, faster checkout, improved conversion rates

Net Banking Payments

ACS Template: Decode the Base64 acs_template and render it in the customer’s browser — the embedded form auto-submits to the bank’s portal
Required Fields: buyer.ip_address and buyer.user_agent are required for fraud prevention
Supported Banks: See the full list of supported banks

Security Considerations

Card Data: Never log or store card details in your application
3D Secure: Always implement proper 3D Secure handling for card payments
Token Management: Use the Card Token APIs for managing saved cards

Authorizations

X-Client-ID

string

header

required

Client Application ID - Your unique application identifier used to authenticate API requests. You can find your Client ID in the Developer Settings section of the merchant dashboard.

X-Client-Secret

string

header

required

Client Secret Key - Your secret key used alongside the Client ID for secure authentication. Keep this confidential and never expose it in client-side code. Available in the Developer Settings section of the merchant dashboard.

X-Merchant-ID

string

header

required

Merchant Identifier - The unique ID for the merchant account. This is required for PSP (Payment Service Provider) merchants who manage multiple merchant accounts. You can find merchant IDs in the Merchant Management section of the dashboard.

X-API-Version

string

header

required

API Version - Specifies which version of the API to use (e.g., '1.X.X', '2.X.X', or '3.X.X'). This header allows you to control which API version your integration uses. Default version information is available in the Developer Settings.

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,

net_banking,

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

invoice

object

Show child attributes

card_details

object

Show child attributes

Response

Order created successfully

success

boolean

required

Indicates if the request was successful

message

string

required

Response message

data

object

required

Show child attributes

Get Order Status

​Overview

​Payment Collection Modes

​1. Hosted Payment (Default)

​2. S2S UPI Intent

​3. S2S Card Payment

​4. S2S Net Banking

​Request Parameters

​Required Parameters

​Optional Parameters

​Card Payment Specific Parameters

​Card Details Options

​Parameter Definitions

​Top-level

​Buyer

​Address (Buyer.address)

​Product

​Invoice

​Card Details

​Net Banking Details

​Response

​Hosted Payment Response

​S2S UPI Intent Response

​S2S Card Payment Response

​S2S Net Banking Response

​Examples

​Response Examples

​Implementation Notes

​UPI Payments

​Card Payments

​New vs Saved Cards

​Net Banking Payments

​Security Considerations

Authorizations

Body

Response

Overview

Payment Collection Modes

1. Hosted Payment (Default)

2. S2S UPI Intent

3. S2S Card Payment

4. S2S Net Banking

Request Parameters

Required Parameters

Optional Parameters

Card Payment Specific Parameters

Card Details Options

Parameter Definitions

Top-level

Buyer

Address (Buyer.address)

Product

Invoice

Card Details

Net Banking Details

Response

Hosted Payment Response

S2S UPI Intent Response

S2S Card Payment Response

S2S Net Banking Response

Examples

Response Examples

Implementation Notes

UPI Payments

Card Payments

New vs Saved Cards

Net Banking Payments

Security Considerations