Query Transactions

You can query a specific transaction to retrieve detailed information about it. This is useful when a Paybyrd webhook is not received or a technical issue prevents your software from receiving a payment response. Without this response, your staff may be unable to verify whether the transaction was processed or what its result was. They may also attempt to cancel or refund the transaction, or inadvertently create a duplicate.

Query a transaction

Example request and response for the Query transactions endpoint:

curl --request GET \
  --url https://gateway.paybyrd.com/api/v2/transactions/{transactionId} \
  --header 'Accept: application/json' \
  --header 'x-api-key: {your_api_key}'

{
   "referencedTransactions":[],
   "code":"BYRD200",
   "description":"Operation successfully completed",
   "currency":"EUR",
   "orderRef":"ORDER#3570",
   "brand":"VISA",
   "operationType":"Payment",
   "status":"Success",
   "fingerPrint":"fb1714e5-f2a4-40c8-b3e6-7487187bdaab",
   "createdDate":"2021-06-08T22:07:37Z",
   "transactionDate":"2021-06-08T22:07:37Z",
   "capturedDate":"2021-06-08T22:08:06Z",
   "maskedCardNumber":"420000******0000",
   "initiatedFrom":"HostedForm",
   "subscriptionGuid":"476f8d2c-22ee-42a0-b986-0d01b9292c49",
   "personId":78,
   "index":2,
   "externalSessionIdentifier":"f31a836d-42c6-41c7-b0d0-109d64efb133",
   "externalTransactionIdentifier":"b1b2cf19-e9fe-4b7c-be1a-a12f0f8899f2",
   "externalCustomIdentifier":"8cb922ee-01cd-453d-90b9-b377e4f1d38b",
   "transactionId":"8cb922ee-01cd-453d-90b9-b377e4f1c3cb",
   "amount":"5.00",
   "acquirerEntity": "11854",
   "acquirerReference": "999999935"
}

Shift code and tip

For POS transactions, the response can include the shiftCode and tip fields. Use them to reconcile your POS shifts, for example to total the sales and tips of each shift.

Field	Type	Description
`shiftCode`	string	The code of the shift the transaction belongs to.
`tip`	object	The tip included in the transaction.
`tip.isoAmount`	integer	The tip amount in minor units, for example `250`.
`tip.amount`	string	The tip amount in major units, for example `"2.50"`.

Both fields are optional:

shiftCode appears only when the transaction is linked to a shift. When there is no shift, the response doesn’t include the shiftCode key.
tip appears only when the transaction has a tip. When there is no tip, the response doesn’t include the tip key.

tip.amount uses the currency exponent, like the top-level amount field. For example, a tip with isoAmount 250 in EUR is "2.50", 300 in JPY is "300" and 1250 in BHD is "1.250".

The top-level amount and isoAmount include the tip. To get the amount without the tip, calculate isoAmount - tip.isoAmount. When there is no tip, the amount without the tip is isoAmount.

{
   "referencedTransactions":[],
   "code":"BYRD200",
   "description":"Operation successfully completed",
   "currency":"EUR",
   "brand":"VISA",
   "operationType":"Payment",
   "status":"Success",
   "initiatedFrom":"POS",
   "transactionId":"8cb922ee-01cd-453d-90b9-b377e4f1c3cb",
   "amount":"42.50",
   "isoAmount":4250,
   "shiftCode":"SHIFT-0001",
   "tip":{
      "isoAmount":250,
      "amount":"2.50"
   }
}

{
   "referencedTransactions":[],
   "code":"BYRD200",
   "description":"Operation successfully completed",
   "currency":"EUR",
   "brand":"VISA",
   "operationType":"Payment",
   "status":"Success",
   "initiatedFrom":"POS",
   "transactionId":"3f9d2c71-6a4e-4b8f-9c15-2e7a8d0b4f63",
   "amount":"40.00",
   "isoAmount":4000
}

Query a transaction by acquirer custom identifier

Example request and response for querying a transaction by acquirer custom identifier:

curl --request GET \
  --url https://gateway.paybyrd.com/api/v2/transactions?acquirerCustomId=${customIdentifier} \
  --header 'Accept: application/json' \
  --header 'x-api-key: {your_api_key}'

[
    {
        "currency": "EUR",
        "acquirer": "SIMULATED",
        "brand": "MASTER",
        "paymentMethod": "Card",
        "operationType": "Payment",
        "status": "Success",
        "fingerPrint": "f7f76173-f357-4863-bbc3-f5b6204a2769",
        "createdDate": "2025-05-12T18:04:38Z",
        "transactionDate": "2025-05-12T18:04:38Z",
        "capturedDate": "2025-05-12T18:04:41Z",
        "maskedCardNumber": "555534******1115",
        "authorizationCode": "327161",
        "initiatedFrom": "Server",
        "subscriptionGuid": "b9852997-0e6a-4542-a9fd-e9ae76967653",
        "personId": 10,
        "expiresAt": "2025-05-12T18:19:39Z",
        "attempt": 0,
        "index": 0,
        "externalSessionIdentifier": "b7fc1639-6dda-4c20-b618-097ef1e4e842",
        "externalTransactionIdentifier": "b15dc08a-277e-4c24-95e4-0ceb10540efd",
        "externalCustomIdentifier": "bc0a8270d48b4a3d9f1bf0a4eab365dc",
        "acquirerResponseCode": "00",
        "acquirerResponseMessage": "Success",
        "card": {
            "holder": "Jane Jones",
            "number": "555534******1115",
            "expiresAt": "12/25",
            "installments": 1,
            "installmentAmount": 2634,
            "isPayerTraveling": false,
            "countryCode": "QAT"
        },
        "acceptTokenization": true,
        "cardInfoComposition": {
            "cardServiceType": "Credit",
            "sourceEnvironment": "Online",
            "cardCommercialType": "Corporate",
            "cardIssueLocation": "NonEea"
        },
        "transactionId": "bc0a8270-d48b-4a3d-9f1b-f0a4eab365dc",
        "amount": "26.34",
        "isoAmount": 2634
    }
]

See the Query transactions API endpoint for more details. The status field indicates whether the transaction was processed successfully. See the Transaction statuses table for the full list of possible values.

Accept Payments

Manage Payments

Query Transactions

Query a transaction

Shift code and tip

Query a transaction by acquirer custom identifier

​Query a transaction

​Shift code and tip

​Query a transaction by acquirer custom identifier

Query a transaction

Shift code and tip

Query a transaction by acquirer custom identifier