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

POST Body

Top Level Objects

ElementDescriptionData TypeRequiredNotes
finx_transaction_idUnique to the transactionstringRequired
purchase_tsWhen the purchase occurredRFC3339RequiredTimestamp is in UTC, example: 2021-01-28T14:43:50.52Z
finx_consumer_tokenA hashed token that is unique to the household or consumerstringOptional
descriptionThe description of the transaction, with merchant detailsstringOptional
authorization_tsWhen authorization was requested to the issuerRFC3339OptionalIf only authorization timestamp is available, use it in both purchase and auth ts fields
order_typeThe mode by which the order was placedstringOptionalValid values: in_store, web, phone
custom_fieldsA free field to tie attributes of the transaction that you want to share with Banyanarray of straingsOptional

Payment Object: transaction.payment
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 creditstringOptional
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
binBank Identification Number associated with the card usedstringOptionalSome BINs will be 8 digits in the near future
total_amountThe total amount of the transactionstringRequired
auth_codeSix digit alphanumeric code passed between banks that signal a transaction is possiblestringOptional
arnA 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.stringonly available on credit card transactions from visa and mastercard
currencyAlphabetic currency code associated with the value in ISO 4217 format.stringOptionalDefault is USD
finx_midA unique ID for each merchant POS, assigned by merchant bankstringOptional

Merchant Object: transaction.merchant

ElementDescriptionTypeRequiredNotes
merchantElements pertaining to the location of the purchasetop level objectOptional
nameThe name of the merchantstringOptionale.g., ABC Store #23
display_nameConsumer facing name of the merchantstringOptionale.g., ABC

Location Object: transaction.location

ElementDescriptionTypeRequiredNotes
locationElements pertaining to the address of the store where the purchase took place as well as other detailstop level objectOptional
nameThe name of the locationstringOptional
display_nameConsumer facing name of the mechantstringOptionalOften the same as merchant.display_name

Address Object: transaction.location.address

ElementDescriptionTypeRequiredNotes
addressElements pertaining to the address of the store where the purchase took placetop level objectRequired
address_line_oneStreet address of the storestringOptional
address_line_twoAdditional address informationstringOptionalSuch as a lot number
cityCity of the storestringOptional
stateState of the storestringOptional
countryCountry of the storestringOptionalISO 3066-1, Alpha 2 format preferred
postal_codePostal code of the storestringOptionalMust 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",
      "consumer_token": "d448d0aa-4383-40ff-a222-4bca8d7d53d7",
      "description": "Pickles US 0903",
      "merchant": {
         "name": "Pickles US inc",        
         "display_name": "Pickles US"
      },
      "location": {
         "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": "Mastercard",
            "card_last_four": "9287",
            "total_amount": 20.98,
            "authorization_code": "392082",
            "finx_mid": "39801801084001",
            "arn": "198018429390",
            "bin": "749280"
      }       
   }
}

Response

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

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
401Not FoundNot authorized to view data
500Internal Server Error