Crear wallet de cobro

POST/v1/partner/walletswallets:write

Genera la wallet de cobro de un usuario del partner. Idempotente: si ya tiene wallet, devuelve la que hay. Exige Idempotency-Key.

Propósito

Crea una wallet de cobro (blockchain Base, proveedor Crossmint) para un usuario que ya diste de alta con POST /users. La wallet es donde se reciben los pagos de los links de pago.

Flujo recomendado

Crea el usuario → POST /users
Crea su wallet → este endpoint
Genera links de pago → POST /payment-links

Campos del request

Campo	Tipo	Requerido	Descripción
`userPublicId`	string (ULID)	✅	El `publicId` del usuario devuelto por `POST /users`.

Comportamiento especial

Idempotente por diseño: un usuario tiene como máximo una wallet de cobro. Si llamas de nuevo, devolvemos la existente sin crear otra.
status: PENDING no es un error. Significa que el proveedor (Crossmint) no respondió a tiempo. Un proceso automático reintenta cada 15 minutos hasta resolverla. No la crees de nuevo.
address: null aparece cuando status es PENDING. Una vez resuelta, la dirección se llena automáticamente.

Errores comunes

Código	Error	Causa	Solución
`404`	`WALLET_OWNER_NOT_FOUND`	El usuario no existe o no es tuyo	Verifica el `userPublicId`
`409`	`WALLET_PROVISION_UNCONFIRMED`	Proveedor no confirmó (queda PENDING)	Espera — se resuelve automáticamente
`500`	`INTERNAL_SERVER_ERROR`	Error inesperado	Reintenta. Reporta `requestId` si persiste

Cabeceras

Idempotency-Keyrequerida: Clave única de la intención, 8-128 caracteres (un UUID v4 sirve). Se genera UNA vez por intención del usuario y se reutiliza en cada reintento: mismo cuerpo ⇒ misma respuesta con `Idempotent-Replayed: true`, sin repetir el efecto. La respuesta se guarda 24 h.

Cuerpo de la petición

userPublicIdstringrequerido
Ejemplo: "01JKX7PEND0000000000000036"

Respuesta 201

El proveedor confirmó: ACTIVE y con dirección. Repetir la llamada devuelve esta misma wallet

addressstringpuede venir null
admite null
Ejemplo: "0xabcdef1234567890abcdef1234567890abcdef12"
chainstring
Ejemplo: "BASE"
createdAtstring
Ejemplo: "2026-09-04T15:04:05.000Z"
networkstring
Ejemplo: "MAINNET"
ownerPublicIdstring
Ejemplo: "01JKX7PEND0000000000000036"
providerCodestring
Ejemplo: "CROSSMINT"
publicIdstring
Ejemplo: "01JKX7MNDR0000000000000037"
purposestring
Ejemplo: "PAYMENTS"
statusenum
PENDINGACTIVEFAILEDDISABLEDMIGRATING
Ejemplo: "ACTIVE"

Errores

Estado	Códigos	Cuándo
`400`	`IDEMPOTENCY_KEY_REQUIRED`	Falta la cabecera `Idempotency-Key` o no mide entre 8 y 128 caracteres
`401`	sin code	Sin x-api-key válida
`403`	sin code	La llave no tiene el scope wallets:write
`404`	`WALLET_OWNER_NOT_FOUND`	El usuario no existe o no es de este partner
`409`	`IDEMPOTENCY_IN_FLIGHTWALLET_PROVISION_UNCONFIRMED`	El proveedor no contestó: la wallet queda PENDING y un job la termina; NO se reintenta creando otra Hay una petición en curso con esa misma clave: espera y reintenta
`422`	`IDEMPOTENCY_PAYLOAD_MISMATCHIDEMPOTENCY_ROUTE_MISMATCH`	La clave ya se usó con OTRO cuerpo o en OTRA ruta: genera una nueva
`429`	`RATE_LIMITED`	Limite de uso: 60 por minuto por credencial. Respeta la cabecera `Retry-After`.
`500`	sin code	Error interno inesperado. Reintenta la petición. Si persiste, reporta el `requestId` al equipo de soporte.