Skip to content
Developer Docs

Business endpoints ​

Shared catalog of endpoints used by both PagaFactu and ZertiPay to manage flows, operations, PSD2 payments, beneficiary accounts and configurations.

This page groups the 18 common endpoints used by both PagaFactu and ZertiPay. The only product-specific endpoint is the PagaFactu flow creation (POST/flow/v1/flows/pagafactu), documented on the PagaFactu implementation page.

Common conventions ​

  • Sandbox base URL: https://api-sandbox.zertiban.com
  • Required headers on every call:
    • Authorization: Bearer {access_token}
    • x-tenant-id: {businessUuid}

Flows ​

1. Create flow ​

POST/flow/v1/flows

Content-Type: multipart/form-data. The payload part must carry Content-Type: application/json; otherwise the server returns 400. For PagaFactu collections there is a dedicated POST/flow/v1/flows/pagafactu endpoint, documented on its implementation page.

shell
curl -X POST https://api-sandbox.zertiban.com/flow/v1/flows \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {businessUuid}" \
  -F 'payload={ "externalId": "...", "countryCode": "ES", "operations": [...] };type=application/json'

Payload root:

FieldTypeReq.Description
externalIdStringNoYour flow ID
countryCodeStringYesISO 3166 (e.g. "ES")
additionalLanguageStringNoISO 639-1
operationsArrayYes1 operation
documentsArrayNoAttached PDFs (up to 10)
labelsArrayNoKey-value labels

Response (201):

FieldDescription
uuidFlow UUID
externalIdYour externalId
operations[i].uuidOperation UUID
operations[i].externalIdYour operation externalId
operations[i].idThe local id you sent
operations[i].urlPayment link for the payer

2. List flows ​

GET/flow/v1/flows

shell
# Flows completed in the last 7 days
curl "https://api-sandbox.zertiban.com/flow/v1/flows?q_status=COMPLETED&q_fromCreatedAt=2026-04-15T00:00:00Z&sort_by=STATUS_UPDATED_AT&sort_dir=DESC" \
  -H "Authorization: Bearer {access_token}" -H "x-tenant-id: {businessUuid}"

Query parameters:

ParameterTypeDefaultDescription
q_uuidUUID—Filter by flow UUID
q_externalIdString—Filter by externalId
q_statusCSV—Flow statuses
q_productLabelValueCSV—Filter by product label value
q_fromCreatedAt / q_toCreatedAtISO-8601 Instant—Creation range
q_fromStatusUpdatedAt / q_toStatusUpdatedAtISO-8601 Instant—Status change range
q_originEnum—Filter by flow origin: DIRECT (direct, no Partner/Agent) or COLLABORATOR (originated by a Partner/Agent). Case-insensitive.
q_collaboratorUuidUUID—Only flows originated by that specific Partner/Agent (exact match).
q_collaboratorLegalNameString—Only flows whose Partner/Agent legal name contains the value (substring, case-insensitive).
offsetint0Starting position
limitint10Results per page (max 100)
sort_byStringCREATED_ATEXTERNAL_ID, STATUS, CREATED_AT, STATUS_UPDATED_AT
sort_dirStringDESCASC or DESC

Incompatible combinations

q_origin=DIRECT cannot be combined with q_collaboratorUuid or q_collaboratorLegalName. The combination returns 400 INVALID_PARAMETER.

Response (200):

json
{
  "total": 150,
  "results": [
    {
      "uuid": "28ffd216-...",
      "externalId": "COLLECTION-2026-001",
      "status": "COMPLETED",
      "createdAt": "2026-04-22T09:00:00Z",
      "statusUpdatedAt": "2026-04-22T09:15:00Z",
      "operationsCount": 1,
      "labels": [{ "name": "order", "value": "12345" }],
      "collaborator": {
        "uuid": "f7c1a2b3-4d5e-6f70-8192-a3b4c5d6e7f8",
        "legalName": "Perez Advisory Ltd"
      }
    },
    {
      "uuid": "3fa85f64-...",
      "externalId": "COLLECTION-2026-002",
      "status": "IN_PROGRESS",
      "createdAt": "2026-04-23T10:00:00Z",
      "statusUpdatedAt": "2026-04-23T10:05:00Z",
      "operationsCount": 1,
      "labels": [],
      "collaborator": null
    }
  ]
}

The collaborator block identifies the Partner/Agent that originated the flow. It is null or absent when the flow was created directly by the organisation itself, with no Partner/Agent. It is an immutable snapshot captured at flow creation.

3. Flow detail ​

GET/flow/v1/flows/{flowUuid}

Returns the flow with a summary of its payment operations.

shell
curl https://api-sandbox.zertiban.com/flow/v1/flows/{flowUuid} \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {businessUuid}"

Response (200):

json
{
  "uuid": "28ffd216-5ee8-4e99-b1a9-511961e9c655",
  "externalId": "COLLECTION-2026-001",
  "status": "COMPLETED",
  "countryCode": "ES",
  "languageCode": "ES",
  "createdAt": "2026-04-22T09:00:00Z",
  "labels": [{ "name": "order", "value": "12345" }],
  "paymentOperations": [
    {
      "uuid": "d1faff9e-...",
      "externalId": "OP-2026-001",
      "status": "COMPLETED",
      "statusUpdatedAt": "2026-04-22T09:15:00Z",
      "expiresAt": "2026-05-22T09:00:00Z",
      "amount": 15075,
      "currency": "EUR"
    }
  ],
  "collaborator": {
    "uuid": "f7c1a2b3-4d5e-6f70-8192-a3b4c5d6e7f8",
    "legalName": "Perez Advisory Ltd"
  }
}
FieldDescription
statusFlow status (CREATED, IN_PROGRESS, COMPLETED, REJECTED, EXPIRED, CANCELLED)
paymentOperations[i].amountAmount in cents
labelsKey-value labels sent when creating the flow
collaboratorPartner/Agent that originated the flow, with uuid and legalName (legal name snapshotted at creation). null or absent ⇒ direct flow, no Partner/Agent.

4. Flow status history ​

GET/flow/v1/flows/{flowUuid}/status-histories

shell
curl https://api-sandbox.zertiban.com/flow/v1/flows/{flowUuid}/status-histories \
  -H "Authorization: Bearer {access_token}" -H "x-tenant-id: {businessUuid}"

Response (200): Array sorted chronologically.

json
[
  { "previousStatus": null, "newStatus": "IN_PROGRESS", "changedAt": "2026-04-22T09:10:00Z" },
  { "previousStatus": "IN_PROGRESS", "newStatus": "COMPLETED", "changedAt": "2026-04-22T09:15:00Z" }
]

5. Flow statistics ​

GET/flow/v1/flows/statistics

shell
curl "https://api-sandbox.zertiban.com/flow/v1/flows/statistics?q_fromCreatedAt=2026-04-01T00:00:00Z" \
  -H "Authorization: Bearer {access_token}" -H "x-tenant-id: {businessUuid}"

Accepts the same filters as GET/flow/v1/flows (without pagination).

Response (200):

json
{
  "summary": { "totalFlows": 42 },
  "groups": [
    { "key": "COMPLETED", "metrics": { "count": 38 } },
    { "key": "EXPIRED", "metrics": { "count": 3 } },
    { "key": "CANCELLED", "metrics": { "count": 1 } }
  ]
}

Operations ​

6. List operations ​

GET/flow/v1/operations

shell
# Completed operations of a specific flow
curl "https://api-sandbox.zertiban.com/flow/v1/operations?q_flowUuid={flowUuid}&q_status=COMPLETED" \
  -H "Authorization: Bearer {access_token}" -H "x-tenant-id: {businessUuid}"

Query parameters:

ParameterTypeDefaultDescription
q_operationUuidUUID—Filter by operation UUID
q_flowUuidUUID—Filter by parent flow UUID
q_externalIdString—Filter by operation externalId
q_statusCSV—Statuses: CREATED, OPENED, COMPLETED, REJECTED, EXPIRED, CANCELLED
q_typeCSV—Operation type (PAYMENT, SIGNATURE)
q_invoiceExternalIdString—Filter by invoice externalId
q_fromCreatedAtISO-8601 Instant—Created from
q_toCreatedAtISO-8601 Instant—Created to
q_fromStatusUpdatedAtISO-8601 Instant—Last status change from
q_toStatusUpdatedAtISO-8601 Instant—Last status change to
q_amountFromLong—Minimum amount (cents)
q_amountToLong—Maximum amount (cents)
q_originEnum—Filter by the owning flow's origin: DIRECT (no Partner/Agent) or COLLABORATOR (originated by a Partner/Agent). Case-insensitive.
q_collaboratorUuidUUID—Only operations whose owning flow was originated by that specific Partner/Agent (exact match).
q_collaboratorLegalNameString—Only operations whose owning flow's Partner/Agent legal name contains the value (substring, case-insensitive).
offsetint0Starting position
limitint10Results per page (max 100)
sort_byStringCREATED_ATEXTERNAL_ID, STATUS, CREATED_AT, STATUS_UPDATED_AT
sort_dirStringDESCASC or DESC

Incompatible combinations

q_origin=DIRECT cannot be combined with q_collaboratorUuid or q_collaboratorLegalName. The combination returns 400 INVALID_PARAMETER.

Response (200):

json
{
  "total": 42,
  "results": [
    {
      "uuid": "d1faff9e-...",
      "externalId": "OP-2026-001",
      "status": "COMPLETED",
      "type": "PAYMENT",
      "createdAt": "2026-04-22T09:00:00Z",
      "statusUpdatedAt": "2026-04-22T09:15:00Z",
      "flow": {
        "uuid": "28ffd216-...",
        "collaborator": {
          "uuid": "f7c1a2b3-4d5e-6f70-8192-a3b4c5d6e7f8",
          "legalName": "Perez Advisory Ltd"
        }
      }
    },
    {
      "uuid": "a2b3c4d5-...",
      "externalId": null,
      "status": "CREATED",
      "type": "SIGNATURE",
      "createdAt": "2026-04-23T08:22:00Z",
      "statusUpdatedAt": null,
      "flow": {
        "uuid": "3fa85f64-...",
        "collaborator": null
      }
    }
  ]
}

The Partner/Agent attribution is inherited from the owning flow and exposed under flow.collaborator in each item. null or absent ⇒ operation belongs to a direct flow.

7. Operation detail ​

GET/flow/v1/operations/{uuid}

Returns all operation data, including PSD2 payment details and the paymentUuid you need to fetch the payment detail once completed.

shell
curl https://api-sandbox.zertiban.com/flow/v1/operations/{operationUuid} \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {businessUuid}"

Response (200):

json
{
  "uuid": "d1faff9e-bb8b-47bd-8b47-4f20f1a7912b",
  "externalId": "OP-2026-001",
  "flowUuid": "28ffd216-5ee8-4e99-b1a9-511961e9c655",
  "configurationUuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "status": "COMPLETED",
  "type": "PAYMENT",
  "expirationOffset": "P30D",
  "expiresAt": "2026-05-22T09:00:00Z",
  "createdAt": "2026-04-22T09:00:00Z",
  "synchronous": true,
  "payment": {
    "paymentUuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "amount": 15075,
    "currency": "EUR",
    "concept": "Collection 2026-001",
    "types": ["PSD2_PAYMENT"],
    "psd2Payment": {
      "type": "SINGLE_PAYMENT",
      "product": "SEPA_CREDIT_TRANSFER",
      "creditorAccount": { "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" }
    },
    "subject": { "name": "Ana", "lastName": "Martinez", "email": "[email protected]" }
  },
  "flow": {
    "uuid": "28ffd216-5ee8-4e99-b1a9-511961e9c655",
    "collaborator": {
      "uuid": "f7c1a2b3-4d5e-6f70-8192-a3b4c5d6e7f8",
      "legalName": "Perez Advisory Ltd"
    }
  }
}
FieldDescription
payment.paymentUuidPSD2 payment UUID. Available once status is COMPLETED. Use it to call GET/payment/v1/payments/{uuid}.
payment.amountAmount in cents.
payment.subjectDebtor data as sent when creating the flow.
expiresAtOperation expiration date.
flow.collaboratorOwning flow's Partner/Agent, with uuid and legalName (legal name snapshotted at creation). Absent or null when the operation belongs to a direct flow.

8. Quick operation status ​

GET/flow/v1/operations/{operationUuid}/status

Returns the operation's current status with a minimal payload. Ideal for frequent polling when you don't need the full object.

shell
curl https://api-sandbox.zertiban.com/flow/v1/operations/{operationUuid}/status \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {businessUuid}"

Response (200):

json
{
  "status": "COMPLETED",
  "actionCode": "INITIATED",
  "final": true
}
FieldTypeDescription
statusStringCurrent status: CREATED, OPENED, COMPLETED, REJECTED, EXPIRED, CANCELLED.
actionCodeStringPlatform-internal action code.
finalbooleantrue when the state is terminal (no further transitions possible).

9. Operation status history ​

GET/flow/v1/operations/{uuid}/status-histories

Returns the full sequence of state transitions, useful for auditing the lifecycle of a collection.

shell
curl https://api-sandbox.zertiban.com/flow/v1/operations/{operationUuid}/status-histories \
  -H "Authorization: Bearer {access_token}" -H "x-tenant-id: {businessUuid}"

Response (200): Array sorted chronologically.

json
[
  { "previousStatus": null, "newStatus": "CREATED", "changedAt": "2026-04-22T09:00:00Z" },
  { "previousStatus": "CREATED", "newStatus": "OPENED", "changedAt": "2026-04-22T09:10:00Z" },
  { "previousStatus": "OPENED", "newStatus": "COMPLETED", "changedAt": "2026-04-22T09:15:00Z" }
]
FieldTypeDescription
previousStatusStringPrevious status (null for the initial state).
newStatusStringNew status.
changedAtInstantMoment of the transition.

10. Operation statistics ​

GET/flow/v1/operations/statistics

Returns aggregated metrics: total operations and amount totals, with the same filters as the listing.

shell
# Total collected and per-status breakdown for the last month
curl "https://api-sandbox.zertiban.com/flow/v1/operations/statistics?q_fromCreatedAt=2026-03-22T00:00:00Z" \
  -H "Authorization: Bearer {access_token}" -H "x-tenant-id: {businessUuid}"

Accepts the same filter query parameters as GET/flow/v1/operations (without offset, limit, sort_by, sort_dir).

Response (200):

json
{
  "summary": { "total": 42 },
  "groups": [
    { "key": "COMPLETED", "metrics": { "count": 38, "amount": 578450 } },
    { "key": "EXPIRED", "metrics": { "count": 3, "amount": 45000 } },
    { "key": "CANCELLED", "metrics": { "count": 1, "amount": 15075 } }
  ]
}
FieldDescription
summary.totalTotal operations matching the filters.
groups[i].keyGrouper value (operation status).
groups[i].metrics.countNumber of operations in this group.
groups[i].metrics.amountSum of amounts in cents in this group.

11. Cancel operation ​

PUT/flow/v1/operations/{operationUuid}/cancel

Cancels an operation that has not yet reached a final state.

shell
curl -X PUT https://api-sandbox.zertiban.com/flow/v1/operations/{operationUuid}/cancel \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {businessUuid}"

No body in the request.

Successful response: 204 No Content

CodeCause
409The operation is already in a final state (COMPLETED, REJECTED, EXPIRED, CANCELLED).
409The operation is in OPENED and the payer has a payment in progress (pending transaction).

If the flow had this operation as the only active one, the flow will also become CANCELLED.

12. Extend operation expiration ​

PATCH/flow/v1/operations/{operationUuid}/expiration

Recomputes the operation's expiration by adding the given duration to the call time (expiresAt = now + duration).

shell
curl -X PATCH https://api-sandbox.zertiban.com/flow/v1/operations/{operationUuid}/expiration \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {businessUuid}" \
  -H "Content-Type: application/json" \
  -d '{ "duration": "P7D" }'

Request body:

FieldTypeDescription
durationStringISO 8601 duration in days only (e.g. "P7D" = 7 days, "P30D" = 30 days). Only the D designator is supported.

Successful response: 204 No Content

Restrictions:

  • The operation must be in a non-final state (CREATED or OPENED).
  • Minimum duration is 1 day (P1D).
  • The duration field only accepts the day designator (D). Hours (H) and minutes are not allowed.

13. Download attached payment document ​

GET/flow/v1/operations/{operationUuid}/payment-documents/{paymentDocumentUuid}/content

Downloads the binary content of a PDF document attached when creating the flow. The documentUuid comes from the payment.documents array in the operation detail.

shell
curl https://api-sandbox.zertiban.com/flow/v1/operations/{operationUuid}/payment-documents/{documentUuid}/content \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {businessUuid}" \
  -o document.pdf

Response: application/pdf binary with the header Content-Disposition: attachment; filename="<file-name>". If no name is available, the server uses payment-document.pdf.

PSD2 payment ​

14. PSD2 payment detail ​

GET/payment/v1/payments/{uuid}

The paymentUuid is available in GET/flow/v1/operations/{uuid} → field payment.paymentUuid, once the operation reaches the COMPLETED state.

shell
curl https://api-sandbox.zertiban.com/payment/v1/payments/{paymentUuid} \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {businessUuid}"

Response (200):

json
{
  "psd2Payment": {
    "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "status": { "code": "ACSC", "status": "AcceptedSettlementCompleted" },
    "instructedAmount": { "amount": 15075, "currency": "EUR" },
    "remittanceInformationUnstructured": "Collection 2026-001",
    "executionDate": "2026-04-22T09:14:00Z",
    "requestedExecutionDate": null,
    "bankPaymentId": "BANKA12345678",
    "creditorAccount": {
      "ownerName": "My Company Ltd.",
      "accountNumber": "ES91210004183401234567",
      "bic": "CAIXESBBXXX",
      "country": "ES",
      "type": "IBAN"
    },
    "debtorAccount": {
      "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "accountNumber": "ES8020484097908424975543",
      "type": "IBAN",
      "currency": "EUR",
      "psuName": "Ana Martinez",
      "ownerName": "Ana Martinez",
      "bic": "BBVAESMMXXX"
    }
  },
  "collaborator": {
    "uuid": "f7c1a2b3-4d5e-6f70-8192-a3b4c5d6e7f8"
  }
}
FieldDescription
psd2Payment.status.codeISO 20022 code of the payment status (e.g. ACSC = settled).
psd2Payment.instructedAmountExact amount that was moved.
psd2Payment.remittanceInformationUnstructuredPayment concept / reference.
psd2Payment.executionDateWhen the bank processed the payment.
psd2Payment.requestedExecutionDateOnly present for scheduled payments (FUTURE_PAYMENT).
psd2Payment.bankPaymentIdBank-assigned payment identifier.
psd2Payment.creditorAccountBeneficiary account that received the money.
psd2Payment.debtorAccountPayer account that issued the transfer.
collaborator.uuidUUID of the Partner/Agent that originated the flow this payment belongs to. Attribution inherited immutably at payment creation. Unlike flow-service, the legal name is not exposed here; if you need it, fetch it from the flow or operation detail. The collaborator block is null or absent for payments originated directly.

Beneficiary accounts ​

Detailed field and filter documentation in Beneficiary accounts.

15. List beneficiary accounts ​

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

shell
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}"
ParameterTypeDefaultDescription
offsetint0Starting position
limitint—Results per page
q_statusenum (ACTIVE / DISABLED)—Filter by status. No value returns all.
q_isDefaultboolean—Filter by whether it's the default account.

16. Beneficiary account detail ​

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

shell
curl "https://api-sandbox.zertiban.com/business-creditor-account/v1/business-creditor-accounts/{uuid}" \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {businessUuid}"
FieldTypeDescription
uuidUUIDcreditorAccountUuid to use when creating flows
accountNumberStringAccount number (masked)
typeStringAccount type. Possible value: IBAN
aliasStringIdentifying name
statusStringACTIVE or DISABLED. Only ACTIVE accept payments.
isDefaultBooleanWhether it's the organisation's default beneficiary account
aspsp.commercialNameStringBank commercial name

Flow configurations ​

Detailed field and filter documentation in Flow configuration.

17. List configurations ​

GET/flow-customization/v1/configurations

shell
curl "https://api-sandbox.zertiban.com/flow-customization/v1/configurations?offset=0&limit=10" \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {businessUuid}"

18. Configuration detail ​

GET/flow-customization/v1/configurations/{configurationUuid}

shell
curl https://api-sandbox.zertiban.com/flow-customization/v1/configurations/{configurationUuid} \
  -H "Authorization: Bearer {access_token}" \
  -H "x-tenant-id: {businessUuid}"

Summary table ​

Sandbox base URL: https://api-sandbox.zertiban.com

Common errors ​

CodeTypical causeSolution
400Invalid payload: missing field, wrong format, mistyped parameterReview the validation in the reference section
401Expired token or invalid credentialsRequest a new token with Basic Auth
403Wrong x-tenant-id or insufficient credential permissionsVerify businessUuid and credential permissions
404Configuration, account, operation, flow or payment UUID not foundVerify with the GET endpoints
409State conflict (cancel finished operation, inactive configuration)Check the current status before the action