Gift Cards

Overview

Customers with a gift card can use the card to pay for their purchases just as they would use other payment methods.

During Checkout, customers have the option to provide their gift card details and have their payment deducted from the total on the card.

To offer your customers the option to purchase and pay with gift cards, ask your Project Manager to add Gift Cards to your store.

Gift Card Validation Flow

Purchasing Gift Cards

Gift cards can be purchased from the Global-e Checkout as either a virtual or physical good.

Important information about gift cards:

The gift card purchase price is displayed in the customer’s currency.
The gift card price is set according to the daily currency rate unless the price is fixed.
The value of the gift card remains the same and is not affected by currency rate changes.
The gift card is included when calculating flat rates but not included when calculating D&T
When purchased as a physical product, the gift card should exist in the Merchant manifest
When purchased as a virtual product, the gift card Is not included when calculating shipping taxes (CIF)

Paying with a Gift Card

Customers can redeem gift cards on the checkout page, whether purchased from Global-e or external vendors.

Gift cards can be used to purchase goods as well as to pay for shipping, duties, and taxes. They can also be used for purchases in a different currency than the one used to purchase the card.

For a Global-e gift card, the exchange rate from the purchase date is used. For a non-Global-e gift card, the daily exchange rate is applied.

To use a gift card in Checkout:

In Billing Summary click Gift Card.
Fill in the required fields.
Click save.
The cart total is deducted from the card balance and the amount redeemed is displayed in the sub totals.

If the total in the cart is lower than the card’s balance then the cart’s value is deducted from the card and the balance can be used for future purchases.

If the total in the cart is higher than the card balance then the customer must use a second payment method to pay the rest of the cart balance.

You can view gift card purchases in Orders under General Payment > Payment Details.

Returning a Gift Card

A physical gift card can be returned, but a virtual gift card cannot.

A customer attempting to return a virtual gift card will not find the gift card displayed in the return portal.

Refunding Gift Card Purchases

Refunds for orders purchased with a gift card are processed in the same way as other orders.

If an order is paid for with both a gift card and a credit card then the credit card is refunded first, and then the gift card.

Merchants are notified by API as well as in the reconciliation report about the gift card refund

The refund email also includes a note about money refunded from a gift card purchase.

When performing a refund, products are refunded first, then shipping, service gesture and D&T

Note

For the reconciliation report, It is necessary to know which products are refunded with money and which with gift cards.

The NotifyOrderRefund API reflects the gift card part in the refund as well.

A refund of 0 value is created when the order is purchased with a gift card as well.

In cases in which a refund is not possible, the process used for COD, where the customer’s Paypal account is

used for refunds, is taken

Gift Cards on the Invoice

In a commercial invoice:

Neither physical or virtual gift cards are included in a commercial invoice.
If an order only includes the physical gift card card, the shipment is sent as documents.
For a virtual gift card, the Invoice total amount does not match the order total.

In a VAT Invoice:

Both physical and virtual gift cards are included.
The real product price is shown.
No VAT is charged for the product.

API Calls to Platforms

3 API calls are set up with platforms to handle the gift cards.

• Validate - validates the card’s authenticity and balance

• Redeem – sent once the order is confirmed and will redeem the card’s balance

• Release – releases the card’s balance and refund it on order cancellations and refunds

Implementation Guide

Base Gift Card Model

The CardData model is used for most calls where multiple cards are passed.

Parameter name	Data type	Description
`CardId`	Long	ID of card in DB table on Global-e CORE side
`BalanceUsedInCardCurrency`	Decimal	Amount to redeem in gift card currency
`GiftCardCurrencyCode`	String	Gift card currency code
`CustomerCurrencyCode`	String	User currency code (checkout currency)
`CardFields`	Dictionary<string,string>	The Value of each field is defined in the configuration. Key – defined field name Value – user input data
`CardHash`	String	Unique hash generated for each card
`RedeemTransactionId`	String	Value which is set as a result of card redemption
`RefundedBalanceInCustomerCurrency`	Decimal	Amount of refunded money in customer currency (should be set in refund API call)
`RefundedBalanceInGiftCardCurrency`	Decimal	Amount of refunded money in gift card currency (should be set in refund API call)
`IsRefundSuccess`	Bool	If the refund is successful, set to True If the refund fails, set to False If there is no refund on the card it should be NULL
`ErrorCode`	String	Code of error which should be set during Redeem and Refund calls
`ErrorText`	String	Text of error message

Validation API Call

Use the Validate Gift Card API call to send gift card data to the platform. In return, the Platform sends the card amount and approvs that the card is valid.

Request:

Parameter name

Data type

Description

MerchantGUID

String

Merchant unique identifier

ShippingCountryCode

String

Code of country selected in Shipping country dropdown

CardFields

Dictionary<string,string>

Values of each fields defined in configuration.

Key – defined field name

Value – user input data

Response:

Parameter name	Data type	Description
`IsValid`	Bool	Flag which approves that the user entered the correct card data
`Balance`	Decimal	Available amount of money on the gift card
`CurrencyCode`	String	Code of card currency
`IsGlobalEGiftCard`	Bool	If the card was bought from Global-e, should be true
`ErrorCode`	String	Code of platform error
`ErrorText`	String	Message of platform error

Redeem API Call

Use the Redeem Gift Card API call to send the remaining card balance to the Platform, and the Platform updates the information accordingly.

Request:

Parameter name	Data type	Description
`MerchantGUID`	String	Merchant unique identifier
`ShippingCountryCode`	String	Code of country selected in Shipping country dropdown
`Cards`	List<CardData>	Data of all applied cards

Response:

Parameter name	Data type	Description
`Cards`	List<CardData>	The same list of cards from request after redeem process. `CardData.RedeemTransactionId` should be set during the redeem call. If we do not receive `RedeemTransactionId` for each card we will decide that redeem is failed
`ErrorCode`	String	Code of platform error
`ErrorText`	String	Message of platform error

Refund API Call

Use the Refund Gift Card API to send a request to return the used gift card balance in cases where an order is canceled or a new refund is created.

We send a list of all the applied gift cards and the total amount to refund in both currencies (customer currency and gift card currency) plus the conversion rate. The platform implements the code that determines the refund values per gift card.

The following values need to be set up in response for each card:

RefundedBalanceInGiftCardCurrency
Make sure it is lower than the provided value of BalanceUsedInCardCurrency
RefundedBalanceInCustomerCurrency
Make sure that it is lower than the provided value of BalanceUsedInCustomerCurrency
IsRefundSuccess
Should be set as true if the two previous values are set to the card and values are successfully refunded. If a refund is added but something went wrong – should be set as false.

If you are not adding any refunds for a particular card – do not set these values.

Request:

Parameter name	Data type	Description
`MerchantGUID`	String	Merchant unique identifier
`Cards`	List<CardData>	Data of all applied cards
`TotalToRefundInCustomerCurrency`	Decimal	Total value to refund for all gift cards in customer currency
`TotalToRefundInGiftCardCurrency`	Decimal	Total value to refund for all gift cards in Gift Card currency
`ConversionRate`	Decimal	Rate of conversion from Gift Card currency to Customer Currency

TotalToRefundInGiftCardCurrency = TotalToRefundInCustomerCurrency / ConversionRate

TotalToRefundInCustomerCurrency = TotalToRefundInGiftCardCurrency * ConversionRate

Response:

Parameter name	Data type	Description
`IsRefunded`	Bool	Return true if amounts of redeemed cards are successfully returned
`Cards`	List<CardData>	The same list of cards from request after the refund process. Values for `RefundedBalanceInCustomerCurrency` property should be set
`ErrorCode`	String	Code of platform error
`ErrorText`	String	Message of platform error

Changes in Existing Methods

The SendOrderToMerchant call is used to pass all card information,

New property GiftCards (List<CardData>) is added in BaseOrder model at the same level as InternationalDetails. The platform checks that each CardData.RedeemTransactionId is not empty.

See example in SendOrderToMerchantWithGiftCards.json

In cases where a platform has its own Send Cart Call, like some Pro merchants – the same changes should be implemented in the platforms' Send Cart Call.

SendCart

When GiftCard is purchased using Global-e checkout, a new field should be passed as part of Product model:

bool IsGiftCart

A flag that indicates that a product is a Gift Card.

Models for all calls described in CORE API calls models.cs (C#

API Call Examples

Gift Card Validation

Validation Card Request:

{
 "MerchantGUID": " ",
 "ShippingCountryCode": "UA",
 "CardFields": {
 "CardId": "card10",
 "CardPin": "111"
 }
}

Validation Success Response:

{
 "IsValid": true,
 "Balance": 1000.0,
 "CurrencyCode": "GBP",
 "IsGlobalEGiftCard": false,
}

Validation success Response for Gift Cards that were purchased through Global-e checkout

{
 "IsValid": true,
 "Balance": 1000.0,
 "CurrencyCode": "USD",
 "IsGlobalEGiftCard": true,
}

Validation Response in case of error:

{
 "IsValid": false,
 "Balance": 1000.0,
 "CurrencyCode": "USD",
 "IsGlobalEGiftCard": false,
 "ErrorCode": "Validation failed",
 "ErrorText": "Card not found"
}

Gift Card Redeem

Redeem Request:

{
 "MerchantGUID": "abcdabcd-abcd-abcd-abcd-abcdabcdabcd",
 "ShippingCountryCode": "UA",
 "Cards": [
 {
 "CardId": 167,
 "BalanceInGiftCardCurrency": 10.000000,
 "BalanceInCustomerCurrency": 21.390000,
 "GiftCardCurrencyCode": "GBP",
 "CustomerCurrencyCode": "EUR",
 "BalanceUsedInCardCurrency": 10.000000,
 "BalanceUsedInCustomerCurrency": 21.390000,
 "CardFields": {
 "CardId": "card10",
 "CardPin": "111"
 },
 ],
 }
 ]
}

Redeem success Response:

{
 "Cards": [
 {
 "CardId": 167,
 "BalanceInGiftCardCurrency": 10.000000,
 "BalanceInCustomerCurrency": 21.390000,
 "GiftCardCurrencyCode": "GBP",
 "CustomerCurrencyCode": "EUR",
 "BalanceUsedInCardCurrency": 10.000000,
 "BalanceUsedInCustomerCurrency": 21.390000,
 "RedeemTransactionId": 120423,
 "CardFields": {
 "CardId": "card10",
 "CardPin": "111"
 },
 ],
 }
 ],
}

Gift Card Refund

Refund Request:

{
 "MerchantGUID": "abcdabcd-abcd-abcd-abcd-abcdabcdabcd",
 "Cards": [
 {
 "CardId": 167,
 "BalanceInGiftCardCurrency": 10.000000,
 "BalanceInCustomerCurrency": 21.390000,
 "GiftCardCurrencyCode": "GBP",
 "CustomerCurrencyCode": "EUR",
 "BalanceUsedInCardCurrency": 10.000000,
 "BalanceUsedInCustomerCurrency": 21.390000,
 "RedeemTransactionId": 120423,
 "CardFields": {
 "CardId": "card10",
 "CardPin": "111"
 },
 ],
 }
 ],
 "TotalToRefundInCustomerCurrency": 21.390000,
 "TotalToRefundInGiftCardCurrency": 10.00,
 "ConversionRate": 2.138827
 }

Refund success response:

{
 "Cards": [
 {
 "CardId": 167,
 "BalanceInGiftCardCurrency": 10.000000,
 "BalanceInCustomerCurrency": 21.390000,
 "GiftCardCurrencyCode": "GBP",
 "CustomerCurrencyCode": "EUR",
 "BalanceUsedInCardCurrency": 10.000000,
 "BalanceUsedInCustomerCurrency": 21.390000,
 "RedeemTransactionId": 120423,
 "CardFields": {
 "CardId": "card10",
 "CardPin": "111"
 },
 ],
 "RefundedBalanceInGiftCardCurrency": 10.000000,
 "RefundedBalanceInCustomerCurrency": 21.390000,
 "IsRefundSuccess": true
- CONFIDENTIAL -
| P a g e 9
 }
 ],
 "IsRefunded": true,
 }
}

Refund multiple cards request:

{
 "MerchantGUID": "abcdabcd-abcd-abcd-abcd-abcdabcdabcd",
 "Cards": [
 {
 "CardId": 167,
 "BalanceInGiftCardCurrency": 10.000000,
 "BalanceInCustomerCurrency": 21.390000,
 "GiftCardCurrencyCode": "GBP",
 "CustomerCurrencyCode": "EUR",
 "BalanceUsedInCardCurrency": 10.000000,
 "BalanceUsedInCustomerCurrency": 21.390000,
 "RedeemTransactionId": 120423,
 "CardFields": {
 "CardId": "card10",
 "CardPin": "111"
 },
 ],
 },
{
 "CardId": 168,
 "BalanceInGiftCardCurrency": 10.000000,
 "BalanceInCustomerCurrency": 21.390000,
 "GiftCardCurrencyCode": "GBP",
 "CustomerCurrencyCode": "EUR",
 "BalanceUsedInCardCurrency": 10.000000,
 "BalanceUsedInCustomerCurrency": 21.390000,
 "RedeemTransactionId": 120424,
 "CardFields": {
 "CardId": "card20",
 "CardPin": "222"
 },
 ],
 }
 ],
 "TotalToRefundInCustomerCurrency": 42.77654,
 "TotalToRefundInGiftCardCurrency": 20.00,
 "ConversionRate": 2.138827
 },

Refund multiple cards success response:

{
 "Cards": [
 {
 "CardId": 167,
 "BalanceInGiftCardCurrency": 10.000000,
 "BalanceInCustomerCurrency": 21.390000,
 "GiftCardCurrencyCode": "GBP",
 "CustomerCurrencyCode": "EUR",
 "BalanceUsedInCardCurrency": 10.000000,
 "BalanceUsedInCustomerCurrency": 21.390000,
 "RedeemTransactionId": 120423,
 "CardFields": {
 "CardId": "card10",
 "CardPin": "111"
 },
 ],
 "RefundedBalanceInGiftCardCurrency": 10.000000,
 "RefundedBalanceInCustomerCurrency": 21.390000,
 "IsRefundSuccess": true
 },
{
 "CardId": 168,
 "BalanceInGiftCardCurrency": 10.000000,
 "BalanceInCustomerCurrency": 21.390000,
 "GiftCardCurrencyCode": "GBP",
 "CustomerCurrencyCode": "EUR",
 "BalanceUsedInCardCurrency": 10.000000,
 "BalanceUsedInCustomerCurrency": 21.390000,
 "RedeemTransactionId": 120424,
 "CardFields": {
 "CardId": "card20",
 "CardPin": "222"
 },
 ],
 "RefundedBalanceInGiftCardCurrency": 10.000000,
 "RefundedBalanceInCustomerCurrency": 21.390000,
 "IsRefundSuccess": true
 }
 ],
 "IsRefunded": true,
 }
}

Refund one card for multiple cards order request:

{
 "MerchantGUID": "abcdabcd-abcd-abcd-abcd-abcdabcdabcd",
 "Cards": [
 {
 "CardId": 167,
 "BalanceInGiftCardCurrency": 10.000000,
 "BalanceInCustomerCurrency": 21.390000,
 "GiftCardCurrencyCode": "GBP",
 "CustomerCurrencyCode": "EUR",
 "BalanceUsedInCardCurrency": 10.000000,
 "BalanceUsedInCustomerCurrency": 21.390000,
 "RedeemTransactionId": 120423,
 "CardFields": {
 "CardId": "card10",
 "CardPin": "111"
 },
 ],
 },
{
 "CardId": 168,
 "BalanceInGiftCardCurrency": 10.000000,
 "BalanceInCustomerCurrency": 21.390000,
 "GiftCardCurrencyCode": "GBP",
 "CustomerCurrencyCode": "EUR",
 "BalanceUsedInCardCurrency": 10.000000,
 "BalanceUsedInCustomerCurrency": 21.390000,
 "RedeemTransactionId": 120424,
 "CardFields": {
 "CardId": "card20",
 "CardPin": "222"
 },
 ],
 }
 ],
 "TotalToRefundInCustomerCurrency": 21.390000,
 "TotalToRefundInGiftCardCurrency": 10.00,
 "ConversionRate": 2.138827
 },

Refund one card for multiple cards order success response:

{
 "Cards": [
 {
 "CardId": 167,
 "BalanceInGiftCardCurrency": 10.000000,
 "BalanceInCustomerCurrency": 21.390000,
 "GiftCardCurrencyCode": "GBP",
 "CustomerCurrencyCode": "EUR",
 "BalanceUsedInCardCurrency": 10.000000,
 "BalanceUsedInCustomerCurrency": 21.390000,
 "RedeemTransactionId": 120423,
 "CardFields": {
 "CardId": "card10",
 "CardPin": "111"
 },
 ],
 "RefundedBalanceInGiftCardCurrency": 10.000000,
 "RefundedBalanceInCustomerCurrency": 21.390000,
 "IsRefundSuccess": true
 },
{
 "CardId": 168,
 "BalanceInGiftCardCurrency": 10.000000,
 "BalanceInCustomerCurrency": 21.390000,
 "GiftCardCurrencyCode": "GBP",
 "CustomerCurrencyCode": "EUR",
 "BalanceUsedInCardCurrency": 10.000000,
 "BalanceUsedInCustomerCurrency": 21.390000,
 "RedeemTransactionId": 120424,
 "CardFields": {
 "CardId": "card20",
 "CardPin": "222"
 },
 ],
 "RefundedBalanceInGiftCardCurrency": null, //not required
 "RefundedBalanceInCustomerCurrency": null, //not required
 "IsRefundSuccess": null //not required
 }
 ],
 "IsRefunded": true,
 }
}

Refund one card for multiple cards order failed response:

{
 "Cards": [
 {
 "CardId": 167,
 "BalanceInGiftCardCurrency": 10.000000,
 "BalanceInCustomerCurrency": 21.390000,
 "GiftCardCurrencyCode": "GBP",
 "CustomerCurrencyCode": "EUR",
 "BalanceUsedInCardCurrency": 10.000000,
 "BalanceUsedInCustomerCurrency": 21.390000,
 "RedeemTransactionId": 120423,
 "CardFields": {
 "CardId": "card10",
 "CardPin": "111"
 },
 ],
 "RefundedBalanceInGiftCardCurrency": 10.000000,
 "RefundedBalanceInCustomerCurrency": 21.390000,
 "IsRefundSuccess": false,
 "ErrorCode": "Internal Error",
 "ErrorText": "Fail in card refund."
 },
{
 "CardId": 168,
 "BalanceInGiftCardCurrency": 10.000000,
 "BalanceInCustomerCurrency": 21.390000,
 "GiftCardCurrencyCode": "GBP",
 "CustomerCurrencyCode": "EUR",
 "BalanceUsedInCardCurrency": 10.000000,
 "BalanceUsedInCustomerCurrency": 21.390000,
 "RedeemTransactionId": 120424,
 "CardFields": {
 "CardId": "card20",
 "CardPin": "222"
 },
 ],
 "RefundedBalanceInGiftCardCurrency": null, //not required
 "RefundedBalanceInCustomerCurrency": null, //not required
 "IsRefundSuccess": null //not required
 }
 ],
 "IsRefunded": false,
 "ErrorCode": "Internal Error",
 "ErrorText": "Fail to refund one or more cards."
 }
}

Documentation Portal

Gift Cards

Overview

Gift Card Validation Flow

Purchasing Gift Cards

Paying with a Gift Card

Returning a Gift Card

Refunding Gift Card Purchases

Note

Gift Cards on the Invoice

API Calls to Platforms

Implementation Guide

Base Gift Card Model

Validation API Call

Redeem API Call

Refund API Call

Changes in Existing Methods

API Call Examples