Refunds

Create and retrieve refunds. Refunds return all or part of a charge back to the original payment method.

List refunds

Returns a list of all refunds you created. We return the refunds in sorted order, with the most recent refunds appearing first.

Query parameters
charge_intentstringoptional

Only return refunds for the ChargeIntent specified by this ID. Mutually exclusive with transfer.

transferstringoptional

Only return refunds for the Transfer specified by this ID. Mutually exclusive with charge_intent.

per_pageintegeroptional

A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.

pageintegeroptional

The page offset at which you'd like to resume fetching data.

Returns

A dictionary with a data property that contains an array of up to per_page refunds. Each entry in the array is a separate Refund object. If no other refunds are available, the resulting array is empty.

GET/v1/refunds
curl --request GET \
  --url https://api.framepayments.com/v1/refunds \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "meta": {
    "page": 1,
    "url": "/v1/refunds",
    "has_more": false,
    "prev": null,
    "next": null
  },
  "data": []
}

Create refund

To initiate a refund, specify either a Transfer or a ChargeIntent. When using a Transfer, it must be an inbound (charge-backed) transfer. Upon creating a refund, the corresponding charge, previously executed but not yet refunded, will be reimbursed. Refunds are directed back to the original credit or debit card used for the transaction.

Partial refunds are permissible, allowing for multiple partial refunds until the entire charge has been reimbursed. Once a charge has been fully refunded, it cannot be refunded again. Attempting to refund an already-refunded charge, or exceeding the remaining amount on a charge, will result in an error.

Body parameters
charge_intentnullable stringoptional

The identifier of the ChargeIntent to refund. Mutually exclusive with transfer.

transfernullable stringoptional

The identifier of the Transfer to refund. Must be an inbound (charge-backed) transfer. Mutually exclusive with charge_intent.

amountintegeroptional

A positive integer in the smallest currency unit representing how much of this charge to refund. Can refund only up to the remaining, unrefunded amount of the charge.

reasonenumoptional

String indicating the reason for the refund. If you believe the charge to be fraudulent, specifying fraudulent as the reason will add the associated card and email to your block lists, and will also help us improve our fraud detection algorithms. One of duplicate, fraudulent, or requested_by_customer.

Returns

Returns the Refund object if the refund succeeded.

POST/v1/refunds
curl --request POST \
  --url https://api.framepayments.com/v1/refunds \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "4c0bbee5-b8ae-4fc7-9674-00e4139d53fb",
  "currency": "usd",
  "status": "refunded",
  "amount": 100,
  "reason": "requested_by_customer",
  "charge_intent": "0b6272ed-25b3-437a-8cb3-9d1f7fb57e2f",
  "transfer": null,
  "object": "refund",
  "livemode": false,
  "created": 1781115886,
  "updated": 1781115886
}

Get refund

Retrieves the details of an existing refund. Returns a refund if you provide a valid ID. Returns an error otherwise.

Path parameters
idstringrequired

The identifier of the refund to retrieve.

Returns

Returns a refund if you provide a valid ID.

GET/v1/refunds/{id}
curl --request GET \
  --url https://api.framepayments.com/v1/refunds/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
  --header 'Authorization: Bearer API_KEY'
RESPONSE
{
  "id": "bf5ea1d0-b9a1-47e3-8c5e-b77f32073b3c",
  "currency": "usd",
  "status": "refunded",
  "amount": 1000,
  "reason": "requested_by_customer",
  "charge_intent": "68f9d476-ab28-4333-88d3-5e186010dc81",
  "transfer": null,
  "object": "refund",
  "livemode": false,
  "created": 1781115886,
  "updated": 1781115886
}