API: POST 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 NameDescriptionRequiredValues
Authorization: BearerAccess TokenRequiredSee Authorization section
Content-TypeThe receipt format to sendOptionalapplication/JSON
AcceptThe response format sent backOptionalapplication/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

ElementDescriptionTypeRequiredNotes
merchant_receipt_idUnique to the transactionstringRequired
purchase_tsWhen the purchase occurredRFC3339RequiredTimestamp is in UTC, example: 2021-01-28T14:43:50.52Z
currencyCurrency of the receipt amountstringOptionalDefault is USD
merchant_consumer_tokenA hashed token that is unique to the household or consumerstringOptional
order_typeLocation of where the transaction took placestringOptionalValid values include {web, in_store, phone, third_party_delivery}
merchant_total_paymentThe full amount on the receiptnumericOptionalIncludes cash back for debit transactions
barcode_urlThe URL to the image of a receipt barcodestringOptional
fulfillment_typeHow the items are received by the customerstringOptionalValid values include {in_store, shipped, delivered, pick_up}
image_urlThe URL to the image of the receiptstringOptional

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

ElementDescriptionTypeRequiredNotes
paymentsAn array of paymentsTop Level ObjectRequired
payment_typeWhether the payment was in cash, gift card, debit or creditstringRequired
payment_schemeIf debit or credit, what network is the card onstringOptionalValid values include Mastercard, Visa, Discover and American Express
card_last_fourThe last four digits on a debit or credit cardstringOptional
merchant_midThe merchant id provided by the acquiring bankstringOptional
total_amountThe total amount per payment per receiptnumericRequired
tip_amountThe total amount of tip on the paymentnumericOptional
tax_amountThe total amount of tax on the paymentnumericRequired
subtotal_amountThe total amount of the items without discounts, taxes, tip, shippingnumericOptional
shipping_amountThe amount of shipping cost on the paymentnumericOptional
cash_back_amountThe amount received from debit/EBT card as cash from tellernumericOptional
other_positive_amountsAny additional amounts included in the total amount that are not specifiedarray of numericsOptional
other_negative_amountsAny negative amounts included in the total amount that are not specifiedarray of numericsOptional
authorization_codeSix digit alphanumeric code passed between banks that signal a transaction is possiblestringOptional
arnA 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.stringonly available on credit card transactions from visa and mastercard

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

ElementDescriptionTypeRequiredNotes
itemAn array of itemstop level objectRequired
item_idUnique id represented on the receiptstringOptionalThis number will help with QA efforts to know that Banyan has the complete receipt information
upcUniversal product codestringOptional
skuUnique id to the merchantstringOptional
image_urlUrl of an image of the itemstringOptional
brandBrand of the itemstringOptional
descriptionItem descriptionstringRequired
priceThe amount paid for the item including discountsnumericRequired
unit_price
list_priceThe list price of the item before discounts

Merchant Object

ElementDescriptionTypeRequiredNotes
merchantElements pertaining to the location of the purchasetop level objectRequired
merchant_store_idThe number of the store of the purchasestringOptional
nameThe internal name of the storestringOptionalE.g., ABC Store #23
display_nameThe external name of the storestringRequiredE.g.,ABC Store
phone_numberThe phone number of the storestringOptional
merchant_idA unique ID for each merchant POS, assigned by merchant bankstringOptional

Location Object

ElementDescriptionTypeRequiredNotes
locationElements pertaining to the address of the store where the purchase took placetop level objectRequired
address_line_oneStreet address of the storestring
address_line_twoAdditional address informationstringSuch as a lot number
cityCity of the storestring
stateState of the storestring
countryCountry of the storestringISO 3066-1, Alpha 2 format preferred
postal_codePostal code of the storestring

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

ElementDescriptionTypeNotes
byn_receipt_idThe ID of the receipt generated by BanyanstringThis 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

CodeDescriptionNotes
200SuccessA record was written to the /receipt resource
400Bad RequestThis error code will come with a brief description of what needs to be changed such as a data type or unknown field name
404Not FoundNot authorized to view data
500Internal Server Error