Testing your gift card API implementation

The reference implementation repository includes a set of test API requests in a Postman™ collection. You can use these test requests to simulate the API requests that the Toast platform sends to your integration. For more information, see Reference gift card API implementation.

Important

You can send real requests from the Toast platform using the sandbox testing environment. The Toast integrations team can configure a test restaurant that uses your implementation and a restaurant employee account that you can use to sign into a POS device to simulate gift card transactions. Your implementation must verify incoming JWTs with the sandbox public key when receiving requests from the sandbox environment. For more information about the public key, see Gift card integration authentication.

In addition, Toast offers an integration verification tool that you can use to test your API implementation. The following sections describe this tool.

About the integration verification tool

The integration verification tool is a single page application (SPA) that allows integration partners to test an API implementation.

The verification tool uses authentication tokens that are encrypted using the keys for the sandbox environment. When you configure your integration API implementation to authenticate requests using the production environment encryption keys, you will no longer be able to use this testing tool.

Verifying a gift card integration

To use the integration verification tool, you supply information in the fields at the top of the page.

A screenshot of the controls at the top of the validation tool page.

You provide the following information.

  • Your Integration Type. This selection determines the testing options shown later on the page.

  • Your sandbox Provider URL section.

  • A restaurant GUID recognized by your system in the Restaurant ID field.

The values needed for gift card API requests are a card identifier and an amount for the transaction. Under the Transaction Info heading are fields for card number and amount.

A screenshot of the Transaction Info controls.

To test a reverse request you must also supply a transaction GUID. You supply this information using options near the Send Reverse button further down on the page.

To test your gift card API implementation, the verification tool provides the following options.

  • Send Activate Request

    Sends a GIFTCARD_ACTIVATE request to the provider, using the inputs from the fields in the Transaction Info section. After a successful response, the new balance of the gift card displays below Send Activate.

  • Send Get Balance Request

    Sends a GIFTCARD_GET_BALANCE request using the card number provided in the Transaction Info section. After a successful response, the gift card balance displays below Send Get Balance.

  • Send Add Value Request

    Sends a GIFTCARD_GET_BALANCE request, followed by a GIFTCARD_ADD_VALUE request, to the provider. Both requests use the information provided in the Transaction Info section. If both requests give successful responses, the balance before transaction, balance after transaction, and transaction GUID display in a table below Send Add Value.

    Note

    If the GIFTCARD_GET_BALANCE request fails, an error message displays the error and the add value request is not sent. Add value requests with amounts less than 0.01 are not supported by the gift card API. This tool will not send a request with an invalid amount and will show an error message.

  • Send Redeem Request

    Sends a GIFTCARD_GET_BALANCE request, followed by a GIFTCARD_REDEEM request, to the provider. Both requests use the information provided in the Transaction Info section. If both requests result in successful responses, the balance before transaction, balance after transaction, and transaction GUID display in a table below Send Redeem.

    Note

    If the GIFTCARD_GET_BALANCE request fails, the error messaging will indicate that the get balance failed and not the redeem. Redemption requests with amounts less than 0.01 are not supported by the gift card API. This tool will not send a request with an invalid amount and will show an error message.

  • Send Reverse Request

    To use this testing option, you must either supply a transaction GUID or select a transaction type to send as a New Transaction.

    A screenshot of the controls for sending a reverse request.

    Sends a GIFTCARD_REVERSE request using either the ID in the Transaction GUID field or the specified New Transaction type. If you provide a transaction GUID, it is passed right to the request. If you do not provide a transaction GUID and instead specify a new transaction, the verification tool sends the selected transaction and then reverses it. If neither field is filled out, this tool does not send the request and an error message displays. If you supply both a transaction GUID and specify a new request type, the testing tool uses the transaction GUID.

  • Test All Requests

    Sends every command, validates each one, reverses the reversible commands, validates that they were reversed, redoes them, and validates that they were redone. These tests are run serially and stop when they encounter an error.

    For this request, the card that you supply must be inactive (in order to test the activate steps). If you supply an amount of 0 in the Transaction Info section, the activate requests use a value of 0 and the add value and redeem requests use a value of 1. The verification tool makes this adjustment automatically to assure that only supported amounts are sent. If all tests pass, all transactions are reversed and the card is returned to an inactive state.

    The test structures that this option initiates, send request and reverse request, are described below. Note that a test of GET_BALANCE is run implicitly by both structures.

    Send request (ACTIVATE, ADD_VALUE, REDEEM, REDO_ACTIVATE, REDO_ADD_VALUE, REDO_REDEEM)

    1. Send request.

    2. Send GET_BALANCE to get card current balance.

    3. Verify the current balance is the expected balance based on the amount given in the Transaction Info section.

    Reverse request (REVERSE_ACTIVATE, REVERSE_ADD_VALUE, REVERSE_REDEEM)

    1. Reverse the request completed in the send request test.

    2. Send GET_BALANCE to get card current balance.

    3. Verify the current balance is the expected balance based on the amount given in the Transaction Info section.

    The result of each test (pass, fail, or did not run) displays in a table below the Test All Requests button. If a test fails, an error message displays above the table.

Error handling

There are a number of error states that can occur for each request.

  • No response from provider.

  • No response from the Toast platform.

  • Valid error transaction status.

  • Invalid response format.

  • Invalid response transaction status (provider threw an undefined error).

If any of these error states occur for a request, an error message appears below that request's button.