Follow the steps below to build a gift card integration with the Toast platform.
-
Setup
Complete initial integration setupReview and implement the instructions on the Getting Started section.
Submit endpoint to ToastYour gift card integration requires a single endpoint. Submit your test environment endpoint to Toast support so they can set up the endpoint in the sandbox environment.
Review initial informationReview the gift card integration overview to understand the flow of information in a gift card integration. In addition, familiarize yourself with physical card requirements and workflows involving multiple transactions.
Perform an initial testThen use the integration verification tool to send a Get Balance request to your endpoint. Review the structure, format, and headers of this request to familiarize yourself with gift card requests in Toast.
Decide card vendorIf your integration will support physical gift cards, you must select a card vendor. When restaurants purchase new physical cards, they should import these cards' numbers into your platform so that you recognize their card numbers when you receive gift card transactions from them. For more information about physical card requirements, see Physical gift card requirements.
-
Success responses
Support balance inquiriesWhen you receive a GIFTCARD_GET_BALANCE request, you should return the balance of this card and a 200 HTTP response status code.
Develop success workflowReview all gift card transaction types and determine which of the following transaction types you will support:
-
GIFTCARD_ACTIVATE
-
GIFTCARD_ADD_VALUE
-
GIFTCARD_REDEEM
Toast support recommends supporting all three of the transaction types above. For each transaction type that you support, develop successful responses that contain a 200 HTTP response status code and a
transactionStatus
ofACCEPT
.For transaction types that you do not support, your endpoint must return a 400 HTTP response status code and a
transactionStatus
ofERROR_TOAST_TRANSACTION_TYPE_NOT_SUPPORTED
.Develop reversal workflowThe following transactions can be reversed through a
GIFTCARD_REVERSE
request:-
GIFTCARD_ACTIVATE
-
GIFTCARD_ADD_VALUE
-
GIFTCARD_REDEEM
When you receive a
GIFTCARD_REVERSE
request, you must reverse the transaction whoseToast-Transaction-GUID
is in thepreviousTransaction
value.Validate endpoint idempotenceEnsure that your endpoint is idempotent using the
Toast-Transaction-GUID
header on the transactions you receive. If two requests contain the sameToast-Transaction-GUID
, they are the same request.Validate that you send timely responsesEnsure that your endpoint adheres to Toast gift card latency requirements. This allows the Toast platform to correctly understand how you processed the transaction in your system.
If your endpoint does not adhere to timeout requirements, guests will see an error message on the POS that instructs them to contact your support team.
Handle cash-out transactionsSome restaurant locations are subject to regulations that require that guests be allowed to redeem gift card balances in cash. If the
isCashOut
value on a gift card transaction istrue
, your reports should reflect that the guest received this gift card balance in cash. -
-
Failure responses
Handle unknown restaurantsYour system must maintain an allowlist of restaurant GUIDs that your integration recognizes.
If the
Toast-Restaurant-External-ID
header in a gift card transaction contains a restaurant GUID that is not on your allowlist, your endpoint must return a 400 HTTP response status code and atransactionStatus
ofERROR_INVALID_RESTAURANT
.Handle invalid authentication tokensYour endpoint must validate that gift card transactions came from the Toast production environment.
If your gift card authentication process determined that a transaction came from somewhere other than the Toast production environment, your endpoint must return a 400 HTTP response status code and a
transactionStatus
ofERROR_INVALID_TOKEN
.Use the integration verification tool to test authentication against your production endpoint, because this tool submits requests out of the Toast sandbox environment.
Handle unknown card numbersIf you receive a gift card transaction whose
giftCardIdentifier
you do not recognize, your endpoint must return a 400 HTTP response status code and atransactionStatus
ofERROR_CARD_INVALID
.Handle duplicate card activation attemptsIf you receive a
GIFTCARD_ACTIVATE
transaction for a card that is already active, your endpoint must return a 400 HTTP response status code and atransactionStatus
ofERROR_CARD_ALREADY_ACTIVATED
.Handle unexpected information from ToastIf you receive unexpected information from the Toast platform, your endpoint must return a 400 HTTP response status code and one of the following values for
transactionStatus
, depending on the information you receive:-
ERROR_INVALID_TOAST_TRANSACTION_TYPE
-
ERROR_INVALID_INPUT_PROPERTIES
-
ERROR_TRANSACTION_DOES_NOT_EXIST
-
ERROR_TRANSACTION_CANNOT_BE_REVERSED
See Response status types for more information.
Handle unexpected errors in your systemIf your system has an unexpected error, your endpoint must return a 500 HTTP response status code.
-
-
Test your integration
Run through the test planUse the gift card integration test plan to validate that you correctly handle each test case.
Load-test your endpointTo ensure that your endpoint can handle a high volume of gift card transactions at a time, add 10+ gift cards to a POS order to ensure that your endpoint can handle this volume. Consider any additional load-test workflows you should validate before going live.
Review functionality with Toast teamContact the Toast support team about walking through the test plan together. After the Toast team confirms that your integration is ready to go live, send your production endpoint to the Toast support team.
Plan for onboardingSet up the allowlist of restaurant GUIDs you support and prepare a sample email for requesting new integration connections. The Toast support team will supply you with a guide for integration enablement. Bookmark this page for distribution to customers to help them understand the integration onboard process.
-
Reporting
Build gift card reportsAfter you build your core gift card functionality, create reports that restaurants can use to understand gift card cash flow. Below are ideas for information to report on over time:
-
Sales
-
Number of gift cards sold
-
Currency value of gift cards sold
-
Average value of gift card sold
-
-
Redemptions
-
Number of gift cards fully redeemed
-
Currency value of gift card redemptions
-
-
Balances
-
Average balance on active cards
-
-
Escheatment
-
Number of gift cards that expired
-
Average value of expired gift cards
-
-
Cash-outs
-
Total currency value of cash-out transactions
-
Average currency value of cash-out transactions
-
-
Congratulations on building a gift card integration, allowing customers to use your gift card functionality in their Toast POS workflows.