Merchants (Payees)
Create and manage the payees you attribute payments to.
Merchants (Payees)
A merchant is a saved payee — a party you attribute payments to. Create a
merchant once, then reference it by merchantId when you Create a Payment,
instead of repeating the payee's bank details on every request. See Core
Concepts for how merchants relate to payments.
All endpoints require a Bearer token — see Authentication. Failed requests
return the standard error shape — see Errors.
| Endpoint | Purpose |
|---|---|
POST /v2/merchants | Create a merchant. |
GET /v2/merchants | List merchants. |
GET /v2/merchants/{merchantId} | Read one merchant. |
DELETE /v2/merchants/{merchantId} | Delete a merchant. |
Create a merchant
POST https://api.open-finance.ai/v2/merchants
| Field | Required | Description |
|---|---|---|
name | ✅ | The merchant name. |
bban | – | The merchant's bank account (BBAN). |
iban | – | The merchant's bank account (IBAN). |
psuId | – | The merchant's national ID. |
psuCorporateId | – | The merchant's business ID. |
phoneNumber | – | The merchant's phone number. |
displayName | – | A display name shown to payers. |
logo | – | A logo for the merchant. |
Request
curl -X POST "https://api.open-finance.ai/v2/merchants" \
-H "Authorization: Bearer <accessToken>" \
-H "Content-Type: application/json" \
-d '{
"name": "Acme Ltd",
"displayName": "Acme",
"iban": "IL620108000000099999999"
}'Response
{ "id": "01J8MERCH..." }Keep the returned id — it is the merchantId you pass to Create a Payment.
List merchants
GET https://api.open-finance.ai/v2/merchants
| Query param | Description |
|---|---|
limit | Max merchants to return (max 500). |
sort | 1 ascending, -1 descending. |
nextPage | Pagination cursor from the previous response. |
curl "https://api.open-finance.ai/v2/merchants?limit=100" \
-H "Authorization: Bearer <accessToken>"Returns { nextPage, items }, where each item is a merchant object.
Get a merchant
GET https://api.open-finance.ai/v2/merchants/{merchantId}
curl "https://api.open-finance.ai/v2/merchants/01J8MERCH..." \
-H "Authorization: Bearer <accessToken>"| Field | Description |
|---|---|
id | The merchant id. |
name / displayName | Name and display name. |
bban / iban | The payee's bank account. |
psuId / psuCorporateId | National / business ID. |
phoneNumber | Contact number. |
logoUrl | URL of the merchant's logo. |
createdAt | Creation timestamp (UTC). |
isDeleted | true if the merchant has been deleted. |
Delete a merchant
DELETE https://api.open-finance.ai/v2/merchants/{merchantId}
curl -X DELETE "https://api.open-finance.ai/v2/merchants/01J8MERCH..." \
-H "Authorization: Bearer <accessToken>"
Attribute a payment to a merchant by settingmerchantIdin the body ofCreate a Payment. See the API Reference for the full merchant object.
Updated 7 days ago