Refunds API

This section will walk you through the refunds API to complete your refund flow, including

• Create Refund to initiate a refund
• Get Refund to inquire the status of the refund

You can see an example of the API in the Refund API Specification.

Create Refunds via API

Assume you have already created a charge that has a SUCCEEDED status. You can create a refund for that charge via the refund API (POST /api/v1/refunds), using the chargeId of the successful charge.

Example

Request:

POST https://api.beamcheckout.com/api/v1/refunds
Content-Type: application/json
Authorization: Basic {{yourMerchantId}} {{yourApiKey}}

{
  "chargeId": "{{chargeId}}",
  "reason": "your reason for refund",
}

Response:

{
  "refundId": "exampleRefundId",
}

Example lifecycle of an API refund

1. Shopper wishes to make a refund of a purchase previously made.

2. Merchant sends a refund request to Beam via the refund API (POST /api/v1/refunds).

3. Beam creates and stores a refund object with PENDING status.

4. Beam returns an id of the refund object created for the merchant to store for later lookup.

5. Merchant stores the refund id and returns a message to the shopper indicating that the refund is being processed.

6. After the refund has been successfully processed, Beam updates the refund object status to SUCCEEDED.

7. Shopper wishes to know the status of the refund being processed.

8. Merchant sends a request to retrieve a refund object with the id previously stored via the refund API ( GET /api/v1/refunds/{refundId}).

9. Beam returns a refund object with the provided id. The refund object will have a status of SUCCEEDED and will contain information about the refund such as the amount.

10. Merchant decodes the response and returns information based on the response to the shopper.

Get Refund via API

You can use the refundId in the refund creation response above in the Get Refund API ( GET /api/v1/refunds/{refundId}) to retrieve the details of a specific refund by its identifier.