Cuentas beneficiarias

Endpoints para consultar las cuentas beneficiarias (IBANs) registradas para tu negocio.

El alta de la primera cuenta beneficiaria se realiza durante el onboarding y queda configurada automáticamente como cuenta predeterminada de la organización.

Cada cuenta beneficiaria dispone de un identificador único denominado creditorAccountUuid, utilizado para indicar en qué cuenta se recibirán los fondos asociados a una operación.

El creditorAccountUuid puede enviarse opcionalmente durante el registro de operaciones Pagafactu o Zertipay. En caso de no especificarse, Zertiban utilizará automáticamente la cuenta beneficiaria marcada como predeterminada (isDefault=true) para el negocio.

WARNING

Únicamente las cuentas beneficiarias con estado ACTIVE pueden utilizarse para generar nuevas operaciones o recibir pagos.

Listado de cuentas beneficiarias

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

curl "https://nc-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

Parámetro	Tipo	Default	Descripción
offset	int	0	Posición inicial
limit	int	—	Resultados por página
q_status	enum (ACTIVE / DISABLED)	—	Filtra por estado. Sin valor devuelve todas. Enum inválido → 400
q_isDefault	boolean	—	Filtra por si es la cuenta por defecto. Sin valor devuelve todas. Valor no parseable → 400

Comportamiento por defecto

Si no se aplican filtros, el endpoint devuelve todas las cuentas beneficiarias registradas, incluidas aquellas en estado DISABLED.

Respuesta 200

{
  "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://..."
      }
    }
  ]
}

Detalle de cuenta beneficiaria

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

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

Respuesta 200

{
  "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"
  }
}

Campos de la respuesta

Campo	Tipo	Descripción
uuid	UUID	creditorAccountUuid utilizado para asociar operaciones a una cuenta beneficiaria concreta
accountNumber	String	Número de cuenta enmascarado
type	String	Tipo de cuenta. Valor posible: IBAN
alias	String	Nombre identificativo configurado para la cuenta
status	String	Estado de la cuenta (ACTIVE / DISABLED). Solo las cuentas ACTIVE aceptan pagos
isDefault	Boolean	Indica si es la cuenta beneficiaria predeterminada del negocio
aspsp.commercialName	String	Nombre comercial de la entidad bancaria