Refunds API

The Refunds API returns money from a successful charge to the shopper. The following operations are available:

Create Refund (POST /api/v1/refunds): start a refund on a paid charge.
Get Refund by ID (GET /api/v1/refunds/{refundId}): read the current status of one refund.

A refund cannot be edited or canceled after it is created.

This page covers the request and response shapes. For the concepts behind them, see Refunds: what can be refunded, the refund flow, the lifecycle and statuses, and how to track the outcome. For the full schema, see the Refunds API Specification.

Create a refund

Call POST /api/v1/refunds with the chargeId of a charge that has status SUCCEEDED.


POST https://api.beamcheckout.com/api/v1/refunds
Content-Type: application/json
Authorization: Basic <base64(merchantId:apiKey)>
 
{
  "chargeId": "{{chargeId}}",
  "reason": "your reason for refund",
  "amount": 1000
}

Field	Required	Notes
`chargeId`	Yes	The charge to refund. It must be paid.
`amount`	No	In the smallest currency unit, so `1000` means 10.00 THB. Omit it to refund the maximum refundable amount.
`reason`	No	Free text, up to 500 characters. Stored on the refund for your own records.

The response carries the id of the new refund:


{
  "refundId": "exampleRefundId"
}

The refund is created with status PENDING. Store the refundId against your order, then wait for the webhook. See Track the refund.

Note

Partial refunds are only supported on CARD charges. For the other refundable payment methods, one refund has to cover the full amount of the charge.

If amount is 0 or omitted, Beam refunds the maximum refundable amount for that charge. For example, if the charge was 1000 and you already refunded 600, the maximum refundable amount is 400.

Tip

Send an idempotency key with this call. If your request times out and you retry, the key stops Beam creating a second refund for the same order.

For how to build the Authorization header, see Authentication.

Get a refund

Use the refundId from the creation response to read one refund:


GET https://api.beamcheckout.com/api/v1/refunds/{refundId}
Authorization: Basic <base64(merchantId:apiKey)>

The response holds the current status, the amount, the chargeId it belongs to, the refundReason you sent, and failureCode when the refund failed.

Polling this endpoint is the fallback way to learn the outcome. Webhooks are the recommended way, so see Track the refund before you build a polling loop.

Errors

HTTP 4xx and 5xx responses mean the request was rejected rather than the refund failing. A common one is 422 with REFUND_PENDING, which means a refund on that charge is still being processed, so you should retry later. See Error Handling.