Beneficiary accounts

Endpoints to query the beneficiary accounts (IBANs) registered for your organisation.

The first beneficiary account is registered during onboarding and is automatically configured as the organisation's default account.

Each beneficiary account has a unique identifier called creditorAccountUuid, used to indicate which account will receive the funds associated with an operation.

The creditorAccountUuid can optionally be sent when registering Pagafactu or Zertipay operations. If not specified, Zertiban will automatically use the beneficiary account flagged as default (isDefault=true) for the organisation.

WARNING

Only beneficiary accounts in ACTIVE status can be used to generate new operations or receive payments.

List beneficiary accounts

GET/business-creditor-account/v1/business-creditor-accounts

curl "https://api-sandbox.zertiban.com/business-creditor-account/v1/business-creditor-accounts?offset=0&limit=10" \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {businessUuid}"

Query parameters

Parameter	Type	Default	Description
offset	int	0	Starting position
limit	int	—	Results per page
q_status	enum (ACTIVE / DISABLED)	—	Filters by status. Omitted returns all. Invalid enum → 400
q_isDefault	boolean	—	Filters by whether the account is the default. Omitted returns all. Unparseable value → 400

Default behaviour

If no filters are applied, the endpoint returns all registered beneficiary accounts, including those in DISABLED status.

200 response

{
  "total": 2,
  "results": [
    {
      "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "accountNumber": "ES91 2100 0418 ***** 4567",
      "type": "IBAN",
      "alias": "Cuenta principal cobros",
      "status": "ACTIVE",
      "isDefault": true,
      "aspsp": {
        "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "commercialName": "CaixaBank",
        "icon": "https://..."
      }
    }
  ]
}

Beneficiary account detail

GET/business-creditor-account/v1/business-creditor-accounts/{uuid}

curl "https://api-sandbox.zertiban.com/business-creditor-account/v1/business-creditor-accounts/{uuid}" \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {businessUuid}"

200 response

{
  "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "accountNumber": "ES91 2100 0418 ***** 4567",
  "type": "IBAN",
  "alias": "Cuenta principal cobros",
  "status": "ACTIVE",
  "isDefault": true,
  "aspsp": {
    "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "commercialName": "CaixaBank"
  }
}

Response fields

Field	Type	Description
uuid	UUID	creditorAccountUuid used to associate operations with a specific beneficiary account
accountNumber	String	Masked account number
type	String	Account type. Possible value: IBAN
alias	String	Identifying name configured for the account
status	String	Account status (ACTIVE / DISABLED). Only ACTIVE accounts accept payments
isDefault	Boolean	Indicates whether this is the organisation's default beneficiary account
aspsp.commercialName	String	Commercial name of the banking entity