Building a gift card integration

Follow the steps below to build a gift card integration with the Toast platform.

  1. Setup

    Complete initial integration setup 

    Review and implement the instructions on the Getting Started section.

    Submit endpoint to Toast 

    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 initial information 

    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 involving multiple transactions.

    Perform an initial test 

    Then 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 vendor 

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

  2. Success responses

    Support balance inquiries 

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

    Develop success workflow 

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

    Develop reversal workflow 

    The 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 whose Toast-Transaction-GUID is in the previousTransaction value.

    Validate endpoint idempotence 

    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.

    Validate that you send timely responses 

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

    Handle cash-out transactions 

    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 this gift card balance in cash.

  3. Failure responses

    Handle unknown restaurants 

    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.

    Handle invalid authentication tokens 

    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.

    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 numbers 

    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.

    Handle duplicate card activation attempts 

    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.

    Handle unexpected information from Toast 

    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:

    • 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 system 

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

  4. Test your integration

    Run through the test plan 

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

    Load-test your endpoint 

    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.

    Review functionality with Toast team 

    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.

    Plan for onboarding 

    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 page for distribution to customers to help them understand the integration onboard process.

  5. Reporting

    Build gift card reports 

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