For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Log in to the PayOS Dashboard
GuidesAPI ReferenceHelp Center
GuidesAPI ReferenceHelp Center
  • Authentication API
    • POSTRequest an Access Token
  • Payments API
      • GETList Payments
      • POSTInitiate Payment
      • GETSearch payments by merchant reference
      • GETRetrieve Payment
      • POSTAuthorize Payment
  • Payment Rules API
  • Payouts API
  • Payers API [BETA]
  • Reporting API
  • Verification API
Log in to the PayOS Dashboard
LogoLogo
Payments APIPayment

Search payments by merchant reference

GET
https://api.payos.money/api/v1/payment/search
GET
/api/v1/payment/search
$curl -G https://api.payos.money/api/v1/payment/search \
>     -d merchantIds=string \
>     -d merchantReference=merchantReference
1[
2  {
3    "currentState": "string",
4    "previousStates": [
5      "string"
6    ],
7    "processor": "string",
8    "merchantName": "string",
9    "transactionId": "string",
10    "amount": 1.1,
11    "transactionType": "string",
12    "paymentMethodId": "string",
13    "currency": "string",
14    "merchantReference": "string",
15    "transactionStates": [
16      {
17        "pendingState": {
18          "state": "string",
19          "transitionedAt": "string",
20          "transactionId": "string"
21        },
22        "balancePendingState": {
23          "state": "string",
24          "transitionedAt": "string"
25        },
26        "balanceVerifiedState": {
27          "state": "string",
28          "transitionedAt": "string"
29        },
30        "authRequiredState": {
31          "state": "string",
32          "transitionedAt": "string",
33          "authMethodType": "redirect",
34          "redirect": {
35            "url": "string"
36          }
37        },
38        "errorState": {
39          "state": "string",
40          "transitionedAt": "string",
41          "message": "string",
42          "code": "configurationError",
43          "connectorFailureCode": "string",
44          "connectorFailureMessage": "string"
45        },
46        "failedState": {
47          "state": "string",
48          "transitionedAt": "string",
49          "message": "string",
50          "code": "3dsDeclinedByUser",
51          "connectorFailureCode": "string",
52          "connectorFailureMessage": "string"
53        },
54        "successState": {
55          "state": "string",
56          "transitionedAt": "string"
57        },
58        "routedState": {
59          "state": "string",
60          "transitionedAt": "string",
61          "message": "string",
62          "processorDisplayName": "string",
63          "applicableRules": [
64            {
65              "ruleId": "string",
66              "ruleName": "string"
67            }
68          ],
69          "card": {
70            "encryptedCardNumber": "string",
71            "cardExpiryMonth": "string",
72            "cardExpiryYear": "string",
73            "encryptedCardCvv": "string",
74            "cardHolderName": "string",
75            "payerEmail": "string",
76            "cardBrand": "string",
77            "cardBin": "string",
78            "cardLastFour": "string",
79            "shouldSaveCard": true
80          },
81          "ieft": {},
82          "directCharge": {
83            "payerBank": "string",
84            "payerAccountNumber": "string"
85          },
86          "bankTransfer": {
87            "transactionReference": "string",
88            "payerFullName": "string",
89            "phoneNumber": "string",
90            "bankCountry": "string"
91          },
92          "mobileMoney": {
93            "provider": "airtel",
94            "payerMobileNumber": "string",
95            "payerFullName": "string",
96            "providerCategoryKey": "string"
97          }
98        },
99        "receivedState": {
100          "state": "string",
101          "transitionedAt": "string",
102          "message": "string"
103        },
104        "completedState": {
105          "state": "string",
106          "transitionedAt": "string",
107          "message": "string"
108        },
109        "authExecutingState": {
110          "state": "string",
111          "transitionedAt": "string",
112          "message": "string"
113        },
114        "cancelledState": {
115          "state": "string",
116          "transitionedAt": "string"
117        },
118        "expiredState": {
119          "state": "string",
120          "transitionedAt": "string"
121        },
122        "settledState": {
123          "state": "string",
124          "transitionedAt": "string",
125          "settledAt": "string",
126          "settlementId": "string"
127        },
128        "heldPendingReviewState": {
129          "state": "string",
130          "transitionedAt": "string",
131          "reason": "string"
132        },
133        "autoRefundState": {
134          "state": "string",
135          "transitionedAt": "string",
136          "reason": "string"
137        },
138        "refundedState": {
139          "state": "string",
140          "transitionedAt": "string"
141        }
142      }
143    ],
144    "paymentAttributes": {},
145    "identifiers": {},
146    "paymentInstrument": {
147      "encryptedCardNumber": "string",
148      "encryptedCardCvv": "string",
149      "cardExpiryYear": "string",
150      "cardExpiryMonth": "string",
151      "cardHolderName": "string",
152      "payerEmail": "string",
153      "bin": "string",
154      "lastFour": "string",
155      "eci": "string",
156      "secure3d": {
157        "decision": "string",
158        "decisionReason": "string"
159      },
160      "retrievalReferenceNumber": "string",
161      "issuer": {
162        "country": "string"
163      }
164    },
165    "processorReference": "string",
166    "financialTransactionReference": "string",
167    "currentAttemptId": "string",
168    "batchPayoutId": "string",
169    "sender": {
170      "fullName": "string",
171      "phoneNumber": "string",
172      "email": "string",
173      "country": "string",
174      "nationality": "string",
175      "countryCode": "string",
176      "senderAddress": "string",
177      "dateOfBirth": "string",
178      "identity": "string",
179      "identityNumber": "string",
180      "identityExpiryDate": "string",
181      "jobDescription": "string",
182      "employerName": "string",
183      "purposeOfFunds": "string",
184      "sourceOfFunds": "string",
185      "relationship": "string",
186      "tariff": "string"
187    },
188    "recipient": {
189      "bankAccount": {
190        "accountNumber": "string",
191        "bankCode": "string",
192        "accountHolderName": "string",
193        "country": "string",
194        "phoneNumber": "string"
195      },
196      "mobileMoney": {
197        "phoneNumber": "string",
198        "country": "string",
199        "operator": "string",
200        "name": "string"
201      },
202      "card": {
203        "cardNumber": "string",
204        "cardHolderName": "string",
205        "country": "string"
206      },
207      "cash": {
208        "fullName": "string",
209        "country": "string",
210        "phoneNumber": "string"
211      },
212      "institutionWallet": {
213        "fullName": "string",
214        "country": "string",
215        "phoneNumber": "string"
216      }
217    },
218    "collection": {
219      "amount": "string",
220      "currency": "string"
221    },
222    "fxMidRate": "string",
223    "fxAllInRate": "string",
224    "fxMarkupBps": 1,
225    "fxFee": {
226      "amount": "string",
227      "currency": "string"
228    }
229  }
230]
Retrieves payment transactions matching a merchant reference
Was this page helpful?
Previous

Retrieve Payment

Next
Built with

Query parameters

merchantIdslist of stringsRequired

Comma-separated list of merchant IDs to search within

merchantReferencestringRequired
Merchant reference to search for

Response

Payments retrieved successfully
currentStatestring
Current transaction state
previousStateslist of strings
Array of previous transaction states
processorstring
Payment processor used for the transaction
merchantNamestring
Merchant name
transactionIdstring
Unique transaction identifier
amountdouble
Transaction amount
transactionTypestring
Transaction type
paymentMethodIdstring
Payment method identifier
currencystring
Transaction currency
merchantReferencestring
Merchant reference
transactionStateslist of objects
Detailed transaction state history
paymentAttributesmap from strings to strings

Payment-specific attributes and metadata

identifiersmap from strings to strings
Additional transaction identifiers
paymentInstrumentobject
Card payment instrument details
processorReferencestring
Payment processor reference
financialTransactionReferencestring
Financial transaction reference from the processor
currentAttemptIdstring
Current attempt identifier
batchPayoutIdstring
Batch payout identifier, if the transaction is part of a batch payout
senderobject
Sender details for a payout transaction
recipientobject
Recipient details for a payout transaction
collectionobject

Monetary amount as a decimal-string major unit + currency code

fxMidRatestringformat: "^\d+(\.\d+)?$"

Spot mid-market rate at the time the quote was committed (8 decimal places).

fxAllInRatestringformat: "^\d+(\.\d+)?$"

Mid rate + markup — the rate actually applied to convert source to collection (8 decimal places).

fxMarkupBpsinteger>=0

Markup applied in basis points (0–10000).

fxFeeobject

Monetary amount as a decimal-string major unit + currency code

Errors

401
Unauthorized Error
422
Unprocessable Entity Error
500
Internal Server Error