Returns gift card transaction information

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.

Request
header Parameters
Authorization
string

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.

Toast-Restaurant-External-ID
string

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

Toast-Transaction-GUID
string

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

Toast-Transaction-Type
string

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

  • GIFTCARD_ACTIVATE
  • GIFTCARD_ADD_VALUE
  • GIFTCARD_GET_BALANCE
  • GIFTCARD_REDEEM
  • GIFTCARD_REVERSE
Enum: "GIFTCARD_ACTIVATE" "GIFTCARD_ADD_VALUE" "GIFTCARD_GET_BALANCE" "GIFTCARD_REDEEM" "GIFTCARD_REVERSE"
Request Body schema: application/json

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

object (TransactionInformationActivate)

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

object (TransactionInformationAddValue)

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.

object (TransactionInformationGetBalance)

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.

object (TransactionInformationRedeem)

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.

object (TransactionInformationReverse)

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.

Responses
200

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

400

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
  • ERROR_VERIFICATION_FAILED
  • ERROR_VERIFICATION_REQUIRED
  • ERROR_VERIFICATION_NOT_SUPPORTED
500

Internal server error.

post/yourendpointname
Request samples
application/json
{
  • "activateTransactionInformation": {
    },
  • "addValueTransactionInformation": {
    },
  • "getBalanceTransactionInformation": {
    },
  • "redeemTransactionInformation": {
    },
  • "reverseTransactionInformation": {
    }
}
Response samples
application/json
{
  • "transactionStatus": "ACCEPT",
  • "activateResponse": {
    },
  • "addValueResponse": {
    },
  • "getBalanceResponse": {
    },
  • "redeemResponse": {
    },
  • "reverseResponse": {
    }
}