This article shares some typical use cases you can support, as well as an example flow that supports each use case. You're certainly not limited to these use cases, but they can be a helpful jumping off point as you plan your implementation.
The following sample flows describe the use of gift card balances that are managed by Wix, in checkout flows on non-Wix clients. For example, in a headless project.
When a customer begins the checkout flow for a purchase of $100 on your client, and they have a gift card balance of $50:
A customer chooses to use their gift card to pay for their $100 purchase, enters the gift card code in the designated slot and clicks Apply.
The client calls Get Gift Card with the gift card code.
Example request:
The Gift Card service identifies the appropriate gift card provider, requests the gift card data from the provider, and returns the details of the customer's gift card.
Example response:
The client collects the card balance and the app ID from the response, and displays the card balance to the customer as part of the price summary at Checkout as though the gift card is used for the purchase, showing that $50 is remaining to be paid.
Continuing the example from above, the customer continues with the checkout flow:
The customer enters credit card details to cover the remaining $50, and clicks "Place Order".
The client calls Redeem Gift Card with the previously entered gift card code, the amount to be redeemed, the ID of the purchase order, and the appId collected from the Get Gift Card response.
Example request:
The Gift Card service calls the appropriate gift card provider using the provided appId, and returns a transaction ID for the redeem operation. The gift card balance is updated to $0.
Example response:
Continuing the example from above, the customer chooses to complete the checkout flow:
The customer's credit card payment fails to process, and the purchase is canceled.
The client calls Void Transaction with the transactionId from the Redeem Gift Card response, and the appId from the Get Gift Card response.
Example request:
The Gift Card service calls the appropriate gift card provider with the provided appId and voids the transaction. The customer's gift card balance is restored to $50.