Primeros pasos

El flujo completo de integración con la API de partners de SLAN, de verificar la llave a ver quién pagó un link de cobro.

Una integración completa son seis llamadas. Este es el camino, en orden.

1. GET  /v1/partner/ping                            Verificar que la llave funciona
2. POST /v1/partner/users                           Dar de alta un usuario final
3. POST /v1/partner/wallets                         Crear su wallet de cobro
4. POST /v1/partner/payment-links                   Generar un link de pago
5. GET  /v1/partner/payment-links/:id/payments      Ver quién pagó
6. POST /v1/partner/payment-links/:id/cancel        Cancelar un link

1 · Verifica la llave

curl https://api.slan.mx/v1/partner/ping \
  -H "x-api-key: slan_..."

Un 200 confirma que la credencial es válida y está vigente. Un 401 significa que falta la cabecera, o que la llave no existe, expiró o fue revocada.

GET /v1/partner/me va un paso más allá y te dice qué scopes tienes concedidos. Es el primer sitio donde mirar cuando un endpoint responde 403.

2 · Da de alta un usuario final

curl -X POST https://api.slan.mx/v1/partner/users \
  -H "x-api-key: slan_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f1c9c3e-7c1a-4a2e-9a1e-2f0b6d5c4a31" \
  -d '{"email":"ana.ramirez@example.com","firstName":"Ana","lastName":"Ramírez","externalRef":"tripto-user-4821"}'

No lleva contraseña, y no es un olvido. En SLAN no existen las contraseñas: el acceso a la aplicación es solo con un proveedor de identidad. El usuario que das de alta nace en estado PARTNER_MANAGED, que significa exactamente esto: existe como titular de una wallet y como destinatario de cobros, pero no puede entrar a la aplicación de SLAN, no tiene expediente KYC y no tiene cuenta de dinero.

Dos comportamientos que conviene conocer:

externalRef hace idempotente tu alta. Si reintentas con el mismo externalRef, te devolvemos el usuario que ya existe en vez de crear otro. Es único por partner.
Un correo que ya pertenece a una cuenta de SLAN se rechaza con 409 PARTNER_END_USER_EMAIL_TAKEN, y no se crea nada. No lo vinculamos: hacerlo te daría acceso a un cliente de SLAN con su expediente, sus tarjetas y su saldo. Si ese caso te aparece a menudo, hablémoslo.

3 · Crea su wallet de cobro

curl -X POST https://api.slan.mx/v1/partner/wallets \
  -H "x-api-key: slan_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8c2d1b4a-3e5f-4d6a-8b9c-1a2b3c4d5e6f" \
  -d '{"userPublicId":"01JKX7PEND0000000000000036"}'

La cadena, la red y el proveedor los fija el servidor (Crossmint, EVM sobre Base). Una wallet en una red a la que no sabemos liquidar sería un cobro perdido, así que no es configurable.

Un usuario tiene como máximo una wallet de cobro. Si la pides otra vez te devolvemos la que ya existe; no necesitas llevar control de si la creaste.

4 · Genera un link de pago

curl -X POST https://api.slan.mx/v1/partner/payment-links \
  -H "x-api-key: slan_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 2a7e4f11-9b3c-4d8e-a1f2-6c5b4a39e8d7" \
  -d '{"walletPublicId":"01JKX7MNDR0000000000000037","amount":"500.00","concept":"Servicio fotográfico"}'

El link se asocia a una wallet, que debe ser de un usuario tuyo y estar ACTIVE. El importe siempre es en MXN.

La respuesta trae un shareUrl que puedes mandar por WhatsApp, por correo o convertir en un código QR.

Quién puede pagarlo:

Pagador externo: cualquier persona con tarjeta. Abre la URL y paga en un checkout alojado por Clip. Los datos de la tarjeta los captura Clip, nunca nosotros.
Pagador de SLAN: un usuario de la aplicación. Abre la URL en la app y paga desde su saldo como transferencia interna.

5 · Mira quién pagó

curl https://api.slan.mx/v1/partner/payment-links/01JKX7CBRP0000000000000024/payments \
  -H "x-api-key: slan_..."

Para cada pago recibes:

Campo	Qué es
`payerType`	`EXTERNAL` (tarjeta) o `SLAN_USER` (saldo de SLAN)
`payerEmail`, `payerName`	Datos del pagador
`cardBrand`, `cardBin`, `cardLastFour`	Datos de la tarjeta, solo en pagadores externos
`amount`, `status`, `paidAt`	Importe, estado y momento del cobro

6 · Cancela un link

curl -X POST https://api.slan.mx/v1/partner/payment-links/01JKX7CBRP0000000000000024/cancel \
  -H "x-api-key: slan_..."

Los pagos ya completados no se ven afectados. Un pagador que intente abrir un link cancelado verá «no encontrado».

Y ahora

Antes de llevar esto a producción, lee Idempotencia y Errores: son las dos cosas que más problemas dan en una integración real.