API: POST Receipt Data

Description

Send receipt details which includes payment details, items details, and location information to a RESTful API. If you are unable to provide a value for a field that is not required, do not send in that field. Do not send in a NULL or blank value.

URL

POST api.banyan.com/v1/receipt

Authentication

This as a restricted resource that requires an authentication token. See the API Authentication guide for details.

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" \
  "https://api.banyan.com/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	Alphabetic currency code associated with the value in ISO 4217 format.	string	Optional	Default is USD
consumer_token	A hashed token that is unique to the household or consumer	string	Optional
order_type	Location of where the transaction took place	string	Optional	Valid values include {web, in_store, phone, third_party_delivery}
merchant_total_amount	The full amount on the receipt	string	Optional	Includes cash back for debit transactions
barcode_url	The URL to the image of a receipt barcode	string	Optional
merchant_mid	The merchant id provided by the acquiring bank	string	Optional
fulfillment_type	How the items are received by the customer	string	Optional	Valid values include {in_store, shipped, delivered, pick_up}
image_url	The URL to the image of the receipt	string	Optional
custom_field	A customizable key value pair field used for passing data on to an enriched transaction	string	Optional

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	Optional
scheme	If debit or credit, what network is the card on	string	Optional	Valid values include Mastercard, Visa, Discover and American Express. Please format it as {'AX', 'DS', 'MC', 'OR', 'PP', 'VI'} where OR is "other" and 'PP' is Paypal
card_last_four	The last four digits on a debit or credit card	string	Optional
total_amount	The total amount per payment per receipt	string	Required
tip_amount	The total amount of tip on the payment	string	Optional
tax_amount	The total amount of tax on the payment	string	Optional
subtotal_amount	The total amount of the items without discounts, taxes, tip, shipping	string	Optional
shipping_amount	The amount of shipping cost on the payment	string	Optional
cash_back_amount	The amount received from debit/EBT card as cash from teller	string	Optional
other_positive_amounts	Any additional amounts included in the total amount that are not specified	array of strings	Optional
other_negative_amounts	Any negative amounts included in the total amount that are not specified	array of strings	Optional
authorization_code	Six digit alphanumeric code passed between banks that signal a transaction is possible	string	Optional
arn	A unique number that tags a credit or debit card transaction when it goes from the merchant’s bank through to the cardholder's bank.	string	Optional	only available on credit card transactions from visa and mastercard
is_virtual	Whether the card sent is a virtual card/wallet or a standard credit card	boolean	Optional	only available for credit/debit transactions
payment_account_reference	Payment Account Reference (PAR) is generated by the networks as a stable ID across tokens and PANs	string	Optional

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
merchant_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	Optional
amount_paid	Quantity multiplied by Discount Price Per Unit	string	Required	If an item is returned, this should be a negative number
quantity	number of items	string	Optional	If an item is returned, this should be a negative number
full_price_per_unit	The list price of the item before discounts	string	Optional
discount_price_per_unit	The amount paid for the item, can be less than the full price	string	Optional
tag	Custom field used to add further descriptions of items	array of strings	Optional	e.g., category:\|:beauty

Merchant Object

Element	Description	Type	Required	Notes
merchant	Elements pertaining to the location of the purchase	top level object	Optional
name	The internal name of the store	string	Optional	E.g., ABC Store #23
display_name	Deprecated	string	Deprecated	Deprecated

Location Object

Element	Description	Type	Required
location	Elements pertaining to the address of the store where the purchase took place	top level object	Optional
name	The legal / listed name of the store of the purchase	string	Optional
display_name	The banner name of the store of the purchase	string	Optional

Location.Address Object

Element	Description	Type	Required	Notes
address_line_one	Street address of the store	string	Optional
address_line_two	Additional address information	string	Optional
city	City of the store	string	Optional
state	State of the store	string	Optional
country	Country of the store	string	Optional	ISO 3066-1, Alpha 2 format preferred
postal_code	Postal code of the store	string	Optional	Needs to be 5 characters in length

Sample Request

For the most up to date sample request, please see the API Reference

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

{
  "merchant_receipt_id": "c2143ffb-63c4-442c-b152-816bdc3ca7dc",
  "purchase_ts": "2023-02-10T14:54:57.603Z",
  "merchant": {
    "name": "Rachel Bedding Test",
    "display_name": "Rachel Bedding Test"
  },
  "location": {
    "name": "RachelBeddingTest",
    "display_name": "RachelBeddingTest",
    "phone_number": "439-571-0756",
    "address": {
      "address_line_one": "32949 Plains bury",
      "city": "Lockmantown",
      "state": "Louisiana",
      "country": "USA",
      "postal_code": "85726"
    }
  },
  "order_type": "in_store",
  "fullfilment_type":"in_store",
  "currency": "usd",
  "merchant_total_amount": "25",
  "payments": [
    {
      "total_amount": "25",
      "payment_type": "credit",
      "scheme": "Elo",
      "bin": "638413",
      "card_last_four": "6664",
      "auth_code": "407200",
      "arn": "523763351",
      "subtotal_amount": "23",
      "tax_amount": "2",
      "tip_amount": "0",
      "cash_back_amount": "0",
      "payment_account_reference":"12345678912345678912345678912"
    }
  ],
  "items": [
    {
      "merchant_item_id": "123",
      "upc": "22222222222222",
      "brand": "BrandD",
      "description": "Sheet Detergent",
      "amount_paid": "25",
      "full_price_per_unit": "25",
      "discount_price_per_unit": "25",
      "quantity": "1",
      "tags": [
                "category_description:|:Bedding",
                "brand:|:BrandD",
                "subclass_desc:|:Detergent"
            ]
    }
  ],
  "merchant_consumer_token": "222222222222",
  "image_url": "https://nielsen.com/receipt/image/898577492124",
  "barcode_url": "https://nielsen.com/receipt/barcode/898577492124"
}

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. Errors can also be seen in the API Reference

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