04 / API Reference Developer documentation

Create a payment

Initiates a payment from a funding source to a destination account. Payments are asynchronous — the response returns a pending resource you can poll or track via webhooks.

Audience: Backend developers
Format: REST reference (OpenAPI)
Auth: Bearer token

POST https://api.meridianpay.io/v1/payments

Request headers

Header	Value
`Authorization`	`Bearer <secret_key>`
`Idempotency-Key`	Unique string to safely retry the request.

Body parameters

Field	Type	Required	Description
`amount`	integer	Yes	Amount in the smallest currency unit (e.g. paise).
`currency`	string	Yes	ISO 4217 code, e.g. `INR`.
`source_id`	string	Yes	ID of the funding source.
`destination_id`	string	Yes	ID of the payee account.
`reference`	string	No	Your own identifier, shown on statements.

Example request

# cURL
curl https://api.meridianpay.io/v1/payments \
  -H "Authorization: Bearer sk_live_4f2a…" \
  -H "Idempotency-Key: a1b2c3d4" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 250000,
    "currency": "INR",
    "source_id": "src_9812",
    "destination_id": "acct_5567",
    "reference": "INV-4471"
  }'

Example response `201 Created`

{
  "id": "pay_7c1f9a",
  "status": "pending",
  "amount": 250000,
  "currency": "INR",
  "reference": "INV-4471",
  "created_at": "2026-06-12T09:14:22Z"
}

Error codes

Status	Code	Meaning
`400`	`invalid_request`	A required field is missing or malformed.
`401`	`unauthorized`	API key is missing or invalid.
`402`	`insufficient_funds`	The funding source lacks available balance.
`409`	`idempotency_conflict`	The idempotency key was reused with a different body.
`429`	`rate_limited`	Too many requests; retry after the `Retry-After` header.