arrow-left Back to Announcements
DATE:
AUTHOR:
The Toast - API team
Loyalty API Objects, fields, and values

Loyalty account identifier on reversal can be null

DATE:
AUTHOR: The Toast - API team

The Toast loyalty API will change the behavior of the loyaltyIdentifier value in the TransactionInformationReverse object for reversal transaction requests on 2022-03-14. The loyaltyIdentifier value for a reversal transaction will always match the loyaltyIdentifier of the transaction that is being reversed.

By 2022-03-14, your loyalty API integration must handle a null loyaltyIdentifier for a LOYALTY_REVERSE transaction. If you receive a LOYALTY_REVERSE transaction with a null loyaltyIdentifier, your integration must return an HTTP 200 response code and the transactionStatus ACCEPT if the transaction is structured correctly.

The reversal transaction account identifier will match the account identifier of the original transaction:

  • When the loyalty account identifier of the original transaction is null.

    In this situation, the loyalty account identifier of the reversal transaction will be null. This is a change from current API behavior.

  • When the loyalty account identifier value of the original transaction includes the account identifier string.

    In this situation, the loyalty account identifier of the reversal transaction will also include the identifier value.

Currently, the Toast loyalty API sends a non-null loyaltyIdentifier value for some reversal transactions that apply to a transaction that contained a null loyaltyIdentifier value.

The following procedure describes one situation that can result in a non-null loyaltyIdentifier value in a reversal transaction for a transaction that included a null loyaltyIdentifier value.

  1. A restaurant guest does not provide loyalty account information when paying for a check. The Toast loyalty API sends your loyalty service an accrual transaction request. The loyaltyIdentifier value in the TransactionInformationCheck object is null. The Toast loyalty API sends an accrual request transaction for all check payments, even when the guest has not presented loyalty account information.

    When your service receives a transaction request with no loyalty account identifier, your integration might discard the transaction information. The action your service takes with this request depends on the design of your integration.

  2. After completing the payment transaction, the guest presents loyalty account information and wants to apply the check payment to the loyalty program.

  3. The Toast loyalty API sends your service a reversal transaction for the check payment. The transaction identifier of the reversal request matches the transaction identifier of the accrual request.

    Currently, the Toast loyalty API includes the loyalty account identifier that the guest provided in the loyaltyIdentifier value of the TransactionInformationReverse object for the reversal request. This behavior will change on 2022-03-14 and the loyaltyIdentifier on this transaction will be null.

  4. If your loyalty program service did not store the original transaction (which did not include a loyalty program account identifier), the correct method for handling the reversal request for that transaction might not be clear. The way that your service handles this situation depends on the design of your integration.

On 2022-03-14, the Toast loyalty API will include a null loyaltyIdentifier value for the reversal request described in Step 3.

By 2022-03-14, your loyalty API integration must handle a null loyaltyIdentifier for a LOYALTY_REVERSE transaction. If the you receive a LOYALTY_REVERSE transaction with a null loyaltyIdentifier, your integration must return an HTTP 200 response code and the transactionStatus ACCEPT if the transaction is structured correctly.

Powered by LaunchNotes