Store Transaction Details
POST https://{baseUrl}/api/v2/merchant/{merchantId}/transactionDetails
The Authorization Header is required if JWT (JSON Web Token) authentication is enabled in the application configuration (config.server.jwt_enable is true). This header must contain a valid JWT token prefixed with the word "Bearer". The token is used to authenticate the request and verify that the sender is authorized to perform the requested operation
The Request Body must be an array containing exactly one object. This object includes the details of the transaction and payment information.
This endpoint is used to store transaction details for a merchant identified by merchantId. The endpoint validates the request body, checks the merchant's enrollment, and stores the transaction data in both MongoDB and optionally in AWS DynamoDB.
Headers
Content-Type
application/json
Authorization
Bearer <token>
Path Parameters
merchantId
Merchant Id for create transaction
Body
transactionReference
String
True
Merchant-supplied reference identifying this transaction
cardBin
String
True
The six or eight-digit card Issuer BIN that is associated with the purchase.
cardLast4
String
True
The last four digits of the card number associated with the purchase.
transactionDate
String
True
Purchase transaction date in UTC format.
paymentDescriptor
String
True
The Merchant name component of the billing descriptor which appears on the customer's transaction statement.
receipt
Object
True
Object containing transaction details like payment information and purchased products.
receipt.paymentInformation
Object
True
Object containing payment details.
receipt.paymentInformation.paymentTotalAmount
Object
True
Object containing the total amount and currency.
receipt.paymentInformation.paymentTotalAmount.amount
Number
True
The total payment amount.
receipt.paymentInformation.paymentTotalAmount.currency
String
True
The currency of the payment.
receipt.productsPurchasedList
Array
True
List of products purchased in the transaction.
receipt.productsPurchasedList[].productDescription
String
True
Detailed description of the product (merchandise or service) purchased.
merchantInformation
Object
True
Object containing information about the merchant.
merchantInformation.merchantName
String
True
Corporate or Parent company name of the Merchant, may or may not be recognizable to the consumer. May be the name on file with your Acquirer/Merchant Account provider.
merchantInformation.merchantUrl
String
True
Merchant corporate business URL. May or may NOT be different from the URL the purchase was made from.
merchantInformation.merchantContactPhone
String
True
Merchant’s customer service phone number. Should be the number you would want a consumer to contact you to discuss any questions they may have about the purchase. Must be in E.164 format (“+” , 3-digit country code, 12-digit telephone number).
merchantInformation.storeDetails
Object
True
Object containing details about the merchant's store.
merchantInformation.storeDetails.storeName
String
True
Store/Webstore name where purchase was made. Should be recognizable to the consumer
customerInformation
Object
True (Conditionally)
Object containing information about the customer, required for "CE" merchants.
customerInformation.accountId
String
True (Conditionally)
Cardholder registered identifier to
uniquely identify their account with the
Merchant. This should be recognizable
to the Cardholder (not an internal system
identifier) and something they provided the
Merchant during account creation.
Examples are a unique username, email,
phone number or other similar value.
If a “guest” checkout option was used or the
Cardholder has NOT established/registered
an account with the Merchant this field
is not to be used.
Required for "CE" merchants if deliveryAddress is not provided.
deliveryAddress
Object
True (Conditionally)
Required for "CE" merchants if accountId is not provided.
deliveryAddress.address1
String
True (Conditionally)
Street address plus additional address lines such as suite number, apartment, etc. Required if the merchant enrollment is "CE" or based on specific conditions.
device
Object
True (Conditionally)
Required for "CE" merchants or if additional security checks are needed.
device.deviceId
String
True (Conditionally)
Device ID of the device used to submit order. Example values from device: • IMEI • MEID Required if other device fields are not provided.
device.ipAddress
String
True (Conditionally)
IP Address associated with the device. Only Public IP Addresses should be provided Required if other device fields are not provided.
device.deviceFingerprint
String
True (Conditionally)
Device fingerprint information is generated by a third-party service provider or the Merchant’s own algorithm to combine browser or device attributes to form a unique fingerprint to identify the device. Required if other device fields are not provided.
Storing Merchant Transaction
Merchant Id for create transaction
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.
ORDER-2026-0001First 6 or 8 digits of the card used in the transaction. Must be numeric.
^[0-9]+$Last 4 digits of the card used in the transaction. Must be numeric.
^[0-9]+$The date and time of the transaction in ISO 8601 format. Must be earlier than today.
Payment descriptor identifying the transaction.
Acquirer Reference Number.
Authorization code for the transaction.
Name of the recipient customer.
Response
Merchant transaction storing success9fc0f822-5273-4f98-b95d-bb344d4e821fThe merchant-supplied reference echoed back from the request.
ORDER-2026-0001Error
Forbidden - Token not authorized for this merchant
Merchant not found
Duplicate transactionReference for this merchant
Server Error
POST /api/v2/merchant/{merchantId}/transactionDetails 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": "Merchant transaction storing success",
"txShieldOICartReference": "9fc0f822-5273-4f98-b95d-bb344d4e821f",
"transactionReference": "ORDER-2026-0001"
}Last updated

