> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zopay.cash/llms.txt
> Use this file to discover all available pages before exploring further.

# Direct vs. whitelabel flows

> El campo external_ref decide a qué tabla de balance cae el crédito.

Cada llamada de escritura a `/addresses` y `/payment-intents` cae en uno de dos flujos, decidido por si pasas `external_ref`:

|                                          | **Direct flow** (`external_ref` omitido) | **Whitelabel flow** (`external_ref` seteado)                       |
| ---------------------------------------- | ---------------------------------------- | ------------------------------------------------------------------ |
| Quién es el target del crédito           | Tu organización partner                  | Un "partner profile" per-usuario que minteamos al primer contacto  |
| Dónde vive la fila de dirección          | `organization_addresses`                 | `user_addresses` (joineado con tu org vía `connect_external_refs`) |
| Dónde aterriza el crédito                | `organization_assets`                    | `user_assets` del perfil partner                                   |
| Forma de `GET /balances`                 | Agregado por tu org                      | Agregado AND per-usuario al filtrar por `external_ref`             |
| La respuesta hace echo de `external_ref` | No (campo ausente)                       | Sí                                                                 |

## Cuándo usar cada uno

**Direct flow** es lo correcto cuando estás cobrando para ti — tu dashboard, tu contabilidad, sin atribución de usuario final. El depósito acredita el balance de tu org igual que un depósito vía ui-web o WhatsApp.

**Whitelabel flow** es lo correcto cuando operas un producto multi-tenant y necesitas atribución per-usuario — suministra tu id estable de usuario como `external_ref` y trackeamos el balance, direcciones, y transacciones de ese usuario por separado. Al primer contacto con un `external_ref`, minteamos perezosamente un perfil partner-usuario interno; llamadas subsiguientes con el mismo `external_ref` convergen al mismo perfil (idempotente sobre `(organization_id, external_ref)`).

## Coexisten en la misma clave

Los dos flujos pueden coexistir bajo la misma clave — pasa `external_ref` en las llamadas donde la atribución importa y omítelo donde no. `GET /balances` devuelve la unión (org-level + cada partner-usuario) para que veas un solo número que es verdad para todo el tenant.

## Ejemplos

### Direct — cobrando para ti mismo

```bash theme={null}
curl -X POST "https://api.zopay.cash/connect/v1/payment-intents" \
  -H "Authorization: Bearer $SK" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "amount": "100.00", "currencies": ["USDT"] }'
# Sin external_ref. El crédito cae en organization_assets.
```

### Whitelabel — cobrando para tu usuario `user_42`

```bash theme={null}
curl -X POST "https://api.zopay.cash/connect/v1/payment-intents" \
  -H "Authorization: Bearer $SK" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "amount": "100.00", "currencies": ["USDT"], "external_ref": "user_42" }'
# Con external_ref. El crédito cae en user_assets para el perfil de user_42.
```

```bash theme={null}
# Balance del usuario:
curl "https://api.zopay.cash/connect/v1/balances/user_42" \
  -H "Authorization: Bearer $SK"

# Balance total del tenant (org + todos los perfiles partner-usuario):
curl "https://api.zopay.cash/connect/v1/balances" \
  -H "Authorization: Bearer $SK"
```

## Ver también

* [`POST /addresses`](/api-reference/endpoints/post-addresses)
* [`POST /payment-intents`](/api-reference/endpoints/post-payment-intents)
* [`GET /balances`](/api-reference/endpoints/get-balances)
* [`GET /balances/{external_ref}`](/api-reference/endpoints/get-balances-by-external-ref)