Look up an existing payee.
GET
/api/v1/payments/payee/lookup
GET /payee — for example to detect a duplicate before calling POST /payee again.data when no match is found rather than a 404, so a caller can distinguish "no match" from "request failed."📤 Response Fields
| Field | Type | Nullable | Description |
|---|---|---|---|
data | object | Yes | A saved payee (beneficiary) record. |
data.id | string (uuid) | No | The payee id — pass this as {payeeId} on GET/PUT calls and, elsewhere in the platform, as the beneficiary reference on a payout order. |
data.customerId | string (uuid) | No | The customer this payee belongs to. |
data.favouriteName | string | No | The partner-supplied display label for this payee, as given on create/update. |
data.currency | string | No | The payout currency this payee is set up to receive. |
data.status | string | Yes | Payee lifecycle status. See the status table above. |
data.beneficiary | object | No | — |
data.beneficiary.individual | object | No | Populate this when the beneficiary is a natural person. Mutually exclusive in practice with business — supply one or the other. |
data.beneficiary.individual.firstName | string | Yes | Given name, when the beneficiary is an individual. |
data.beneficiary.individual.middleName | string | Yes | Middle name, if applicable. |
data.beneficiary.individual.lastName | string | Yes | Family name, when the beneficiary is an individual. |
data.beneficiary.business | object | No | Populate this when the beneficiary is a company. Mutually exclusive in practice with individual. |
data.beneficiary.business.name | string | Yes | Registered business name, when the beneficiary is a business rather than an individual. |
data.beneficiary.contact | object | No | Contact details for the beneficiary, individual or business. |
data.beneficiary.contact.email | string (email) | Yes | The beneficiary's email address, used for payout notifications where the corridor supports them. |
data.beneficiary.contact.phone | object | No | The beneficiary's phone number. |
data.beneficiary.contact.phone.countryCode | string | Yes | Phone country calling code, e.g. "+1". |
data.beneficiary.contact.phone.number | string | Yes | Local phone number, digits only. |
data.address | object | No | — |
data.address.line1 | string | Yes | Street address line. |
data.address.city | string | Yes | City or town. |
data.address.state | string | Yes | State, province or region, where applicable. |
data.address.postalCode | string | Yes | Postal or ZIP code. |
data.address.country | string | Yes | Country name. Check GET /payee/countries for the accepted values for a given currency. |
data.kycDetails | object | No | — |
data.kycDetails.businessType | string | Yes | Legal business type, e.g. "llc" or "corporation" — required for business beneficiaries in some corridors. |
data.kycDetails.businessRegistrationNumber | string | Yes | Government-issued business registration number. |
data.bankAccount | object | No | — |
data.bankAccount.accountType | string | Yes | Account type at the bank, e.g. "checking" or "savings" — required for some corridors (notably US ACH), ignored for others. |
data.bankAccount.bankName | string | Yes | Name of the beneficiary bank. |
data.bankAccount.bankCountry | string | Yes | Country the beneficiary bank is domiciled in. |
data.bankAccount.bankCode | string | Yes | Local bank identifier where the corridor uses one instead of (or alongside) a SWIFT/BIC code, e.g. a sort-code-style bank code. |
data.bankAccount.accountNumber | string | Yes | The local account number. Not required where iban is supplied instead. |
data.bankAccount.iban | string | Yes | IBAN, for corridors that use it in place of a local account number. |
data.bankAccount.swiftBic | string | Yes | SWIFT/BIC code identifying the beneficiary bank for international wires. |
data.bankAccount.routingNumber | string | Yes | US ABA routing number, for US domestic transfers. |
data.bankAccount.sortCode | string | Yes | UK sort code, for GBP domestic transfers. |
data.bankAccount.branchCode | string | Yes | Bank branch identifier, where the corridor distinguishes branches separately from the bank code. |
data.payment | object | No | — |
data.payment.type | string | Yes | Payment method for payouts to this payee, e.g. "bank_transfer". |
data.payment.purpose | string | Yes | Default payment purpose for payouts to this payee. Check GET /payee/purposes for accepted values. |
data.payment.providerFields | object | Yes | Free-form key/value bag for provider-specific fields a particular corridor needs beyond the modeled ones above. Keys and value shapes vary by provider and corridor — confirm with your integration contact before relying on a specific key. |
data.createdAt | string (date-time) | No | When the payee was created. |
data.updatedAt | string (date-time) | Yes | When the payee was last updated. |
requestId | string | Yes | — |
timestamp | string (date-time) | No | — |
Request
Header Params
Responses
Request Request Example
Shell
JavaScript
Java
Swift
curl --location '/api/v1/payments/payee/lookup' \
--header 'X-API-Key: ak_live_8f3a9b2c7e1d4f6a9b0c2d5e8f1a3b6c' \
--header 'X-Signature: kZ3fQeT2m7xVvC9pR1sLdY8bN0hU4jK6oW5aE2gI7cQ=' \
--header 'X-Timestamp: 1758556800' \
--header 'X-Nonce: 3fa85f64-5717-4562-b3fc-2c963f66afa6' \
--header 'X-Body-Hash: 47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU='Response Response Example
200 - Success
{
"data": {
"id": "4d8f2a7c-9b1e-4c6d-8a3f-7e2b0c9d1a56",
"customerId": "c1f4a9d2-6b3e-4a7c-9f1d-2e8b5c0a7d31",
"favouriteName": "Acme Supplier — EUR",
"currency": "EUR",
"status": "active",
"beneficiary": {
"business": {
"name": "Acme Trading GmbH"
},
"contact": {
"email": "payments@acmetrading.example",
"phone": {
"countryCode": "+49",
"number": "3012345678"
}
}
},
"address": {
"line1": "Friedrichstrasse 123",
"city": "Berlin",
"state": null,
"postalCode": "10117",
"country": "Germany"
},
"kycDetails": {
"businessType": "gmbh",
"businessRegistrationNumber": "HRB123456B"
},
"bankAccount": {
"accountType": null,
"bankName": "Deutsche Bank",
"bankCountry": "Germany",
"bankCode": null,
"accountNumber": null,
"iban": "DE89370400440532013000",
"swiftBic": "DEUTDEFF",
"routingNumber": null,
"sortCode": null,
"branchCode": null
},
"payment": {
"type": "bank_transfer",
"purpose": "payment_for_services",
"providerFields": null
},
"createdAt": "2026-09-20T09:12:00Z",
"updatedAt": "2026-09-22T14:02:00Z"
},
"requestId": "req_4f9a2c7e1b8d3f6a9c2e0b7d1f8a3c6e",
"timestamp": "2026-09-22T14:03:11Z"
}Modified at 2026-09-23 04:45:35