Create Order

​

Overview

​

Payment Collection Modes

​

1. Hosted Payment (Default)

​

2. S2S UPI Intent

​

3. S2S UPI Collection

​

4. S2S Card Payment

​

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
• 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 (required for fraud prevention)
• buyer.user_agent: Customer’s browser user agent (required 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 Save Card API after successful payment to tokenize for future use
2. Saved Card Token (for repeat payments):
   • Use token: Previously saved card token from the Save Card 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

​

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