Create Order

​

Overview

• 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 UPI Collection: returns an order_id and a confirmation message
• S2S Card: returns an order_id and an acs_template (Base64) for 3D Secure

​

Payment Collection Modes

​

1. Hosted Payment (Default)

​

2. S2S UPI Intent

​

3. S2S UPI Collection

​

4. S2S Card 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

​

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
• invoice: Invoice details object
• card_details: Card information object - required when mop_type is credit_card or debit_card

​

Card Payment Specific Parameters

• 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

1. 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
2. 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

​

Top-level

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

​

Buyer

​

Address (Buyer.address)

​

Product

​

Invoice

​

Card Details

• 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

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

​

Response

​

Hosted Payment Response

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

​

S2S UPI Intent Response

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

​

S2S UPI Collection Response

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

​

S2S Card Payment Response

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

​

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": "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
• S2S UPI Collection: A payment request is sent to the provided VPA, and the customer receives a notification
• UPI App Optimization: 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)

​

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

​

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