Banyan Receipt API

Introduction

This document describes how fintechs can make a request to our endpoint to get back enriched data for your receipt.

The flow to make a request and a response is as follows: you make a POST request to our endpoint and at a later time we will send a POST request back to your specified address.

Due to the nature of our data, we send back the data as a webhook event. Some merchants send us the information as the transaction is happening, others send it in batches once a day. This means that if we don't find the data for your receipt immediately, we will keep your request on our side until the data appears.

This also means that you have to send us a unique ID in each request so you can track if you got back the response (we will include this ID in the payload sent back to you).

Modes

Mode

Endpoint

Description

Development

https://output.api.development.getbanyan.com/receipt

Use the Development API to send test data to Banyan with your API keys. Banyan will send back sample data to the development endpoint you will have provided to your Banyan representative.

Production

https://output.api.getbanyan.com/receipt

Use the Production API to send live data to Banyan with your API keys. Banyan will send back live data to the production endpoint you will have provided to your Banyan representative.

Webhook

To receive webhook events about the result of your query, you have to get in touch with us and provide the following:

  • Your URL endpoint.
  • The API Key that you want us to use when sending back data.

We are going to pass the API Key in the header under the value of x-api-key when sending back data.

Endpoint URL

  • Production: https://output.api.getbanyan.com/receipt
  • Development: https://output.api.development.getbanyan.com/receipt

Payload

Both customerToken and uniqueIdentifier keys are mandatory, but their definitions are left open-ended so they can be used to track your request. The Banyan system is asynchronous, meaning a reply will be sent back to you whenever it is found, perhaps even a day later. We give you this two fields to make it easy for you to match the response with the original request. The customerToken key identifies the customer and uniqueIdentifier identifies the transaction.

customerToken

This field indicates the customer's ID as defined in the client system, and can be used to match a response from Banyan to their data.

uniqueIdentifier

This field indicates the ID of the transaction as defined in the client system. It can be used to find the specific transaction a Banyan response refers to once the customer is identified. When you make a request, make sure to store the value in a DB of your choosing to be able to match our response.

Example Payloads

Example 1 - Internal

{
    "customerToken": "007",
    "uniqueIdentifier": "0x00000001",
    "receipt": {
        "storeId": "1234",
        "merchantName": "walmart",
        "datetime": "2020-12-30T00:00:00.000Z",
        "cardType": "visa",
        "last4": "1234",
        "totalAmount": 12.24
    }
}

Example 2 - Address conversion

{
    "customerToken": "007",
    "uniqueIdentifier": "0x00000002",
    "receipt": {
        "merchantName": "walmart",
        "datetime": "2020-05-08T15:30:37.000Z",
        "cardType": "debit",
        "last4": "9631",
        "totalAmount": 6.76,
        "address": {
            "country": "us",
            "state": "fl",
            "city": "sebring",
            "postalCode": "33870",
            "addressLineOne": "3525 US HIGHWAY 27 N",
            "addressLineTwo": ""
        }
    }
}

Example Response

{
    "customerToken": "007",
    "uniqueIdentifier": "0x00000002",
    "receipt": {
        "store": {
            "displayName": "Neptune Supercenter",
            "phoneNumber": "732-922-8084",
            "address": {
                "addressLineOne": "3575 STATE ROUTE 66",
                "addressLineTwo": "",
                "country": "us",
                "state": "cs",
                "city": "neptune",
                "postalCode": "07753"
            }
        },
        "transaction": {
            "transactionID": "27804549671483058136",
            "datetime": "2020-05-08T15:30:37.000Z",
            "cardType": "debit",
            "last4": "0000",
            "subtotal": 6.76,
            "taxAmount": 0,
            "changeDue": 0,
            "items": [
                {
                    "itemId": "0576407142",
                    "quantity": 1,
                    "price": 3.97,
                    "description": "Equate Moisturizing Hand Sanitizer with Vitamin E, 34 fl oz - May Ship with a Flip Top Cap",
                    "upc": "068113124766"
                },
                {
                    "itemId": "0578188885",
                    "quantity": 1,
                    "price": 3.38,
                    "description": "LaCroix LimonCello Sparkling Water - 8pk/12 fl oz Cans, 8 / Pack (Quantity)",
                    "upc": "001299322111"
                }
            ]
        }
    }
}

Error Handling

If the receipt is not in our database and we cannot find it externally, we will send a message saying so.

{
    "customerToken": "0x07",
    "uniqueIdentifier": "0x00000002",
    "error": {
        "message": "Receipt not found",
        "code": 404
    }
}

Retry Mechanism

If we are unable to send data to the webhook endpoint for any reason, we will continue to try and hit the endpoint every minute for fifteen minutes before dropping the message.


Did this page help you?