API: POST Transaction Data

Description

Send transaction details which includes payment details, merchant 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.

For the most up to date version of our schema please see our API reference docs. This page goes in more depth to describe the fields we are able to receive.

URL

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

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. These keys can also be used within the API reference.

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

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	Data Type	Required	Notes
finx_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
finx_consumer_token	A hashed token that is unique to the household or consumer	string	Optional
description	The description of the transaction, with merchant details	string	Optional
authorization_ts	When authorization was requested to the issuer	RFC3339	Optional	If only authorization timestamp is available, use it in both purchase and auth ts fields
order_type	The mode by which the order was placed	string	Optional	Valid values: in_store, web, phone
custom_fields	A free field to tie attributes of the transaction that you want to share with Banyan	array of straings	Optional

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

Element	Description	Type	Required	Notes
payment	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
bin	Bank Identification Number associated with the card used	string	Optional	Some BINs will be 8 digits in the near future
total_amount	The total amount of the transaction	string	Required
auth_code	Six digit alphanumeric code passed between banks that signal a transaction is possible	string	Optional
arn	A unique 23-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
currency	Alphabetic currency code associated with the value in ISO 4217 format.	string	Optional	Default is USD
finx_mid	A unique ID for each merchant POS, assigned by merchant bank	string	Optional

Merchant Object: transaction.merchant

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

Location Object: transaction.location

Element	Description	Type	Required	Notes
location	Elements pertaining to the address of the store where the purchase took place as well as other details	top level object	Optional
name	The name of the location	string	Optional
display_name	Consumer facing name of the mechant	string	Optional	Often the same as merchant.display_name

Address Object: transaction.location.address

Element	Description	Type	Required	Notes
address	Elements pertaining to the address of the store where the purchase took place	top level object	Optional
address_line_one	Street address of the store	string	Optional
address_line_two	Additional address information	string	Optional	Such as a lot number
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	Must be 5 characters in length

Sample Request

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

{
   "transaction": {
      "finx_transaction_id": "928010812908",
      "purchase_ts": "2021-09-03T11:48:02.745487434Z",
      "finx_consumer_token": "d448d0aa-4383-40ff-a222-4bca8d7d53d7",
      "description": "Pickles US 0903",
      "merchant": {
         "name": "Pickles US inc",        
         "display_name": "Pickles US"
      },
      "location": {
         "name": "Pickles Holmdel",
         "merchant_store_id": "0903",
         "phone_number": "555-123-4567",
         "address": {
           "address_line_one": "12 Main Street",
         	 "address_line_two": "Floor 2",
           "city": "Holmdel",
           "state": "NJ",
           "country": "US",
           "postal_code": "08382"
         }
       },
      "order_type": "in_store",
     	"currency": "USD",
      "payment":  {
            "payment_type": "credit",
            "currency": "USD",
            "scheme": "MC",
            "card_last_four": "9287",
            "total_amount": 20.98,
            "authorization_code": "392082",
            "finx_mid": "39801801084001",
            "arn": "198018429390",
            "bin": "749280"
      }       
   }
}

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