This guide will be removed on April 29, 2022. Please use our new, easier-to-use Toast technical documentation site. All updated content is on the new site.

Multiple requests for a gift card transaction

The Toast platform may send multiple requests to your gift card integration API implementation when it processes a gift card transaction.

For example, when a restaurant employee sells a new gift card to a guest:

  • First, the Toast platform sends a balance inquiry request to verify that the new gift card is not already active and that it does not have an existing balance

  • Then the Toast platform sends an activate request to add value and make the card usable for transactions.

The following procedures describe the sequence of integration API requests that the Toast platform sends to a gift card integration API implementation to handle common gift card transaction types.

Note

The sequence of requests is described here to show the way that the Toast platform combines request types for a transaction. The specific sequence of requests is determined by the internal implementation of the Toast platform software. Make sure that your integration API implementation does not rely on any specific sequence of requests. The specific sequence of requests will change without notice.

Selling a new gift card, successful result

  1. Toast platform sends a GIFTCARD_GET_BALANCE request for the new gift card.

  2. Gift card provider sends a ERROR_CARD_NOT_ACTIVATED transaction status in the GiftCardTransactionResponse.

  3. Toast platform sends a GIFTCARD_ACTIVATE request for the new gift card.

  4. Gift card provider sends an ACCEPT transaction status in the GiftCardTransactionResponse.

Selling a new gift card, failure

  1. Toast platform sends a GIFTCARD_GET_BALANCE request for the new gift card.

  2. Gift card provider sends an ACCEPT transaction status and information about the card balance in the GiftCardTransactionResponse.

  3. Toast platform reports that the gift card is already active to restaurant employee and takes no further action.

Adding value to a gift card, successful result

  1. Toast platform sends a GIFTCARD_GET_BALANCE request for the new gift card.

  2. Gift card provider sends an ACCEPT transaction status and information about the card balance in the GiftCardTransactionResponse.

  3. Toast platform sends a GIFTCARD_ADD_VALUE request for the new gift card.

  4. Gift card provider sends an ACCEPT transaction status in the GiftCardTransactionResponse.

Adding value to a gift card, failure

  1. Toast platform sends a GIFTCARD_GET_BALANCE request for the new gift card.

  2. Gift card provider sends an ERROR_CARD_NOT_ACTIVATED transaction status in the GiftCardTransactionResponse.

  3. Toast platform reports that the gift card is not active to restaurant employee and takes no further action.