API: POST Receipt Data
Description
Send receipt details which includes payment details, items details, and location information to a RESTful API.
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; the follow examples use the shell variables defined there.
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}" \
"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 | 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 | |
order_type | Location of where the transaction took place | string | Optional | Valid values include {web, in_store, phone, third_party_delivery} |
merchant_total_payment | The full amount on the receipt | numeric | Optional | Includes cash back for debit transactions |
barcode_url | The URL to the image of a receipt barcode | 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 |
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_mid | The merchant id provided by the acquiring bank | string | Optional | |
total_amount | The total amount per payment per receipt | numeric | Required | |
tip_amount | The total amount of tip on the payment | numeric | Optional | |
tax_amount | The total amount of tax on the payment | numeric | Required | |
subtotal_amount | The total amount of the items without discounts, taxes, tip, shipping | numeric | Optional | |
shipping_amount | The amount of shipping cost on the payment | numeric | Optional | |
cash_back_amount | The amount received from debit/EBT card as cash from teller | numeric | Optional | |
other_positive_amounts | Any additional amounts included in the total amount that are not specified | array of numerics | Optional | |
other_negative_amounts | Any negative amounts included in the total amount that are not specified | array of numerics | 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 | numeric | 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 |
Updated 5 days ago