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.
Amount, in cents.
ID of the charge that's refunded.
Three-letter ISO currency code, in lowercase. Must be a supported currency.
An arbitrary string attached to the object. You can use this for displaying to users (available on non-card refunds only).
ID of the ChargeIntent that's refunded.
Reason for the refund, which is either user-provided (duplicate, fraudulent, or requested_by_customer) or generated by Frame internally (expired_uncaptured_charge).
Status of the refund. This can be pending, requires_action, succeeded, failed, or canceled.
Provides the reason for the refund failure. Possible values are: lost_or_stolen_card, expired_or_canceled_card, charge_for_pending_refund_disputed, insufficient_funds, declined, merchant_request, or unknown.
String representing the object's type. Objects of the same type share the same value.
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.
Example response
Create a refund
To initiate a refund, you must specify either a Charge or a ChargeIntent object upon which to apply it.
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 charge to refund.
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 Charge/ChargeIntent has already been refunded, or if an invalid identifier was provided.
example response
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 The 10 most recent refunds are always available by default on the Charge object.
Parameters
Only return refunds for the charge specified by this charge ID.
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 50.
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. If you provide a non-existent charge ID, this call returns an error.
Example response
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