---
title: "Create a payment"
method: POST
path: "/api/v1/payment"
tags: ["Payments"]
---

# Create a payment

`POST /api/v1/payment`

## Request

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

Creates a payment for an order or subscription. For initial payments, card details and a callback URL are required. For subsequent payments on as_presented subscriptions, the card from the last successful payment is reused, and request_id, amount, and currency are required instead.

Either order_id or subscription_id must be provided, but not both.

## Request body

- CreatePaymentRequest: Either order_id or subscription_id must be provided, but not both. For initial payments, card and callback_url are required. For subsequent payments on as_presented subscriptions, the card from the last successful payment is reused, and request_id, amount, and currency are required instead.
  - `order_id` string: The unique identifier for the order. Either order_id or subscription_id must be provided, but not both.
  - `subscription_id` string: The unique identifier for the subscription. Either order_id or subscription_id must be provided, but not both.
  - `method` 'card': Payment method. Must be card. Required for initial payments. Not required for subsequent payments (defaults to card).
  - `sequence` 'initial' | 'subsequent': Payment sequence. Use initial (default) for first-time payments or subsequent for merchant-initiated payments on as_presented subscriptions.
  - `card` PaymentCard: Card details. Required for initial payments. Not required for subsequent payments — the card from the last successful payment is reused.
    - `holder_name` string, required: The name of the card holder.
    - `number` string, required: The card number.
    - `expiry_month` string, required: The card expiry month (MM format).
    - `expiry_year` string, required: The card expiry year in 2-digit (YY) format. Send the last two digits of the expiry year (e.g. for 2030, send '30').
    - `cvv` string, required: The card CVV/CVC code.
  - `callback_url` string: HTTPS URL where the customer is redirected after payment processing. Required for initial payments. Not required for subsequent payments as there is no customer redirect involved.
  - `request_id` string: Idempotency key. Required for subsequent payments, optional for initial payments.
  - `amount` integer: Payment amount in minor units (cents). Required for subsequent subscription payments. Cannot exceed the subscription's max_amount.
  - `currency` string: Currency code in ISO 4217 format. Must match the subscription's currency for subsequent payments.
  - `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.

## Response `201`

Created

- CreatePaymentResponse
  - `payment_id` string: The unique identifier for the created payment.
  - `status` 'pending' | 'success' | 'failed' | 'action_required' | 'in_progress' | 'under_review': The current status of the payment.
  - `next_steps` NextStep[]: A list of actions to be taken to complete the payment. For initial payments, this typically includes a redirect URL for 3DS/OTP authentication and a polling URL to check payment status.
    - `action` 'redirect' | 'poll': The type of action to perform.
    - `payload` object: The payload for the action. Structure varies based on the action type.
      - `url` string: The URL for the action. For redirect, this is the URL to redirect the customer to. For poll, this is the URL to poll for payment status updates.
      - `interval_in_ms` integer: The recommended polling interval in milliseconds. Only present for poll actions.

## 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)