Upload Transaction Batch

POST https://{base_url}/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
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

Path parameters

merchantIdstringRequired

Merchant Id for transaction batch upload

Body

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

400

Bad Request

application/json

401

Unauthorized

application/json

404

Not Found

application/json

500

Internal Server Error

application/json

post

HTTPcURLJavaScriptPython

POST /api/v2/merchant/{merchantId}/uploadTransactionBatch HTTP/1.1
Host: {baseurl}
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 5769

[
  {
    "transactionDate": "2025-01-01T12:00:00Z",
    "cardBin": "411111",
    "cardLast4": "1111",
    "paymentDescriptor": "EXAMPLE MERCHANT",
    "arn": "12345678901234567890",
    "authCode": "123456",
    "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": 123.45,
          "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": "[phone]",
      "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": "[phone]",
        "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": "[e-mail]",
      "firstName": "John",
      "lastName": "Doe",
      "lengthOfRelationship": "4"
    },
    "deliveryAddress": {
      "address1": "123 Main Street",
      "address2": "Suite 2200",
      "city": "Anytown",
      "region": "ST",
      "postalCode": "12345",
      "country": "USA"
    },
    "device": {
      "deviceId": "a1b2c3d4e5f6g7h8i9j0",
      "deviceType": "Mobile",
      "deviceName": "John's iPhone",
      "ipAddress": "192.168.1.1",
      "deviceFingerprint": "xyz-device-fingerprint-123",
      "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",
      "txShieldOICartReference": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6"
    },
    {
      "status": "success",
      "txShieldOICartReference": "q1r2s3t4-u5v6-w7x8-y9z0-a1b2c3d4e5f6"
    }
  ]
}

Upload Transaction Batch

post

Upload a batch of merchant transactions as JSON.

Authorizations

Path parameters

merchantIdstringRequired

Merchant Id for transaction batch upload

Body

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.

Responses

200

Successful Response

application/json

400

Bad Request

application/json

401

Unauthorized

application/json

404

Not Found

application/json

500

Internal Server Error

application/json

post

HTTPcURLJavaScriptPython

POST /api/v2/merchant/{merchantId}/uploadTransactionBatch HTTP/1.1
Host: {baseurl}
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 2153

[
  {
    "transactionDate": "2025-01-01T12:00:00Z",
    "cardBin": "411111",
    "cardLast4": "1111",
    "paymentDescriptor": "EXAMPLE MERCHANT",
    "arn": "12345678901234567890",
    "authCode": "123456",
    "receipt": {
      "orderNumber": "ORD-123456",
      "paymentInformation": {
        "paymentTotalAmount": {
          "amount": 123.45,
          "currency": "USD"
        }
      },
      "productsPurchasedList": [
        {
          "productDescription": "Premium Headphones",
          "deliveryDetails": {
            "deliveryStatus": "SHIPPED",
            "dateOfShipment": "2025-01-02T10:00:00Z"
          }
        }
      ]
    },
    "merchantInformation": {
      "merchantName": "Example Merchant LLC",
      "merchantUrl": "https://www.examplemerchant.com",
      "merchantContactPhone": "[phone]",
      "storeDetails": {
        "storeName": "Example Store Location"
      }
    },
    "customerInformation": {
      "accountId": "CUST-12345",
      "emailAddress": "[e-mail]"
    },
    "deliveryAddress": {
      "address1": "123 Main Street",
      "city": "Anytown",
      "region": "ST",
      "postalCode": "12345",
      "country": "USA"
    },
    "device": {
      "deviceId": "a1b2c3d4e5f6g7h8i9j0",
      "ipAddress": "192.168.1.1",
      "deviceFingerprint": "xyz-device-fingerprint-123"
    }
  },
  {
    "transactionDate": "2025-01-02T15:30:00Z",
    "cardBin": "511111",
    "cardLast4": "2222",
    "paymentDescriptor": "EXAMPLE MERCHANT",
    "arn": "09876543210987654321",
    "authCode": "654321",
    "receipt": {
      "orderNumber": "ORD-789012",
      "paymentInformation": {
        "paymentTotalAmount": {
          "amount": 89.99,
          "currency": "USD"
        }
      },
      "productsPurchasedList": [
        {
          "productDescription": "Wireless Charging Pad",
          "deliveryDetails": {
            "deliveryStatus": "DELIVERED",
            "dateOfShipment": "2025-01-03T09:00:00Z",
            "dateOfDelivery": "2025-01-05T14:30:00Z"
          }
        },
        {
          "productDescription": "Phone Case",
          "deliveryDetails": {
            "deliveryStatus": "DELIVERED",
            "dateOfShipment": "2025-01-03T09:00:00Z",
            "dateOfDelivery": "2025-01-05T14:30:00Z"
          }
        }
      ]
    },
    "merchantInformation": {
      "merchantName": "Example Merchant LLC",
      "merchantUrl": "https://www.examplemerchant.com",
      "merchantContactPhone": "[phone]",
      "storeDetails": {
        "storeName": "Example Store Location"
      }
    },
    "customerInformation": {
      "accountId": "CUST-67890",
      "emailAddress": "[e-mail]"
    },
    "deliveryAddress": {
      "address1": "456 Oak Avenue",
      "city": "Somewhere",
      "region": "ST",
      "postalCode": "67890",
      "country": "USA"
    },
    "device": {
      "deviceId": "j9i8h7g6f5e4d3c2b1a0",
      "ipAddress": "192.168.2.2",
      "deviceFingerprint": "abc-device-fingerprint-456"
    }
  }
]

{
  "msg": "Transactions processed",
  "results": [
    {
      "status": "success",
      "txShieldOICartReference": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6"
    },
    {
      "status": "success",
      "txShieldOICartReference": "q1r2s3t4-u5v6-w7x8-y9z0-a1b2c3d4e5f6"
    }
  ]
}