API Submission of Transaction Data

Description

Send transaction details which includes payment details, merchant details, and location information to a RESTful API.

URL

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

Headers

Header Name

Description

Required

Values

Bearer

Access Token

Required

See Authorization section

Content-Type

The transaction format to send

Optional

application/JSON

Accept

The response format sent back

Optional

application/JSON

POST Body

Top Level Objects

Element

Description

Type

Required

Notes

transaction_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 transaction amount

string

Optional

Default is USD

consumer_token

A hashed token that is unique to the household or consumer

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

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

total amount

The total amount of the transaction

decimal

Required

cash_back

The amount of cash back requested with a debit purchase

decimal

Optional

Only relevant for debit transactions

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

Merchant Object

Element

Description

Type

Required

Notes

merchant

Elements pertaining to the location of the purchase

top level object

Required

name

The internal name of the store

string

Optional

E.g., ABC Store #23

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/transaction
Bearer: {token_id}
Content-Type: application/json
Accept: application/json

{
   "transaction": {
      "transaction_id": "928010812908",
      "purchase_ts": "2021-09-03T11:48:02.745487434Z",
      "currency": "USD",
      "consumer_token": "d448d0aa-4383-40ff-a222-4bca8d7d53d7",
      "merchant": {
         "name": "Pickles US inc",        
         "merchant_id": "899444"
      },
      "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",
      "payment":  {
            "payment_type": "credit",
            "scheme": "Mastercard",
            "card_last_four": "9287",
            "total_amount": 20.98,
            "authorization_code": "392082",
            "arn": "198018429390"
      }       
   }
}

Response

Element

Description

Type

Notes

byn_transaction_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_transaction_id": "c35fd152-454a-5281-a1f2-bc8426b68461"
        }
    ],
    "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

401

Not Found

Not authorized to view data

500

Internal Server Error


Did this page help you?