Private preview

Non-payment operations Private preview

Activate, reload, check balance, and cash out gift cards. Use void to undo a successful operation.

Private preview

Request access to the Gift card private preview by contacting your Account Executive or by sending an email to with the following information:

• Use case for in-person and/or online gift card acceptance
• Terminal device and integration type
• Gift card provider
• Country/countries where gift cards will be accepted
• Estimated annual gift card transaction volume

Gift card operations are actions you can perform on a gift card, such as activation, reload, cash out, balance check, and void. Each endpoint returns a GiftCardOperation.

If you need to undo an operation, you can void an operation within 24 hours.

Before you begin

All operations require a GiftCard object. If you haven’t created one yet, see Create a gift card. For card-present integrations, see Accept gift card payments on Terminal.

Activate a gift card

Activate a gift card and optionally load an initial balance onto it. Pass the optional balance hash to set the initial balance at activation time.

Command Line

cURL

The response returns a GiftCardOperation object with the type set to activation.

Reload a gift card

Add funds to an existing gift card. Use this endpoint when a customer wants to add funds to their card or when you issue a gift card refund.

For a customer-initiated reload, complete these actions separately:

1. Collect payment from the customer (for example, using a PaymentIntent ).
2. After the payment succeeds, call this endpoint to add the amount to the gift card.

Command Line

cURL

The response returns a GiftCardOperation object with the type set to reload. The reload.previous_balance field reflects the card balance before the reload.

If the payment succeeds but the reload fails, refund the customer’s payment separately.

Check balance

Checks the current balance on a gift card. Balance checks call the gift card provider in real time. Stripe doesn’t cache balances because operations can occur off Stripe.

Command Line

cURL

Returns a GiftCardOperation object with the type set to balance_check.

Cash out a gift card

Cash out a gift card in full and set its balance to zero. Use this endpoint when a business needs to convert a card’s remaining balance to cash (for example, to meet local requirements or at the customer’s request). The previous_balance field shows the balance that Stripe cashed out.

Command Line

cURL

The response returns a GiftCardOperation object with the type set to cashout.

Void a gift card operation

Void a previously completed gift card operation to reverse its effect on the card. Use this endpoint if you performed an operation by mistake (for example, if you loaded the wrong amount or activated the wrong card).

Voidable operations

You can only void activation, reload, and cashout operations. You can’t void a balance_check or a void operation.

Restrictions

These restrictions apply when you void a gift card operation:

• The operation must have a status of succeeded .
• The operation must not have already been voided.
• The operation must have completed within the last 24 hours.

Even when an operation meets these conditions, the gift card provider can reject the void if other activity on the card depends on it—for example, voiding an activation after the card has already been reloaded. If the provider rejects the void, the original operation stands.

Command Line

cURL

The response returns a new GiftCardOperation object representing the void with a type set to activation_void, reload_void, or cashout_void. Stripe doesn’t modify the original operation.

For reload_void and cashout_void, the response includes the card balance after Stripe voids the operation.

Retrieve a gift card operation

Retrieve a specific gift card operation by its ID. Use this endpoint to look up the result of a previous gift card action.

Command Line

cURL

The response returns the GiftCardOperation object.

You can expand the gift_card field. Pass expand[]=gift_card in the request to include the full gift card object in the response.

Use Connect

For any operation, use on_behalf_of to specify the account that has the gift card provider credentials.

Command Line

cURL