Before developing your gift card provider implementation, it's important to clearly understand the data structures and the behaviors expected by Gift Card Hub. In most cases, developers will need to map the data structures and behaviors exhibited by external gift card providers and create parsing routines in their middleware to switch back and forth between standards.

A gift card provider is an external system that manages gift cards and their transactions.

The minimum information needed to define a provider includes:

• id: the provider identifier in the context of Gift Card Hub API
• caption: the name seen by shoppers in the store checkout
• serviceUrl: the base URL that should be prepended to all provider endpoints
  
  Below you will find an example of the gift card provider data structure and more details on the usage of each parameter. Parameters that were not mentioned in our short description above can usually be set to the values in the example.

Name	Type	Description	Required?
id	string	Gift card provider identifier for API requests
serviceUrl	string	Base URL for all gift card provider middleware endpoints
caption	string	Gift card provider identifier in the store checkout
oauthProvider	string	Webstore login provider identifier in VTEX ID, used to identify users in loyalty programs	'vtex'
preAuthEnabled	bool	Indicates whether purchases using this gift card provider should be pre-authorized	true
cancelEnabled	bool	Indicates whether purchases using this gift card provider can be cancelled	true
_self	object	Indicates the relative path where this data structure can be found in Gift Card Hub, by appending the href parameter to https://api.vtex.com

Failing to define a valid oauthProvider will generate an error in your store's checkout. Most implementations should set this parameter to 'vtex'

A gift card can work as either a redeemable gift voucher or a loyalty program. Although the data structure is the same, the required fields for each behavior are slightly different.

The minimum information needed to define a gift card includes:

• id: the gift card identifier in the context of Gift Card Hub API
• balance: the amount of credit available in the gift card
• emissionDate: the date when the gift card starts being valid
• expiringDate: the date when the gift card stops being valid

When used as a redeemable gift voucher, you should also set:

• caption: the gift card identifier in checkout

Below you will find an example of the gift card data structure for a loyalty program card. The provider and transaction fields are added by Gift Card Hub.

When used as a redeemable gift voucher, you should also set:

• redemptionCode: the gift card code in checkout

Below you will find an example of the gift card data structure for a redeemable gift voucher. The provider and transaction fields are added by Gift Card Hub.

Our default display for redeemable vouchers is simply the redemption code.

If you would like to present the caption as well, you will need to customize your checkout to display it by fetching that information from the paymentData available in the vtex.js orderForm object. All the parameters that can be set when creating gift cards are listed in the table below.

Name	Type	Description
id	string	Gift card identifier for API requests
balance	number	Credit available in gift card
emissionDate	string	Date when the gift card starts being valid (ISO 8601 format)
expiringDate	string	Date when the gift card stops being valid (ISO 8601 format)
caption	string	Gift card identifier in the store checkout that is displayed for loyalty programs
relationName	string	Relationship between the customer and the store
redemptionCode	string	Code used in the store checkout to activate redeemable vouchers
redemptionToken	string	Optional code that can be used to validate redeemable vouchers (checkout customization required for user input)
provider	string	Gift card provider identifier for API requests
transaction	object	Indicates the relative path where the transactions for this gift card can be found in Gift Card Hub, by appending the href parameter to https://api.vtex.com

Some fields are shown in the order details page when gift cards are used to pay for an order:

• Code: redemptionCode
• Name: relationName
• Caption: caption
• Gift Card Issuer: provider

The image below illustrates how these might be presented in a specific order.

A gift card transaction is a record of an operation that changes the gift card balance as a side-effect, such as a purchase or a refund. Our protocol expects gift cards to store their transactions for bookkeeping throughout the different stages of the purchase process.

The minimum information needed to define a transaction includes:

• operation: indicates whether credit should be added (Credit) or redeemed (Debit)
• value: the amount of credit that should be added or redeemed
• date: the date when the transaction occurred

Once a transaction is created, the gift card provider should allow our payments gateway to interact with the typical operations seen in the transaction flow:

• Authorization: provider verifies payment details and reserves the funds for capture
• Settlement: provider captures the funds for an authorized payment
• Cancellation: provider rejects the payment and reserved funds are released

Below you will find an example of the gift card transaction data structure and more details on the usage of each parameter. Parameters that were not mentioned in our short description above can usually be set to the values in the example.

When gift card transactions are listed for a specific gift card, Gift Card expects a minimal list including only the transaction IDs and references paths where full details can be found for each gift card. This allows for better performance.

If your gift cards need code or not, it's all about how you implement your search endpoint. Our native provider requires redemption code and sometimes document (if restricted)

Loyalty program: list is fine

Gift Voucher: redemption code must return only one gift card

Checkout validates data between search and get by id

Name	Type	Description	Required?
id			Yes
providerId