Private preview
Accept a gift card payment Private preview
Learn how to accept gift card payments using the Payment Intents API.
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 payments use the Payment Intents API and the gift_card payment method. Because gift card redemptions don’t involve fund movement, Stripe returns a PaymentRecord instead of a Charge.
Your integration must use a .preview API version. To access preview features, use the public preview SDKs or specify a Stripe version in your request header.
Set up Stripe Server-side
To get started, create a Stripe account.
Use our official libraries for access to the Stripe API from your application:
Command Line
Select a language
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
# Available as a gem
sudo gem install stripe
Gemfile
Select a language
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
# If you use bundler, you can add this line to your Gemfile
gem 'stripe'
Create a gift card Server-side
When a customer redeems a gift card, create a gift_card object with the card details.
Command Line
cURL
Note
The pin parameter is not supported when creating fiserv_valuelink gift cards.
Store the gift card id so you can use it for all gift card operations.
Create a PaymentIntent Server-side
Create a PaymentIntent with gift_card in allowed_payment_method_types.
Note
Gift cards aren’t supported in dynamic payment methods. You must manually list payment methods and include gift_card.
Command Line
cURL
Partial authorization
By default, Stripe declines the payment if the gift card has insufficient balance. Set payment_method_options[gift_card][request_partial_authorization] to if_available to charge up to the available balance on the gift card.
Command Line
cURL
Use Connect
Gift card payments work differently with Connect because gift card redemptions don’t involve fund movement.
- Use on _ behalf _ of to specify the account that has the gift card provider credentials.
- If your platform uses destination charges or application fees, include ignore _ transfer _ data and ignore _ application _ fee in the payment method options. Stripe can’t transfer funds to a connected account at settlement time for a gift card redemption, so confirmation fails without these parameters when gift _ card is the payment method.
- Because a redemption doesn’t move money on Stripe, move funds separately when your platform needs to settle with the connected account. If you hold the underlying funds on Stripe, create a transfer to the connected account. If the funds are held outside Stripe, the movement happens out of band and your platform manages it.
- Use Account Debit to collect fees for gift card usage from the connected account.
Command Line
cURL
Confirm the PaymentIntent Server-side
Confirm the PaymentIntent by passing the gift card ID in payment_method_data.gift_card.gift_card.
Command Line
cURL
Handle the response Server-side
Because gift card redemptions involve no money movement, Stripe doesn’t create a Charge object. Instead, the confirmed PaymentIntent references a payment_record and a latest_payment_attempt_record.
The PaymentRecord includes the amount_authorized, gift card payment_method_details, including the balance after redemption.
Partial authorization
If partial authorization occurred, the PaymentRecord amount is less than amount_requested. Collect the remaining balance with a separate PaymentIntent.
Redemption timeouts
If the gift card provider times out during redemption, Stripe transitions the PaymentIntent to requires_payment_method with code payment_method_unavailable. Because the timeout means Stripe never received a definitive response, it’s possible the provider processed the request but the response was lost in transit. To handle this safely, Stripe automatically schedules an asynchronous check with the provider and reverses the transaction if it did go through.
Treat any timeout response as a failed payment and don’t fulfill the order. You can safely retry the payment with the same or a different payment method.
Handle post-payment events Server-side
Stripe sends a payment_intent.succeeded event when the payment completes. Use the Dashboard, a custom webhook, or a partner solution to receive these events and run actions, like sending an order confirmation email to your customer, logging the sale in a database, or starting a shipping workflow.
Listen for these events rather than waiting on a callback from the client. On the client, the customer could close the browser window or quit the app before the callback executes, and malicious clients could manipulate the response. Setting up your integration to listen for asynchronous events also helps you accept more payment methods in the future. Learn about the differences between all supported payment methods.
- Handle events manually in the Dashboard Use the Dashboard to view your payments, send email receipts, handle payouts, or retry failed payments.
- Build a custom webhook Build a custom webhook handler to listen for events and build custom asynchronous payment flows. Test and debug your webhook integration locally with the Stripe CLI.
- Integrate a prebuilt app Handle common business events, such as automation or marketing and sales, by integrating a partner application.
Test your integration
In a sandbox, confirming a PaymentIntent sends the request to your gift card provider’s sandbox environment by using your onboarded credentials. This allows you test the full payment flow end-to-end against the provider’s test infrastructure. Use test gift cards issued by your provider.