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
  • Payment Rules API
  • Payouts API
      • POSTInitiate a payout transaction
      • GETSearch payouts by merchant reference
      • GETRetrieve Payout
      • GETList Payouts
  • Payers API [BETA]
  • Reporting API
  • Verification API
Log in to the PayOS Dashboard
LogoLogo
Payouts APIPayout

Search payouts by merchant reference

GET
https://api.payos.money/api/v1/payout/search
GET
/api/v1/payout/search
$curl -G https://api.payos.money/api/v1/payout/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      }
129    ],
130    "paymentAttributes": {},
131    "identifiers": {},
132    "paymentInstrument": {
133      "encryptedCardNumber": "string",
134      "encryptedCardCvv": "string",
135      "cardExpiryYear": "string",
136      "cardExpiryMonth": "string",
137      "cardHolderName": "string",
138      "payerEmail": "string",
139      "bin": "string",
140      "lastFour": "string",
141      "eci": "string",
142      "secure3d": {
143        "decision": "string",
144        "decisionReason": "string"
145      },
146      "retrievalReferenceNumber": "string",
147      "issuer": {
148        "country": "string"
149      }
150    },
151    "processorReference": "string",
152    "financialTransactionReference": "string",
153    "currentAttemptId": "string",
154    "batchPayoutId": "string",
155    "sender": {
156      "fullName": "string",
157      "phoneNumber": "string",
158      "email": "string",
159      "country": "string",
160      "nationality": "string",
161      "countryCode": "string",
162      "senderAddress": "string",
163      "dateOfBirth": "string",
164      "identity": "string",
165      "identityNumber": "string",
166      "identityExpiryDate": "string",
167      "jobDescription": "string",
168      "employerName": "string",
169      "purposeOfFunds": "string",
170      "sourceOfFunds": "string",
171      "relationship": "string",
172      "tariff": "string"
173    },
174    "recipient": {
175      "bankAccount": {
176        "accountNumber": "string",
177        "bankCode": "string",
178        "accountHolderName": "string",
179        "country": "string",
180        "phoneNumber": "string"
181      },
182      "mobileMoney": {
183        "phoneNumber": "string",
184        "country": "string",
185        "operator": "string",
186        "name": "string"
187      },
188      "card": {
189        "cardNumber": "string",
190        "cardHolderName": "string",
191        "country": "string"
192      },
193      "cash": {
194        "fullName": "string",
195        "country": "string",
196        "phoneNumber": "string"
197      },
198      "institutionWallet": {
199        "fullName": "string",
200        "country": "string",
201        "phoneNumber": "string"
202      }
203    }
204  }
205]
Retrieves payout transactions matching a merchant reference
Was this page helpful?
Previous

Retrieve Payout

Next
Built with

Query parameters

merchantIdslist of stringsRequired

Comma-separated list of merchant IDs to search within

merchantReferencestringRequired
Merchant reference to search for

Response

Payouts 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

Errors

401
Unauthorized Error
422
Unprocessable Entity Error
500
Internal Server Error