Reference · Payees
Create a payee
POST
https://api.paygoro.com/v1/payeesSaves a beneficiary. The IBAN is checksum-validated and normalized; one payee per IBAN per company.
Authorization
Requires a bearer API key with payees:write. See Authentication.
Request body
application/json
| Field | Type | Description |
|---|---|---|
companyId | string | Required when the workspace has more than one legal entity. |
namerequired | string | max 70 chars |
ibanrequired | string | Any formatting; validated and normalized server-side.max 42 chars |
defaultReference | string | Default SEPA remittance reference (1–35 characters from the SEPA character set). |
Response
201 · application/json
| Field | Type | Description |
|---|---|---|
id | string | Opaque resource id. |
companyId | string | Opaque resource id. |
name | string | max 70 chars |
iban | string | Normalized IBAN (uppercase, no spaces). |
defaultReference | string | null | |
lastUsedAt | string (date-time) | null | When a transfer to this payee was last initiated. |
createdAt | string (date-time) | Timestamp in RFC 3339 format (UTC). |
updatedAt | string (date-time) | Timestamp in RFC 3339 format (UTC). |
Errors
| 400 | BAD_REQUEST | The request was malformed or failed validation. |
| 401 | UNAUTHORIZED | Missing, malformed, expired or revoked API key. |
| 403 | FORBIDDEN | The API key does not have the scope this operation requires. |
| 404 | NOT_FOUND | No resource with this id exists in your workspace, or a `companyId` filter does not match one of your companies. |
| 409 | CONFLICT | A payee with this IBAN already exists for the company. |
| 429 | TOO_MANY_REQUESTS | Rate limit exceeded. Retry after the `Retry-After` header. |
All errors share one envelope — see Errors.