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
idstring

Unique identifier for the object.

amountinteger

Amount, in cents.

chargenullable string

ID of the charge that's refunded.

currencyenum

Three-letter ISO currency code, in lowercase. Must be a supported currency.

descriptionnullable string

An arbitrary string attached to the object. You can use this for displaying to users (available on non-card refunds only).

charge_intentnullable string

ID of the ChargeIntent that's refunded.

reasonnullable enum

Reason for the refund, which is either user-provided (duplicate, fraudulent, or requested_by_customer) or generated by Frame internally (expired_uncaptured_charge).

statusnullable string

Status of the refund. This can be pending, requires_action, succeeded, failed, or canceled.

failure_reasonnullable string

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.

objectstring

String representing the object's type. Objects of the same type share the same value.

createdtimestamp

Time at which the object was created. Measured in seconds since the Unix epoch.

updatedtimestamp

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
amountinteger

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.

chargestring

The identifier of the charge to refund.

charge_intentstring

The identifier of the ChargeIntent to refund.

reasonstring

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
chargestring

Only return refunds for the charge specified by this charge ID.

charge_intentstring

Only return refunds for the ChargeIntent specified by this ID.

per_pageinteger

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

pageinteger

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