Direct vs. whitelabel flows

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

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`

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.

# 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"

Comenzando

Payment Intents

Addresses

Balances

Transactions

Payouts

Capabilities

Health

Events

Sandbox (test helpers)

Conversions (coming soon)

Ramps (coming soon)

Webhooks (coming soon)

Direct vs. whitelabel flows

Cuándo usar cada uno

Coexisten en la misma clave

Ejemplos

Direct — cobrando para ti mismo

Whitelabel — cobrando para tu usuario `user_42`

Ver también

​Cuándo usar cada uno

​Coexisten en la misma clave

​Ejemplos

​Direct — cobrando para ti mismo

​Whitelabel — cobrando para tu usuario user_42

​Ver también

Cuándo usar cada uno

Coexisten en la misma clave

Ejemplos

Direct — cobrando para ti mismo

Whitelabel — cobrando para tu usuario `user_42`

Ver también