---
title: "Create a new order"
method: POST
path: "/api/v1/orders"
tags: ["Orders"]
---

# Create a new order

`POST /api/v1/orders`

## Request

- Base URL: `https://api.crossborder.jiopay.co.in`
- URL: `https://api.crossborder.jiopay.co.in/api/v1/orders`
- Auth: HTTP bearer

Create an order for checkout in one of two ways:

- **Order without quote** — specify the amount, currency and payment methods inline (`Orders`).
- **Order with quote** — pass a `quote_id` from `POST /quotes` (with `resource: payin`) to bind the order to a quote. When supplied, the quote is the single source of truth for amount, currency, payment method and expiry; the locked fields (`amount`, `currency`, `price_id`, `payment_methods`) must not be sent (`CreateOrderWithQuoteRequest`). When a `quote_id` is supplied, the order's expiry is set to the quote's expiry.

The request variant is selected by the presence of `quote_id`.

## Request body

- union
  - Orders: Order without a quote. Amount, currency and payment methods are specified inline.
    - `customer_id` string, required: The unique identifier of customer linked to order.
    - `document_id` string: The unique identifier of document linked to order. This document entity should contain the required documents to process incoming payments. Refer to the Document entity for more details.
    - `currency` string, required: The currency code in ISO 4217 format. Supported currencies: USD, EUR and GBP.
    - `amount` number, required: The amount you want to receive, a positive integer representing the smallest currency unit. For example, if the amount is $299.00, then pass 29900 in this field. In the case of three decimal currencies, such as KWD, BHD and OMR, to represent an amount of 295.991, pass the value as 295990. And in the case of zero decimal currencies such as JPY, for amount ¥295, pass the value as 295.
    - `purpose_code` string: Purpose code for why you want to receive this payment
    - `invoice_number` string: Number/Id of the invoice submitted with order.
    - `invoice_description` string: Description about the invoice submitted with order
    - `invoice_amount` number: The amount in cents for which invoice was generated. It can be more than the amount requested in this order
    - `reference_number` string: Optional identifier to be sent for reconciliations
    - `price_id` string: The unique identifier of 'Price' entity linked to the order. This is the referral fee for this order. Note: price_id is only applicable for platform businesses.
    - `product` Product: Details of the product that the payment is related to.
      - `name` string, required: Name of the product
      - `description` string: Description of the product
    - `notes` Notes, nullable: Optional key-value pairs for attaching custom metadata (e.g. invoice references, project codes). Keys must be strings and cannot collide with reserved field names. If your business has custom field rules configured (e.g. enum constraints), values are validated against those rules. Each key appears as a separate column in CSV report exports, with corresponding values populating the rows.
    - `bank_account_details` BankAccountDetailsRequest: Optional bank account details to associate with the customer for this payment link. When provided, the bank account will be linked to the customer and associated with this payment link. Either bic_primary or bic_secondary must be provided when including this field.
      - `account_number` string, required: The bank account number
      - `bic_primary` string: SWIFT code for the bank account. Will be null if not provided in the request.
      - `bic_secondary` string: Local routing code for the bank account like IFSC. Will be null if not provided in the request.
      - `bank_customer_id` string: Optional bank customer identifier provided by the bank
    - `payment_methods` PaymentMethod[]: Array of payment methods that should be available for the customer on the checkout page. This field allows you to control which payment options your customers can use to complete the payment. You can specify one or multiple payment methods in the array.
    - `request_id` string: Optional idempotency key.
  - CreateOrderWithQuoteRequest: Order bound to a quote. The quote is the single source of truth for amount, currency, payment method and expiry — do not send amount, currency, price_id or payment_methods.
    - `quote_id` string, required: ID of a quote (from POST /api/v1/quotes with resource: "payin") to bind this order to. When supplied, the quote is the single source of truth for amount, currency, payment method, and expiry.
    - `customer_id` string, required: The unique identifier of customer linked to order.
    - `purpose_code` string: Purpose code for why you want to receive this payment.
    - `document_id` string: The unique identifier of document linked to order. This document entity should contain the required documents to process incoming payments. Refer to the Document entity for more details.
    - `invoice_number` string: Number/Id of the invoice submitted with order.
    - `invoice_description` string: Description about the invoice submitted with order
    - `invoice_amount` number: The amount in cents for which invoice was generated. It can be more than the amount requested in this order
    - `reference_number` string: Optional identifier to be sent for reconciliations
    - `product` Product: Details of the product that the payment is related to.
      - `name` string, required: Name of the product
      - `description` string: Description of the product
    - `notes` Notes, nullable: Optional key-value pairs for attaching custom metadata (e.g. invoice references, project codes). Keys must be strings and cannot collide with reserved field names. If your business has custom field rules configured (e.g. enum constraints), values are validated against those rules. Each key appears as a separate column in CSV report exports, with corresponding values populating the rows.
    - `bank_account_details` BankAccountDetailsRequest: Optional bank account details to associate with the customer for this payment link. When provided, the bank account will be linked to the customer and associated with this payment link. Either bic_primary or bic_secondary must be provided when including this field.
      - `account_number` string, required: The bank account number
      - `bic_primary` string: SWIFT code for the bank account. Will be null if not provided in the request.
      - `bic_secondary` string: Local routing code for the bank account like IFSC. Will be null if not provided in the request.
      - `bank_customer_id` string: Optional bank customer identifier provided by the bank
    - `request_id` string: Optional idempotency key.

## Response `201`

Created

- OrderResponse
  - `id` string: The unique identifier for the order.
  - `customer_id` string: The unique identifier of customer linked to order.
  - `document_id` string: The unique identifier of document linked to order. This document entity should contain the required documents to process incoming payments. Refer to the Document entity for more details.
  - `status` 'active' | 'paid' | 'failed' | 'action_required' | 'under_review' | 'expired': The status of the Order.
  - `currency` string: The currency code in ISO 4217 format. Supported currencies: USD, EUR and GBP.
  - `amount` number: The amount you want to receive, a positive integer representing the smallest currency unit. For example, if the amount is $299.00, then pass 29900 in this field. In the case of three decimal currencies, such as KWD, BHD and OMR, to represent an amount of 295.991, pass the value as 295990. And in the case of zero decimal currencies such as JPY, for amount ¥295, pass the value as 295.
  - `purpose_code` string: Purpose code for why you want to receive this payment
  - `invoice_number` string: Number/Id of the invoice submitted with order.
  - `invoice_description` string: Description about the invoice submitted with order
  - `invoice_amount` number: The amount in cents for which invoice was generated. It can be more than the amount requested in this order
  - `reference_number` string: Optional identifier to be sent for reconciliations
  - `price_id` string: The unique identifier of 'Price' entity linked to the order. This is the referral fee for this order. Note: price_id is only applicable for platform businesses.
  - `product` Product: Details of the product that the payment is related to.
    - `name` string, required: Name of the product
    - `description` string: Description of the product
  - `notes` Notes, nullable: Optional key-value pairs for attaching custom metadata (e.g. invoice references, project codes). Keys must be strings and cannot collide with reserved field names. If your business has custom field rules configured (e.g. enum constraints), values are validated against those rules. Each key appears as a separate column in CSV report exports, with corresponding values populating the rows.
  - `bank_account_details` BankAccountDetailsResponse: Bank account details associated with the customer for this payment link.
    - `account_number` string, required: The bank account number
    - `bic_primary` string, nullable: SWIFT code for the bank account. Will be null if not provided in the request.
    - `bic_secondary` string, nullable: Local routing code for the bank account like IFSC. Will be null if not provided in the request.
    - `bank_customer_id` string, nullable: Optional bank customer identifier provided by the bank
  - `payment_methods` PaymentMethod[]: Array of payment methods that should be available for the customer on the checkout page.
  - `created_at` string: Timestamp representing when the order was created
  - `updated_at` string: Timestamp representing when the order was last updated
  - `request_id` string: Optional idempotency key.
  - `rfi_documents` RfiDocument[]: List of required documents for RFI (Request for Information). This field is only present when the order status is 'action_required', indicating that sanction screening has been triggered and additional documents are required to proceed with the payment.
    - `rfi_doc_id` string, required: Unique identifier for the required RFI document
    - `name` string, required: Name/type of the required document

## Other responses

- `400`: Bad Request

---

[API](https://skmtc.dev/jiopay/apis/cross-border.md) - [All operations](https://skmtc.dev/jiopay/apis/cross-border/llms.txt) - [OpenAPI document](https://skmtc.dev/jiopay/apis/cross-border/revisions/b3e97f5918d4?raw)