API: POST Transaction


The important pieces of onboarding for a transaction on Confirm are very similar to onboarding for Banyan Enrich. The biggest distinction is the importance of including the same finx_consumer_token sent with the offer activation in the transaction record. This is the key to signaling to our matching engine that there is an offer that needs to be assessed.

Developers, please see the API Reference for an interactive example.


POST api.banyan.com/rest/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.

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])


Header NameDescriptionRequiredValues
BearerAccess TokenRequiredSee Authorization section
Content-TypeThe transaction format to sendOptionalapplication/JSON
AcceptThe response format sent backOptionalapplication/JSON


Top Level Objects

ElementDescriptionData TypeRequiredNotes
transaction_idUnique to the transactionstringRequired
purchase_tsWhen the purchase occurredRFC3339RequiredTimestamp is in UTC, example: 2021-01-28T14:43:50.52Z
currencyCurrency of the transaction amountstringOptionalDefault is USD
consumer_tokenA hashed token that is unique to the household or consumerstringOptional

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

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 transactiondecimalRequired
auth_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

Merchant Object

merchantElements pertaining to the location of the purchasetop level objectRequired
nameThe name of the merchantstringOptionalE.g., ABC Store #23
descriptionThe description of the transaction, with merchant detailsstringOptional
merchant_idAlso known as MID, it’s a 15-digit distinctive code assigned by merchant bank to identifies a merchant account to their acquirerstringOptional

Location Object

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/rest/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"


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

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