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.

This section provides reference information about the endpoints and data types of the Toast gift card API specification. You implement the Toast gift card API so that the Toast POS system can make calls to your gift card provider service when it performs gift card transactions. For more information about implementing a Toast gift card integration and code examples, see Gift Card Integrations.

Gift Card Integration API

Base URL: /yourapiname/v1, Version: 1.0.0

A REST API that allows the Toast platform to process gift card transactions using a gift card provider that it does not currently support.

Default request content-types: application/json
Default response content-types: application/json
Schemes: https

Summary

Path Operation Description
/yourendpointname POST

Returns gift card transaction information

Paths

Returns gift card transaction information

POST /yourendpointname

Provides information about a gift card transaction processed by the Toast platform. The transaction information in the message body is intended to allow a gift card provider to perform corresponding operations on the gift card account, maintained by that provider.

You define the endpoint name for this implementation. The Toast platform makes requests to the REST path that you supply during integration setup.

Each POST request to the endpoint includes a Toast-Transaction-Type header parameter value to indicate the type of gift card transaction it represents. The possible transaction types are:

  • Activate a new gift card.
  • Add value to an active gift card.
  • Get the current balance of a gift card.
  • Redeem value from a gift card, for example for a purchase.
  • Reverse a previous transaction, for example to void a purchase made with the gift card.

The GiftCardTransaction object in the message body includes a set of information that is specific for each transaction type.

The response time for a gift card transaction request must be less than 500ms.

All gift card transactions must be considered idempotent. The implementation must handle multiple requests with the same Toast-Transaction-GUID and the same giftCardIdentifier.

Uses default content-types: application/json

A GiftCardTransaction object containing information about the gift card transaction that the Toast platform processed.

Toast-Transaction-GUID

A unique identifier of the gift card transaction, defined by the Toast platform.

header string
Toast-Restaurant-External-ID

The unique identifier of the restaurant, defined by the Toast platform.

header string
Toast-Transaction-Type

The type of gift card transaction that occurred. Values are:

  • GIFTCARD_ACTIVATE
  • GIFTCARD_ADD_VALUE
  • GIFTCARD_GET_BALANCE
  • GIFTCARD_REDEEM
  • GIFTCARD_REVERSE
header string , x ∈ { GIFTCARD_ACTIVATE , GIFTCARD_ADD_VALUE , GIFTCARD_GET_BALANCE , GIFTCARD_REDEEM , GIFTCARD_REVERSE }
Authorization

a JSON Web Token (JWT) that you can use to authenticate the request. Verify the token using the public key that you get from the Toast user management service.

header string

application/json

200 OK

OK. The transactionStatus value of the GiftCardTransactionResponse object is ACCEPT.

400 Bad Request

Bad request. The transactionStatus value of the GiftCardTransactionResponse object is one of:

  • ERROR_INVALID_TOAST_TRANSACTION_TYPE
  • ERROR_CARD_ALREADY_ACTIVATED
  • ERROR_CARD_NOT_ACTIVATED
  • ERROR_CARD_INVALID
  • ERROR_INVALID_INPUT_PROPERTIES
  • ERROR_TRANSACTION_DOES_NOT_EXIST
  • ERROR_INVALID_TOKEN
  • ERROR_TRANSACTION_CANNOT_BE_REVERSED
  • ERROR_INVALID_RESTAURANT
500 Internal Server Error

Internal server error.

Schema definitions

GiftCardTransaction: object

Information about a gift card transaction in the Toast
platform. Gift card providers are expected to handle that transaction.

The set of information in this object depends on the gift card transaction type. The transaction type is specified in the Toast-Transaction-Type header parameter for the request.

The GiftCardTransaction object includes the following values for specific transaction types:

  • GIFTCARD_ACTIVATE - includes an activateTransactionInformation value.
  • GIFTCARD_ADD_VALUE - includes an addValueTransactionInformation value.
  • GIFTCARD_GET_BALANCE - includes a getBalanceTransactionInformation value.
  • GIFTCARD_REDEEM - includes a redeemTransactionInformation value.
  • GIFTCARD_REVERSE - includes a reverseTransactionInformation value.
activateTransactionInformation: TransactionInformationActivate
addValueTransactionInformation: TransactionInformationAddValue
getBalanceTransactionInformation: TransactionInformationGetBalance
redeemTransactionInformation: TransactionInformationRedeem
reverseTransactionInformation: TransactionInformationReverse

GiftCardTransactionResponse: object

Information about a gift card transaction from the gift card provider. The Toast platform uses this information to complete guests' gift card transactions.

The set of information in this object depends on the gift card transaction type. The transaction type is specified in the Toast-Transaction-Type header parameter for the request.

All GiftCardTransactionResponse objects must include a transactionStatus value.

The GiftCardTransactionResponse object includes the following additional values for specific transaction types:

  • GIFTCARD_ACTIVATE - includes an activateResponse value.
  • GIFTCARD_ADD_VALUE - includes an addValueResponse value.
  • GIFTCARD_GET_BALANCE - includes a getBalanceResponse value.
  • GIFTCARD_REDEEM - includes a redeemResponse value.
  • GIFTCARD_REVERSE - includes a reverseResponse value.

For example, the response object for a GIFTCARD_ACTIVATE transaction includes an activateResponse value.

transactionStatus: string , x ∈ { ACCEPT , ERROR_INVALID_TOAST_TRANSACTION_TYPE , ERROR_CARD_ALREADY_ACTIVATED , ERROR_CARD_NOT_ACTIVATED , ERROR_CARD_INVALID , ERROR_INVALID_INPUT_PROPERTIES , ERROR_TRANSACTION_DOES_NOT_EXIST , ERROR_INVALID_TOKEN , ERROR_TRANSACTION_CANNOT_BE_REVERSED , ERROR_INVALID_RESTAURANT }

Indicates the result of a gift card transaction, reported by the gift card service provider. Possible values are:

  • ACCEPT - The gift card service provider processed the transaction successfully.
  • ERROR_INVALID_TOAST_TRANSACTION_TYPE - The requested Toast-Transaction-Type is not valid.
  • ERROR_CARD_ALREADY_ACTIVATED - The gift card has already been activated.
  • ERROR_CARD_NOT_ACTIVATED - The gift card has not been activated.
  • ERROR_CARD_INVALID - The gift card is not valid at the current restaurant.
  • ERROR_INVALID_INPUT_PROPERTIES - The specified JSON properties in the request body are not valid.
  • ERROR_TRANSACTION_DOES_NOT_EXIST - The transaction that is being requested to be reversed does not exist. Only occurs on a GIFTCARD_REVERSE
  • ERROR_INVALID_TOKEN - The token supplied in the Authorization header field is invalid or cannot be validated.
  • ERROR_TRANSACTION_CANNOT_BE_REVERSED - The specified transaction cannot be reversed. GIFTCARD_GET_BALANCE and GIFTCARD_REVERSE transactions cannot be reversed.
  • ERROR_INVALID_RESTAURANT - The restaurant specified by the Toast-Restaurant-External-ID is invalid.
activateResponse: TransactionResponseActivate
addValueResponse: TransactionResponseAddValue
getBalanceResponse: TransactionResponseGetBalance
redeemResponse: TransactionResponseRedeem
reverseResponse: TransactionResponseReverse

TransactionInformationActivate: object

Information about a gift card transaction in the Toast
platform that activates a new card. Gift card providers are expected to handle the transaction.

giftCardIdentifier: string

The unique identifier of the gift card.

identifierSource: string , x ∈ { KEYED , SCANNED , SWIPED , UNKNOWN }

Indicates how the Toast platform received the gift card identifier string. Values are:

  • KEYED - A restaurant employee or guest manually entered the identifier string.

  • SCANNED - A restaurant employee or guest used a barcode scanner or other scanning device to enter the identifier string.

  • SWIPED - A restaurant employee or guest used a magnetic card strip reader to enter the identifier string.

  • UNKNOWN - The Toast platform received the identifier string using a method other than KEYED, SCANNED, or SWIPED, or the method is not known.

initialBalance: number (double)

The currency amount of the funds available from the gift card.

checkIdentifier: string

The unique identifier of the check that this gift card transaction is part of. No action needs to be taken based on this identifier, it is just provided for tracking purposes.

TransactionInformationAddValue: object

Information about a gift card transaction in the Toast POS system that adds to the funds that are available on the card. Gift card providers are expected to handle the transaction.

giftCardIdentifier: string

The unique identifier of the gift card.

identifierSource: string , x ∈ { KEYED , SCANNED , SWIPED , UNKNOWN }

Indicates how the Toast platform received the gift card identifier string. Values are:

  • KEYED - A restaurant employee or guest manually entered the identifier string.

  • SCANNED - A restaurant employee or guest used a barcode scanner or other scanning device to enter the identifier string.

  • SWIPED - A restaurant employee or guest used a magnetic card strip reader to enter the identifier string.

  • UNKNOWN - The Toast platform received the identifier string using a method other than KEYED, SCANNED, or SWIPED, or the method is not known.

additionalValue: number (double)

The currency amount of the funds being added to the gift card.

checkIdentifier: string

The unique identifier of the check that this gift card transaction is part of. No action needs to be taken based on this identifier, it is just provided for tracking purposes.

TransactionInformationGetBalance: object

Information about a gift card transaction in the Toast
platform that requests the currency value of the funds available from the gift card. Gift card providers are expected to handle the transaction.

giftCardIdentifier: string

The unique identifier of the gift card.

identifierSource: string , x ∈ { KEYED , SCANNED , SWIPED , UNKNOWN }

Indicates how the Toast platform received the gift card identifier string. Values are:

  • KEYED - A restaurant employee or guest manually entered the identifier string.

  • SCANNED - A restaurant employee or guest used a barcode scanner or other scanning device to enter the identifier string.

  • SWIPED - A restaurant employee or guest used a magnetic card strip reader to enter the identifier string.

  • UNKNOWN - The Toast platform received the identifier string using a method other than KEYED, SCANNED, or SWIPED, or the method is not known.

TransactionInformationRedeem: object

Information about a gift card transaction in the Toast
platform that reduces the balance of funds available from the card. For example, when the gift card is used for a purchase. Gift card providers are expected to handle the transaction.

giftCardIdentifier: string

The unique identifier of the gift card.

identifierSource: string , x ∈ { KEYED , SCANNED , SWIPED , UNKNOWN }

Indicates how the Toast platform received the gift card identifier string. Values are:

  • KEYED - A restaurant employee or guest manually entered the identifier string.

  • SCANNED - A restaurant employee or guest used a barcode scanner or other scanning device to enter the identifier string.

  • SWIPED - A restaurant employee or guest used a magnetic card strip reader to enter the identifier string.

  • UNKNOWN - The Toast platform received the identifier string using a method other than KEYED, SCANNED, or SWIPED, or the method is not known.

redeemedValue: number (double)

The currency amount of the funds being redeemed from the gift card.

checkIdentifier: string

The unique identifier of the check that this gift card transaction is part of. No action needs to be taken based on this identifier, it is just provided for tracking purposes.

isCashOut: boolean

True if this redeem transaction is a cash out transaction, false otherwise

TransactionInformationReverse: object

Information about a gift card transaction in the Toast
platform that undoes a previous transaction. Gift card providers are expected to handle the transaction. The only types of transactions that can be reversed are GIFTCARD_ADD_VALUE, GIFTCARD_REDEEM, and GIFTCARD_ACTIVATE. If a GIFTCARD_ADD_VALUE is reversed then the amount of the original transaction should be deducted from the card's balance. If a GIFTCARD_REDEEM is reversed then the amount of the original transaction should be added to the card's balance. If a GIFTCARD_ACTIVATE is reversed then the card should be set to inactive and its balance set to 0.00. GIFTCARD_GET_BALANCE and GIFTCARD_REVERSE cannot be reversed.

giftCardIdentifier: string

The unique identifier of the gift card.

identifierSource: string , x ∈ { KEYED , SCANNED , SWIPED , UNKNOWN }

Indicates how the Toast platform received the gift card identifier string. Values are:

  • KEYED - A restaurant employee or guest manually entered the identifier string.

  • SCANNED - A restaurant employee or guest used a barcode scanner or other scanning device to enter the identifier string.

  • SWIPED - A restaurant employee or guest used a magnetic card strip reader to enter the identifier string.

  • UNKNOWN - The Toast platform received the identifier string using a method other than KEYED, SCANNED, or SWIPED, or the method is not known.

previousTransaction: string (guid)

The identifier of an earlier gift card transaction. This identifier is provided in the Toast-Transaction-GUID header parameter.

checkIdentifier: string

The unique identifier of the check that this gift card transaction is part of. No action needs to be taken based on this identifier, it is just provided for tracking purposes.

TransactionResponseActivate: object

Information about a gift card transaction from the gift card service provider for activating a new gift card. The Toast POS system uses this information to complete guests' gift card transactions.

currentBalance: number (double)

The currency amount of the funds available from the gift card.

TransactionResponseAddValue: object

Information about a gift card transaction from the gift card service provider for add value transactions. The Toast platform uses this information to complete guests' gift card transactions.

currentBalance: number (double)

The currency amount of the funds available from the gift card.

TransactionResponseGetBalance: object

Information about a gift card transaction from the gift card service provider for get balance transactions. The Toast POS system uses this information to complete guests' gift card transactions.

currentBalance: number (double)

The currency amount of the funds available from the gift card.

TransactionResponseRedeem: object

Information about a gift card transaction from the gift card service provider that reduces the balance of funds available from the card. For example, when the gift card is used for a purchase. The Toast platform uses this information to complete guests' gift card transactions.

currentBalance: number (double)

The currency amount of the funds available from the gift card.

redeemedValue: number (double)

The currency amount of the funds that were redeemed from the gift card. This value may be different than the redeemedValue in a gift card transaction request. For example, if the card balance is less than the redeem value requested by the Toast platform, the redeemedValue in the response will be less than the `redeemedValue in the request.

TransactionResponseReverse: object

Information about a gift card transaction from the gift card service provider that undoes a previous gift card transaction. The Toast platform uses this information to complete guests' gift card transactions.

currentBalance: number (double)

The currency amount of the funds available from the gift card.