Refunds
Refund objects facilitate the process of reimbursing a previously executed charge that remains outstanding. Refunds are directed back to the credit or debit card used for the original transaction.
The Refund object
Attributes
Unique identifier for the object.
Three-letter ISO currency code, in lowercase. Must be a supported currency.
Status of the refund. This can be pending, requires_action, succeeded, failed, or canceled.
Amount, in cents.
Reason for the refund, which is either user-provided (duplicate, fraudulent, or requested_by_customer) or generated by Frame internally (expired_uncaptured_charge).
ID of the charge intent that's refunded.
String representing the object's type. Objects of the same type share the same value.
Has the value true if the object exists in live mode or the value false if the object exists in test mode.
Time at which the object was created. Measured in seconds since the Unix epoch.
Time at which the object was last updated. Measured in seconds since the Unix epoch.
{
"id": "f60170d7-69eb-45ea-9c99-900528802246",
"currency": "usd",
"status": "refunded",
"amount": 500,
"reason": "requested_by_customer",
"charge_intent": "f4544f60-fbee-4a41-8e57-c9a5ca919c1c",
"object": "refund",
"livemode": false,
"created": 1737104157,
"updated": 1737104158
}
Create a refund
To initiate a refund, you must specify a ChargeIntent object.
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.
Parameters
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.
The identifier of the ChargeIntent to refund.
String indicating the reason for the refund. If set, possible values are duplicate, fraudulent, and requested_by_customer. 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.
Returns
Returns the Refund object if the refund succeeded. Returns an error if the ChargeIntent has already been refunded, or if an invalid identifier was provided.
curl --request POST \
--url https://api.framepayments.com/v1/refunds \
--header 'Authorization: Bearer API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"amount": 500,
"charge_intent": "1d32f2f1-6110-4e06-83e6-1953c9f16378"
}'
{
"id": "7f3de047-374a-47a6-9199-e9b0a8ed9167",
"currency": "usd",
"status": "refunded",
"amount": 500,
"reason": null,
"charge_intent": "1d32f2f1-6110-4e06-83e6-1953c9f16378",
"object": "refund",
"livemode": false,
"created": 1739250792,
"updated": 1739250792
}
Retrieve a refund
Retrieves the details of an existing refund.
Parameters
No parameters.
Returns
Returns a refund if you provide a valid ID. Returns an error otherwise.
Example response
List all refunds
Returns a list of all refunds you created. We return the refunds in sorted order, with the most recent refunds appearing first.
Parameters
Only return refunds for the ChargeIntent specified by this ID.
A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
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.
curl --request GET \
--url https://api.framepayments.com/v1/refunds \
--header 'Authorization: Bearer API_KEY'
{
"meta": {
"page": 1,
"url": "/v1/refunds",
"has_more": true,
"prev": null,
"next": 2
},
"data": [
{
"id": "7f3de047-374a-47a6-9199-e9b0a8ed9167",
"currency": "usd",
"status": "refunded",
"amount": 500,
"reason": null,
"charge_intent": "1d32f2f1-6110-4e06-83e6-1953c9f16378",
"object": "refund",
"livemode": false,
"created": 1739250792,
"updated": 1739250792
},
{...},
{...}
]
}
Cancel a refund
This action cancels a refund with a status of requires_action.
You can't cancel refunds in other states. Only refunds for payment methods that require customer action can enter the requires_action state.
Parameters
No parameters.
Returns
Returns the refund object if the cancellation succeeds. This call returns an error if you can't cancel the refund.
Example response