API Submission of Receipt Data

Description

Send receipt details which includes payment details, items details, and location information to a RESTful API.

URL

POST https://api.banyan.com/v1/receipt

Authentication and Authorization

Contact your Banyan representative to obtain an API key and Access ID to be used on the authorization end point. Once you have your key and ID, you will use the following curl call to obtain your token. Tokens expire every 30 minutes. Using a retired token will result in a 404 error response.

TOKEN=$(curl -s -X POST \
    -H 'Content-Type: application/json' \
    --data "{\"access_id\":\"$ACCESS_ID\",\"api_key\":\"$API_KEY\"}" \
    ${GATEWAY_URL}/token | jq -r .data[0])

Headers

As we said above, you will use the token you receive in your header call to the POST Receipt endpoint.

Header Name

Description

Required

Values

Authorization: Bearer

Access Token

Required

See Authorization section

Content-Type

The receipt format to send

Optional

application/JSON

Accept

The response format sent back

Optional

application/JSON

Example:

curl -v -s -X GET \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKey: ${API_KEY}" \
  "${GATEWAY_URL}/rest/v1/version"

POST Body

Top Level Objects

Element

Description

Type

Required

Notes

merchant_receipt_id

Unique to the transaction

string

Required

purchase_ts

When the purchase occurred

RFC3339

Required

Timestamp is in UTC, example: 2021-01-28T14:43:50.52Z

currency

Currency of the receipt amount

string

Optional

Default is USD

merchant_consumer_token

A hashed token that is unique to the household or consumer

string

Optional

location_type

Referencing whether the purchase happened in store or via web

string

Optional

merchant_total_payment

The full amount on the receipt

decimal

Optional

Includes cash back for debit transactions

Payment Object
Each payment used on the receipt is a different object in the array

Element

Description

Type

Required

Notes

payments

An array of payments

Top Level Object

Required

payment_type

Whether the payment was in cash, gift card, debit or credit

string

Required

payment_scheme

If debit or credit, what network is the card on

string

Optional

Valid values include Mastercard, Visa, Discover and American Express

card_last_four

The last four digits on a debit or credit card

string

Optional

merchant_id

The merchant id

total_amount

The total amount per payment per receipt

decimal

Required

tip_amount

The total amount of tip on the payment

decimal

Optional

tax_amount

The total amount of tax on the payment

decimal

Required

subtotal_amount

The total amount of the items without discounts, taxes, tip, shipping

decimal

Optional

cash_back

The amount of cash back requested with a debit purchase

decimal

Optional

shipping_amount

The amount of shipping cost on the payment

decimal

Optional

other_positive_amounts

Any additional amounts included in the total amount that are not specified

array of decimals

Optional

other_negative_amounts

Any negative amounts included in the total amount that are not specified

array of decimals

Optional

authorization_code

Six digit alphanumeric code passed between banks that signal a transaction is possible

string

Optional

arn

A unique 16-digit number that tags a credit or debit card transaction when it goes from the merchant’s bank through to the cardholder's bank.

string

only available on credit card transactions from visa and mastercard

Item Object
Each item on the receipt is its own object in the array

Element

Description

Type

Required

Notes

item

An array of items

top level object

Required

item_id

Unique id represented on the receipt

string

Optional

This number will help with QA efforts to know that Banyan has the complete receipt information

upc

Universal product code

string

Optional

sku

Unique id to the merchant

string

Optional

image_url

Url of an image of the item

string

Optional

brand

Brand of the item

string

Optional

description

Item description

string

Required

price

The amount paid for the item including discounts

decimal

Required

unit_price

list_price

The list price of the item before discounts

Merchant Object

Element

Description

Type

Required

Notes

merchant

Elements pertaining to the location of the purchase

top level object

Required

merchant_store_id

The number of the store of the purchase

string

Optional

name

The internal name of the store

string

Optional

E.g., ABC Store #23

display_name

The external name of the store

string

Required

E.g.,ABC Store

phone_number

The phone number of the store

string

Optional

merchant_id

A unique ID for each merchant POS, assigned by merchant bank

string

Optional

Location Object

Element

Description

Type

Required

Notes

location

Elements pertaining to the address of the store where the purchase took place

top level object

Required

address_line_one

Street address of the store

string

address_line_two

Additional address information

string

Such as a lot number

city

City of the store

string

state

State of the store

string

country

Country of the store

string

ISO 3066-1, Alpha 2 format preferred

postal_code

Postal code of the store

string

Sample Request

POST http://api.banyan.com/v1/receipt
Bearer: {token_id}
Content-Type: application/json
Accept: application/json

{
   "receipt": {
      "merchant_receipt_id": "928010812908",
      "purchase_ts": "2021-09-03T11:48:02.745487434Z",
      "currency": "USD",
      "merchant_consumer_token": "d448d0aa-4383-40ff-a222-4bca8d7d53d7",
      "merchant": {
         "merchant_store_id": "983018",
         "name": "Pickles US inc",
         "display_name": "Pickles US",
         "phone_number": "222-333-4444"
      },
      "location": {
         "address_line_one": "12 Main Street",
         "address_line_two": "Floor 2",
         "city": "Holmdel",
         "state": "NJ",
         "country": "US",
         "postal_code": 8382
      },
      "location_type": "In Store",
      "payments": [
         {
            "payment_type": "credit",
            "payment_scheme": "Mastercard",
            "card_last_four": "9287",
            "total_amount": 20.98,
            "tax_amount": 0.98,
            "subtotal_amount": 15,
            "shipping_amount": 5,
            "authorization_code": "392082",
            "arn": "198018429390"
         },
         {
            "payment_type": "credit",
            "payment_scheme": "VISA",
            "card_last_four": "9999",
            "total_amount": 20.98,
            "tax_amount": 0.98,
            "subtotal_amount": 15,
            "shipping_amount": 5,
            "authorization_code": "876987",
            "arn": "39272635437"
         }
      ],
      "items": [
         {
            "item_id": "82109801",
            "upc": "293802",
            "sku": "98098099",
            "image_url": "wwww.picklesus.com/pickles/variety-pack",
            "description": "Varitey Pack - 10",
            "price": "20.00",
            "discount_price": "10.00",
            "quantity": "2"
         },
         {
            "item_id": "82109802",
            "upc": "293992",
            "sku": "98098393",
            "image_url": "wwww.picklesus.com/kimchi/two-pack",
            "description": "Kimchi 2 Pack",
            "price": "10.00",
            "discount_price": "10.00",
            "quantity": "1"
         }
      ]
   }
}

Response

Element

Description

Type

Notes

byn_receipt_id

The ID of the receipt generated by Banyan

string

This is what to use when using the GET method on /receipt

Sample Response

{
    "data": [
        {
            "byn_receipt_id": "41863f4c-a5dc-53b6-9fcb-44e8b57c4af7"
        }
    ],
    "errors": []
}

Status Codes and Errors

The receipt will be validated upon delivery, and if there is an error, we will report it in our request response

Code

Description

Notes

200

Success

A record was written to the /receipt resource

400

Bad Request

This error code will come with a brief description of what needs to be changed such as a data type or unknown field name

404

Not Found

Not authorized to view data

500

Internal Server Error


Did this page help you?