Upload Transaction Batch

POST https://{baseUrl}/api/v2/merchant/{merchantId}/uploadTransactionBatch

This endpoint is used to upload and validate a batch of transactions for a specified merchant. The Request Body must include a json array. Each array item should contain a single transaction object.

It performs general validation and mandatory field checks on the transaction data. If all validations pass, a success message is returned. Otherwise, detailed error messages are provided for any validation failures.

Headers

Name

Value

Content-Type

application/json

Authorization

Bearer <token>

Path Parameters

Name

Description

merchantId

Merchant Id for transaction batch upload

Body

Name

Type

Required

Description

transactionReference

String

True

Merchant-supplied reference identifying this transaction

transactionDate

Datetime (ISO 8601 format)

True

Date and time when the order was placed.

paymentDescriptor

String

True

Payment descriptor as it appears on the customer's statement.

cardBin

String

True

First six digits of the credit card used for the transaction.

cardLast4

String

True

Last four digits of the credit card used for the transaction.

receipt

Object

True

Contains detailed information about the receipt

receipt.paymentInformation

Object

True

Contains detailed information about the payment information

receipt.paymentInformation.paymentTotalAmount

Object

True

Contains detailed information about the payment total amount

receipt.paymentInformation.paymentTotalAmount.amount

Number

True

The payment amount

receipt.paymentInformation.paymentTotalAmount.currency

String

True

The payment currency

merchantInformation

Object

True

Contains detailed information about the merchant information

merchantInformation.merchantName

String

True

The merchant name

merchantInformation.merchantUrl

String

True

The merchant url

merchantInformation.merchantContactPhone

String

True

The merchant contact phone

merchantInformation.storeDetails.storeName

String

True

The store name

deliveryAddress

Object

True

Contains detailed information about the delivery address

deliveryAddress.address1

String

True

The delivery address

deliveryAddress.city

String

True

The delivery city

deliveryAddress.region

String

True

The delivery region

deliveryAddress.postalCode

String

True

The delivery postal code

deliveryAddress.country

String

True

The delivery country

device

Object

True

Contains detailed information about the device

device.deviceId

String

True

The device id

device.ipAddress

String

True

The device ip address

device.deviceFingerprint

String

True (Conditionally)

The device fingerprint

Upload Transaction Batch

post

Upload a batch of merchant transactions as JSON.

Authorizations

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

merchantIdstringRequired

Merchant Id for transaction batch upload

Bodyobject[]

transactionReferencestring · max: 100Required

Merchant-supplied reference identifying this transaction. Leading/trailing whitespace is trimmed before storage. Must be unique per merchant - duplicates are rejected (single endpoint returns 409; batch endpoints mark the row as error). Echoed back (trimmed) in the response so the merchant can map their reference to the txShieldOICartReference.

Example: ORDER-2026-0001

cardBinstring · min: 6 · max: 8Required

First 6 or 8 digits of the card used in the transaction. Must be numeric.

Pattern: ^[0-9]+$

cardLast4string · min: 4 · max: 4Required

Last 4 digits of the card used in the transaction. Must be numeric.

Pattern: ^[0-9]+$

transactionDatestring · date-timeRequired

The date and time of the transaction in ISO 8601 format. Must be earlier than today.

paymentDescriptorstring · max: 25Required

Payment descriptor identifying the transaction.

arnstring · max: 24Optional

Acquirer Reference Number.

authCodestring · max: 6Optional

Authorization code for the transaction.

recipientCustomerNamestring · max: 20Optional

Name of the recipient customer.

Responses

200

Successful Response

application/json

msgstringOptionalExample: Transactions processed

400

Bad Request

application/json

401

Unauthorized

application/json

404

Not Found

application/json

500

Internal Server Error

application/json

post/api/v2/merchant/{merchantId}/uploadTransactionBatch

POST /api/v2/merchant/{merchantId}/uploadTransactionBatch HTTP/1.1
Host: {baseUrl}
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 5828

{
  "transactionReference": "ORDER-2026-0001",
  "transactionDate": "2025-01-01T12:00:00Z",
  "cardBin": "411111",
  "cardLast4": "1111",
  "paymentDescriptor": "MERCHANT*ONLINESALE",
  "arn": "24692163176000409618961",
  "authCode": "352837",
  "receipt": {
    "orderDate": "2023-01-27T19:11:28Z",
    "orderNumber": "53212X",
    "purchaseCategory": "MERCHANDISE",
    "invoiceNumber": "BBB23243432",
    "subTotalAmount": {
      "amount": 247.5,
      "currency": "USD"
    },
    "taxAmount": {
      "amount": 23,
      "currency": "USD"
    },
    "taxDescription": "CA state 8%",
    "shippingAndHandlingAmount": {
      "amount": 40,
      "currency": "USD"
    },
    "orderTotalAmount": {
      "amount": 310.5,
      "currency": "USD"
    },
    "paymentInformation": {
      "paymentMethod": "VISA xxxxxxxxxxxx1111",
      "billingName": "Joe Customer",
      "billingAddressDetails": {
        "address1": "5670 Wilshire Blvd",
        "address2": "Suite 2200",
        "city": "Los Angeles",
        "region": "CA",
        "postalCode": "90036",
        "country": "USA"
      },
      "paymentSubTotalAmount": {
        "amount": 247.5,
        "currency": "USD"
      },
      "paymentTotalBeforeTax": {
        "amount": 287.5,
        "currency": "USD"
      },
      "paymentTaxAmount": {
        "amount": 23,
        "currency": "USD"
      },
      "paymentTaxDescription": "CA state 8%",
      "paymentTotalAmount": {
        "amount": 310.5,
        "currency": "USD"
      },
      "cvvChecked": true
    },
    "productsPurchasedList": [
      {
        "productType": "ELECTRONICS",
        "productDescription": "ABC Smart Watch, Fitness Tracker and Health Monitor",
        "productUrl": "https://www.verifi.com/product/7366",
        "artistOrSeller": "QualityElectronics",
        "unitPriceAmount": {
          "amount": 100.25,
          "currency": "USD"
        },
        "quantity": 1,
        "deliveryDetails": {
          "shippingCarrier": "UPS",
          "dateOfShipment": "2023-01-27T19:11:28Z",
          "dateOfDelivery": "2023-01-29T11:44:00Z",
          "otherStatusDescription": "DELIVERED: Left at front door",
          "trackingNumber": "1Z9999999999999999",
          "deliveryStatus": "OTHER"
        }
      }
    ]
  },
  "merchantInformation": {
    "merchantName": "Example Merchant LLC",
    "merchantUrl": "https://www.examplemerchant.com",
    "websiteUrl": "https://www.examplemerchantsale.com",
    "merchantContactPhone": "+18005551234",
    "merchantAddress": {
      "address1": "5670 Wilshire Blvd",
      "address2": "Suite 2200",
      "city": "Los Angeles",
      "region": "CA",
      "postalCode": "90036",
      "country": "USA"
    },
    "termsAndConditions": "https://www.examplemerchant.com/terms-of-use/",
    "storeDetails": {
      "storeName": "Example Store Location",
      "storeContactPhone": "+13236555789",
      "storeLocation": {
        "geoLocation": {
          "latitude": "34.0620",
          "longitude": "-118.3521"
        },
        "locationAddress": {
          "address1": "5670 Wilshire Blvd",
          "address2": "Suite 2200",
          "city": "Los Angeles",
          "region": "CA",
          "postalCode": "90036",
          "country": "USA"
        }
      }
    }
  },
  "customerInformation": {
    "accountId": "CUST-12345",
    "emailAddress": "customer@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "lengthOfRelationship": "4"
  },
  "deliveryAddress": {
    "address1": "123 Main Street",
    "address2": "Suite 2200",
    "city": "Anytown",
    "region": "ST",
    "postalCode": "12345",
    "country": "USA"
  },
  "device": {
    "deviceId": "a1b2c3d4e5f6a7b8c9d0",
    "deviceType": "Mobile",
    "deviceName": "John's iPhone",
    "ipAddress": "203.0.113.47",
    "deviceFingerprint": "ace4cb941f15613bdc7e69b28318646915928a6d",
    "deviceLocation": {
      "geoLocation": {
        "latitude": "34.0620",
        "longitude": "-118.3521"
      },
      "locationAddress": {
        "address1": "5670 Wilshire Blvd",
        "address2": "Suite 2200",
        "city": "Los Angeles",
        "region": "CA",
        "postalCode": "90036",
        "country": "USA"
      }
    }
  },
  "flightDetails": {
    "reservationNumber": "CSX-09283",
    "reservationDate": "2023-01-30T19:11:28Z",
    "memberRewardsNumber": "U1985932",
    "memberRewardsName": "Joe Customer",
    "passengerName1": "Joe Customer",
    "passengerName2": "Maria Customer",
    "passengerName3": "John Customer",
    "passengerName4": "Philip Customer",
    "passengerName5": "Tracy Customer",
    "itinerary": "ORD to LAX Premium Economy",
    "additionalRelatedPurchases": 0,
    "flightManifestName": "Joe Customer",
    "flightManifestDateOfBirth": "1990-01-15T00:00:00Z",
    "travelUtilizationIndicator": true,
    "travelInsurance": "https://www.example.com/link/283737",
    "reservationReceivedFrom": "Joe Customer",
    "termsAndConditions": "https://www.example.com/terms-of-use/"
  },
  "hotelDetails": {
    "reservationNumber": "M3928472",
    "reservationDate": "2023-01-30T19:11:28Z",
    "memberRewardsNumber": "JC8377-HKP",
    "memberRewardsNameRegistered": "Joe Customer",
    "checkInDate": "2023-01-29T19:11:28Z",
    "checkOutDate": "2023-01-30T07:12:45Z",
    "lengthOfStay": 1,
    "hotelRoomType": "KING GARDEN VIEW",
    "travelInsurance": "https://www.example.com/policy/insurance",
    "reservationReceivedFrom": "Joe Customer",
    "termsAndConditions": "https://www.example.com/terms-of-use/"
  },
  "carRentalDetails": {
    "reservationNumber": "C2837472",
    "reservationDate": "2023-01-30T19:11:28Z",
    "memberRewardsNumber": "REW028842",
    "memberRewardsName": "Joe Customer",
    "carRentalVehicleDescription": "Ford Bronco Sport - Blue",
    "carRentalPickupDate": "2023-01-30T19:11:28Z",
    "carRentalPickupLocation": {
      "geoLocation": {
        "latitude": "34.0522",
        "longitude": "-118.2437"
      },
      "locationAddress": {
        "address1": "5670 Wilshire Blvd",
        "address2": "Suite 2200",
        "city": "Los Angeles",
        "region": "CA",
        "postalCode": "90036",
        "country": "USA"
      }
    },
    "carRentalDropOffDate": "2023-01-30T19:11:28Z",
    "carRentalDropOffLocation": {
      "geoLocation": {
        "latitude": "34.0522",
        "longitude": "-118.2437"
      },
      "locationAddress": {
        "address1": "5670 Wilshire Blvd",
        "address2": "Suite 2200",
        "city": "Los Angeles",
        "region": "CA",
        "postalCode": "90036",
        "country": "USA"
      }
    },
    "travelInsurance": "https://www.example.com/insurance",
    "reservationReceivedFrom": "Joe Customer",
    "termsAndConditions": "https://www.example.com/terms-of-use/"
  },
  "rideShareDetails": {
    "pickupLocation": {
      "geoLocation": {
        "latitude": "34.0620",
        "longitude": "-118.3521"
      },
      "locationAddress": {
        "address1": "5670 Wilshire Blvd",
        "address2": "Suite 2200",
        "city": "Los Angeles",
        "region": "CA",
        "postalCode": "90036",
        "country": "USA"
      }
    },
    "dropOffLocation": {
      "geoLocation": {
        "latitude": "34.0620",
        "longitude": "-118.3521"
      },
      "locationAddress": {
        "address1": "5670 Wilshire Blvd",
        "address2": "Suite 2200",
        "city": "Los Angeles",
        "region": "CA",
        "postalCode": "90036",
        "country": "USA"
      }
    },
    "dateOfTrip": "2023-01-30T19:11:28Z",
    "totalAmount": {
      "amount": 100.25,
      "currency": "USD"
    },
    "vehicleDescription": "Toyota Corolla 4DR - Silver",
    "termsAndConditions": "https://www.example.com/terms-of-use/"
  }
}

{
  "msg": "Transactions processed",
  "results": [
    {
      "status": "success",
      "index": 0,
      "transactionReference": "ORDER-2026-0001",
      "txShieldOICartReference": "9fc0f822-5273-4f98-b95d-bb344d4e821f"
    },
    {
      "status": "success",
      "index": 1,
      "transactionReference": "ORDER-2026-0002",
      "txShieldOICartReference": "3a7c9b41-82de-4f1e-a035-c7d6e8f90b12"
    },
    {
      "status": "error",
      "index": 2,
      "transactionReference": "ORDER-2026-0001",
      "msg": "transactionReference already exists for this merchant"
    }
  ]
}

PreviousValidate Cart Details NextUpload Transaction Batch File

Last updated 1 month ago