Store Transaction Details

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

Name	Value
Content-Type	application/json
Authorization	Bearer <token>

Path Parameters

Name	Description
merchantId	Merchant Id for create transaction

Body

Name	Type	Required	Description
cardBin	String	True	The first 6 digits of the card used in the transaction.
cardLast4	String	True	The last 4 digits of the card used in the transaction.
transactionDate	String	True	The date and time of the transaction.
paymentDescriptor	String	True	The payment descriptor
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	The description of the product.
merchantInformation	Object	True	Object containing information about the merchant.
merchantInformation.merchantName	String	True	The name of the merchant.
merchantInformation.merchantUrl	String	True	The URL of the merchant.
merchantInformation.merchantContactPhone	String	True	The contact phone number of the merchant.
merchantInformation.storeDetails	Object	True	Object containing details about the merchant's store.
merchantInformation.storeDetails.storeName	String	True	The name of the store.
customerInformation	Object	True (Conditionally)	Object containing information about the customer, required for "CE" merchants.
customerInformation.accountId	String	True (Conditionally)	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)	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)	Required if other device fields are not provided.
device.ipAddress	String	True (Conditionally)	Required if other device fields are not provided.
device.deviceFingerprint	String	True (Conditionally)	Required if other device fields are not provided.

Store Transaction Details

post

Storing Merchant Transaction

Authorizations

Path parameters

merchantIdstringRequired

Merchant Id for create transaction

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

Response

application/json

400

Error

application/json

404

Merchant not found

application/json

500

Server Error

application/json

post

HTTPcURLJavaScriptPython

POST /api/v2/merchant/{merchantId}/transactionDetails 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": "Merchant transaction storing success",
  "txShieldOICartReference": "9fc0f822-5273-4f98-b95d-bb344d4e821f"
}