Skip to main content
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éditoTu organización partnerUn “partner profile” per-usuario que minteamos al primer contacto
Dónde vive la fila de direcciónorganization_addressesuser_addresses (joineado con tu org vía connect_external_refs)
Dónde aterriza el créditoorganization_assetsuser_assets del perfil partner
Forma de GET /balancesAgregado por tu orgAgregado AND per-usuario al filtrar por external_ref
La respuesta hace echo de external_refNo (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"

​
Ver también