Payments

Submit a payment request for one of your end-users, paid into an end-user's bank account. Create the end-user and register their bank account first, then reference them by id. Each request carries your own transactionId and is tracked through a status lifecycle (RECEIVED → PROCESSING → COMPLETED/FAILED).

Request fields

All fields are required. Beneficiary identity and bank details are resolved from the referenced end-users.

Field	Type	Description
transactionId	string	Your reference for the payment. Unique within your account — reusing one returns 409.
amount	string (decimal)	Payment amount, up to 2 decimal places. Sent as a string to preserve precision.
currency	string (ISO 4217)	Three-letter currency code, e.g. INR. Normalised to upper case.
userId	string	Id of the end-user this payment is for. Must be one of your end-users.
bankOwnerId	string	Id of the end-user who owns the destination bank account. That end-user must have a bank account on file.

GET/api/v1/payments/received

List payment requests

Returns up to 100 payment requests belonging to the API key's owner, newest first. The end-user and bank details are expanded inline.

200 Response

{
  "data": [
    {
      "id": "cmpqz8ww70002rzdom9mmux4i",
      "transactionId": "TXN-20260529-1001",
      "amount": "2500.5",
      "currency": "INR",
      "status": "RECEIVED",
      "createdAt": "2026-05-29T13:48:11.527Z",
      "user": {
        "id": "clx9p2k3a0000abc",
        "email": "[email protected]",
        "name": "Ada Lovelace",
        "country": "IN"
      },
      "bankDetails": {
        "id": "cmpqz8wf40001rzdot0kxuio0",
        "ownerId": "clx9p2k3a0000abc",
        "ownerEmail": "[email protected]",
        "accountHolderName": "Ada Lovelace",
        "accountNumber": "XXXXXXXX9012",
        "ifscCode": "HDFC0001234",
        "bankName": "HDFC Bank",
        "branchName": "MG Road",
        "accountType": "SAVINGS",
        "createdAt": "2026-05-29T13:48:10.912Z"
      }
    }
  ]
}

POST/api/v1/payments/received

Create a payment request

Reference an end-user with userId and the bank account owner with bankOwnerId (also an end-user id).

Request body

{
  "transactionId": "TXN-20260529-1001",
  "amount": "2500.50",
  "currency": "INR",
  "userId": "clx9p2k3a0000abc",
  "bankOwnerId": "clx9p2k3a0000abc"
}

201 Response

{
  "id": "cmpqz8ww70002rzdom9mmux4i",
  "transactionId": "TXN-20260529-1001",
  "amount": "2500.5",
  "currency": "INR",
  "status": "RECEIVED",
  "createdAt": "2026-05-29T13:48:11.527Z",
  "user": { "id": "clx9p2k3a0000abc", "email": "[email protected]", "name": "Ada Lovelace", "country": "IN" },
  "bankDetails": {
    "id": "cmpqz8wf40001rzdot0kxuio0",
    "ownerId": "clx9p2k3a0000abc",
    "ownerEmail": "[email protected]",
    "accountHolderName": "Ada Lovelace",
    "accountNumber": "XXXXXXXX9012",
    "ifscCode": "HDFC0001234",
    "bankName": "HDFC Bank",
    "branchName": "MG Road",
    "accountType": "SAVINGS",
    "createdAt": "2026-05-29T13:48:10.912Z"
  }
}

Status	Meaning
400	Invalid body. `details` lists offending fields (e.g. non-positive `amount`).
401	Missing or invalid API key.
404	No end-user with that `userId` exists, or the `bankOwnerId` has no bank account on file.
409	A payment with this `transactionId` already exists under your account.