Flow configuration

Endpoints to query the flow configurations created from the Zertiban Dashboard. A flow configuration defines the functional and visual behaviour the end user will experience when accessing a payment operation.

These configurations centralise aspects such as the flow's visual identity (logo, colours, language), operational rules (expiration, rejection allowed) and the redirections and callbacks used to synchronise the final operation state with the client's systems.

Every organisation automatically has a default configuration created during onboarding. However, the platform allows you to create multiple configurations to adapt to different use cases, brands, verticals or operational behaviours depending on integration needs.

Configurations can optionally be referenced when registering operations through their configurationUuid. If no configuration is specified in the API request, Zertiban will automatically use the configuration marked as default (isDefault=true) for the business.

Only configurations with status ACTIVE can be used to generate new payment flows.

TIP

For details on every field configurable from the Dashboard, see "Getting started > Post-Onboarding" in Introduction.

List

GET/flow-customization/v1/configurations

curl "https://nc-api-sandbox.zertiban.com/flow-customization/v1/configurations?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	10	Results per page
q_isDefault	boolean	—	true returns only the default one; false only the non-default ones; omitted returns all
q_status	enum (ACTIVE / DISABLED)	—	Filters by configuration status. Omitted returns all

Default behaviour

With no filters, the list returns all configurations, including those in DISABLED status.

200 response

{
  "total": 3,
  "results": [
    {
      "uuid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "name": "Cobros estandar 30d",
      "description": "Configuracion principal con caducidad de 30 dias",
      "createdAt": "2026-01-15T10:00:00Z",
      "isDefault": true,
      "status": "ACTIVE"
    }
  ]
}

Detail

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

Returns the full configuration including appearance, behaviour and redirection.

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

200 response

{
  "name": "Cobros estandar 30d",
  "description": "Configuracion principal",
  "isDefault": true,
  "status": "ACTIVE",
  "visualConfiguration": {
    "targetValues": [
      {
        "applicationTarget": "WEB_APP",
        "properties": {
          "icon": "https://tuapp.com/favicon.ico",
          "logo": "https://tuapp.com/logo.png",
          "brandColor": "#003366",
          "accentColor": "#FF9900",
          "language": "es"
        }
      }
    ]
  },
  "operationConfiguration": {
    "operationConfiguration": {
      "rejectAllowed": false,
      "expirationOffset": "P30D"
    },
    "redirection": {
      "callback": {
        "url": "https://tuapp.com/pago-completado",
        "requestTimeout": 3,
        "parameters": ["operationId", "operationStatus", "operationResult", "externalOperationId"]
      },
      "return": {
        "url": "https://tuapp.com/pago-cancelado",
        "parameters": ["operationId", "externalOperationId"]
      }
    }
  }
}

Root-level fields

Field	Type	Description
isDefault	Boolean	Whether this configuration is the business's default one
status	String	ACTIVE or DISABLED. Only ACTIVE ones can be used when creating flows

Main fields of operationConfiguration

Field	Type	Description
operationConfiguration.rejectAllowed	Boolean	If true, the payer can reject the operation on the payment page
operationConfiguration.expirationOffset	String	Duration until expiry in ISO 8601 format (e.g. "P30D")
redirection.callback.url	String	URL the payer's browser is redirected to when a final state is reached
redirection.callback.requestTimeout	Long	Seconds the page waits before automatically redirecting
redirection.callback.parameters	Array	Dynamic parameters appended as query string to the callback URL
redirection.return.url	String	URL of the exit button. If not configured, the exit button does not appear
redirection.return.parameters	Array	Dynamic parameters appended to the return URL

Available dynamic parameters

For callback and return:

Value	Available in	Description
flowId	callback return	Flow UUID
externalFlowId	callback return	Your flow externalId
operationId	callback return	Operation UUID
externalOperationId	callback return	Your operation externalId
language	callback return	Payer session language
operationStatus	callback only	Final status of the operation
operationResult	callback only	OK if COMPLETED; KO if REJECTED, EXPIRED or CANCELLED
flowStatus	callback only	Final flow status
flowResult	callback only	OK if COMPLETED; KO in the other final states