Review and implement the instructions in How to build a Toast integration.

Your 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 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 that involve multiple transactions.

If your integration will support physical gift cards, you must select a card vendor.

When restaurants purchase new physical cards, they should import the card numbers into your platform so that you recognize those card numbers when you receive gift card transactions from them.

For more information, see Physical gift card requirements.

When you receive a GIFTCARD_GET_BALANCE request, you should return the balance of this card and a 200 HTTP response status code.

Review all gift card transaction types and determine which of the following transaction types you will support:

Toast support recommends that you support all of these transaction types. For each transaction type that you support, develop successful responses that contain a 200 HTTP response status code and a transactionStatus of ACCEPT.

For transaction types that you do not support, your endpoint must return a 400 HTTP response status code and a transactionStatus of ERROR_TOAST_TRANSACTION_TYPE_NOT_SUPPORTED.

The following transactions can be reversed through a GIFTCARD_REVERSE request:

When you receive a GIFTCARD_REVERSE request, you must reverse the transaction whose Toast-Transaction-GUID is in the previousTransaction value.

Ensure that your endpoint is idempotent using the Toast-Transaction-GUID header on the transactions you receive.

If two requests contain the same Toast-Transaction-GUID, they are the same request.

Ensure 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 app that instructs them to contact your support team.

Some 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 is true, your reports should reflect that the guest received the gift card balance in cash.

If you plan to support verification codes (PINs) with your Toast integration, validate you send the proper responses based on your expectations for transactions that require a verification code. As an example, you may enforce that all keyed/manually typed gift cards have verification codes. If identifierSource is KEYED and verificationCode is NULL, you would return ERROR_VERIFICATION_REQUIRED.

Your 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 a transactionStatus of ERROR_INVALID_RESTAURANT.

Your 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 of ERROR_INVALID_TOKEN.

If you receive a gift card transaction whose giftCardIdentifier you do not recognize, your endpoint must return a 400 HTTP response status code and a transactionStatus of ERROR_CARD_INVALID.

If you receive a GIFTCARD_ACTIVATE transaction for a card that is already active, your endpoint must return a 400 HTTP response status code and a transactionStatus of ERROR_CARD_ALREADY_ACTIVATED.

If 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:

See Response status types for more information.

If your system has an unexpected error, your endpoint must return a 500 HTTP response status code.

Use the gift card integration test plan to validate that you correctly handle each test case.

To 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.

Contact 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.

Set 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 Toast Central article to distribute to customers to help them understand the integration onboarding process.

After you build your core gift card functionality, create reports that restaurants can use to understand gift card cash flow.

Here are some ideas for information to report on over time: