Payments¶

A payment represents one checkout. You create it on your server, send the customer to its checkout_url, and learn the result from a webhook.

The payment object¶

{
  "id": "pay_8Kq2xV",
  "object": "payment",
  "amount": 245000,
  "currency": "NPR",
  "status": "pending",
  "methods": ["esewa", "khalti"],
  "method_used": null,
  "reference": "order_1042",
  "description": "2 × Himalayan coffee",
  "return_url": "https://himalstore.com.np/orders/1042",
  "checkout_url": "https://checkout.ourapayment.com/pay_8Kq2xV",
  "client_secret": "cs_…",
  "expires_at": "2026-11-08T10:30:00Z",
  "created_at": "2026-11-08T10:00:00Z"
}

Field	Type	Description
`id`	string	Unique ID, starting `pay_`.
`amount`	integer	Amount in paisa.
`currency`	string	Always `NPR`.
`status`	string	See statuses.
`methods`	array	Rails offered at checkout.
`method_used`	string or null	The rail the customer paid with, once known.
`reference`	string or null	Your own reference, such as an order ID.
`description`	string or null	Shown to the customer at checkout.
`return_url`	string or null	Where the customer goes after checkout.
`checkout_url`	string	Hosted checkout. Redirect the customer here.
`client_secret`	string	Full value only on the create response. Later reads return `cs_***`.
`expires_at`	string	After this, the payment moves to `expired`.
`created_at`	string	When the payment was created.

Statuses¶

Status	Meaning
`created`	Created, the customer hasn't started checkout.
`pending`	The customer is at checkout.
`processing`	The rail is confirming the payment.
`succeeded`	Paid. The money is in your rail account. Fulfil the order.
`failed`	The rail declined or the customer gave up.
`cancelled`	You cancelled it before it was paid.
`expired`	Nobody paid before `expires_at`.

succeeded, failed, cancelled and expired are final.

Create a payment¶

POST /v1/payments

Parameter	Required	Description
`amount`	yes	Positive integer, in paisa.
`methods`	yes	One or more of `esewa`, `khalti`, `fonepay`, `connectips`, `ime`. See Payment methods.
`currency`	no	`NPR` (the default and only value).
`reference`	no	Your order ID or similar. Up to 128 characters.
`description`	no	Short text shown at checkout. Up to 500 characters.
`metadata`	no	Object of your own key-value data.
`return_url`	no	URL to send the customer back to after checkout.

Unknown fields are rejected with VALIDATION_ERROR.

curl https://api.ourapayment.com/v1/payments \
  -H "Authorization: Bearer $OURA_SECRET_KEY" \
  -H "Idempotency-Key: order_1042" \
  -H "Content-Type: application/json" \
  -d '{"amount": 245000, "methods": ["esewa", "khalti"], "reference": "order_1042",
       "return_url": "https://himalstore.com.np/orders/1042"}'

Returns 201 with the payment object.

Retrieve a payment¶

GET /v1/payments/:id

curl https://api.ourapayment.com/v1/payments/pay_8Kq2xV \
  -H "Authorization: Bearer $OURA_SECRET_KEY"

List payments¶

GET /v1/payments?limit=20&starting_after=pay_8Kq2xV

Parameter	Description
`limit`	How many to return, 1–100. Default 20.
`starting_after`	A payment ID. Returns the page after it.

{ "data": [ { "id": "pay_…" } ], "has_more": true }

Cancel a payment¶

POST /v1/payments/:id/cancel

Cancels a payment that hasn't been paid yet. Returns the payment with status cancelled. You can't cancel a payment that has already succeeded.