Gift Card Purchases
This document outlines the implementation steps for a platform-agnostic checkout flow for gift card purchases using Nuvei as the payment processor, suitable for both web and mobile applications.
Present the gift card offer to the user, accounting for purchase restrictions found in the offer details:
- Minimum and maximum gift card values
- Pre-defined denominations accepted (if applicable)
Some gift card offers may only allow purchase of certain denominations. If applicable, those denominations will be specified in the offer details. See the next section for more important considerations to make when deciding what gift card values users may purchase.
Important: Individual users are subject to purchase limits of gift card offers both by purchase value and number of purchases. The current limits are $200 in gift card value per week per individual user or 5 gift card purchases per week per individual user, whichever occurs first. These limits will be enforced by the /api/v1/gift-card/purchase endpoint described in step 3. However, a user's current remaining balance (in both gift card value and purchases) may be retrieved from /api/v1/gift-cards/balance so you may decide to inform users about their individual limits ahead of time in any way you see fit in order to create the best user experience.
Gather the required parameters from your application:
- offer_uid: Unique identifier for the gift card offer
- amount: Purchase amount for the gift card
Send a POST request to /api/v1/orders/nuvei?publisher_user_id={{ PUBLISHER_USER_ID }} with the following parameters:
- offer_uid
- amount
- Redirect URLs:
- success_url: URL for successful transactions
- failure_url: URL for failed transactions
- cancel_url: URL for cancelled transactions
The response will contain a payment_token which is a URL to Nuvei's hosted checkout page.
Please make sure to URL-encode the publisher_user_id value before passing it as the query parameter.
The user with the provided publisher_user_id must have a registered email address. This is necessary for sending the user their digital gift card. If an email for that user cannot be found, no payment token will be generated and an error response will be returned.
Navigate the user to the Nuvei-hosted checkout page using the payment_token URL received in step 2.
The user enters their payment details and submits the payment for processing from Nuvei's hosted checkout page
After payment processing, Nuvei will redirect the user to one of the previously specified URLs:
- success_url: Payment was successful
- failure_url: Payment failed
- cancel_url: User cancelled the payment
Each redirect will include query parameters containing relevant transaction information such as:
- Transaction status
- Order details
- Error messages (if applicable)
- Users purchasing gift cards must have registered an email. This is necessary to know where to send the user their digital gift card.
- All redirect URLs must use standard HTTP(S) schemes. Mobile applications must implement universal links (iOS) or app links (Android) instead of custom URL schemes for deep linking
