> ## Documentation Index > Fetch the complete documentation index at: https://docs.velafi.com/llms.txt > Use this file to discover all available pages before exploring further. # Dispersar moneda local fondeada con stablecoins > Fondea la billetera de un comercio con USDT o USDC y paga moneda local, USD o EUR a un beneficiario registrado con órdenes crypto_to_fiat, incluido el manejo de fallas y la conciliación. Esta receta paga fiat a un tercero, como un proveedor, un vendedor o uno de tus usuarios, y fondea el pago con stablecoins. Depositas USDT o USDC en la billetera de VelaFi del comercio, registras la cuenta bancaria del destinatario como beneficiario y creas una orden `crypto_to_fiat` para cada pago. VelaFi convierte la cripto al tipo de cambio cotizado y envía el fiat por el riel local (por ejemplo, SPEI, Pix, CVU, Bre-B) o por Circle Payment Network (CPN) para USD y EUR. Para la referencia completa de campos, consulta la guía [Off-ramp (cripto a fiat)](https://docs.velafi.com/es/docs/guides/off-ramp.md) y [Crear una orden de off-ramp](https://docs.velafi.com/es/api-reference/order/create-a-crypto-to-fiat-order.md). ## Cómo funciona ```mermaid theme={null} sequenceDiagram participant You as Tu sistema participant V as API de VelaFi participant Bank as Riel de pago You->>V: GET /v2/assets/depositAddress You->>V: Envía USDT/USDC on-chain a la dirección You->>V: POST /v2/payments (registrar beneficiario) V-->>You: userPaymentId, status 1 You->>V: GET /v2/user/crypto-quote (createQuoteId=true) You->>V: POST /v2/order/crypto_to_fiat V-->>You: orderId Note over V: Cripto descontada de la billetera (status 40) V->>Bank: Pago fiat al beneficiario Bank-->>V: Resultado del pago V-->>You: ORDER_WEBHOOK 50, después 60 (o 70 / 72) ``` ## Antes de empezar * **Acceso a la API.** Una clave de API, las IP de tus servidores en la lista blanca y un token de negocio para el header `X-BH-TOKEN`. Consulta [Autenticación](https://docs.velafi.com/es/api-reference/authentication.md). * **Un comercio verificado** con una cuenta activada para la moneda y el canal del pago. El beneficiario debe usar un método de pago (`paymentId`) de esa cuenta. Consulta [Activar la cuenta de un comercio](https://docs.velafi.com/es/docs/guides/activating-merchant-account.md). * **`ORDER_WEBHOOK` registrado.** Tu endpoint debe devolver HTTP `2xx` con el cuerpo `{"callbackStatus":"SUCCESS"}`; de lo contrario, la entrega cuenta como fallida. Consulta [Webhooks](https://docs.velafi.com/es/docs/guides/webhooks.md) y [Entrega y reintentos](https://docs.velafi.com/es/api-reference/webhooks/webhook-setup.md#delivery-and-retries). ## Construye el flujo **1. Fondea la billetera cripto del comercio** Obtén la dirección de depósito del comercio para el token y la red que vas a enviar: ```bash theme={null} curl -G https://api.velafi.com/v2/assets/depositAddress \ -H "X-BH-TOKEN: YOUR_TOKEN" \ --data-urlencode "tokenId=USDT" \ --data-urlencode "chainType=TRC20" \ --data-urlencode "merchantId=100001" ``` Envía la cripto a `address` (con `addressExt` si `needAddressTag` es `true`), por al menos `minQuantity`. Consulta [Obtener la dirección de depósito cripto](https://docs.velafi.com/es/api-reference/merchant/get-crypto-deposit-address.md) para ver los pares de token y red admitidos. No hay webhook para los depósitos de cripto entrantes. Confirma el abono con [Listar depósitos cripto](https://docs.velafi.com/es/api-reference/crypto-wallet/get-crypto-deposit-history.md) (`status` `2` es exitoso) y revisa el monto disponible para gastar en `free` con [Obtener el saldo cripto](https://docs.velafi.com/es/api-reference/merchant/get-crypto-assets-balance.md). **2. Registra el beneficiario** Obtén la plantilla de campos del método de pago con `GET /v2/payments/templates?paymentId={paymentId}` y después envía los campos completados con `POST /v2/payments`. Usa el mismo `merchantId` que en tus órdenes. ```json Response theme={null} { "code": 200, "msg": "SUCCESS", "data": { "id": 456, "status": 1, "failReason": "", "sameAccountNumberId": 456 } } ``` Guarda `data.id`. Es el `userPaymentId` para tus órdenes. Solo un beneficiario en `status` `1` (válido) puede recibir pagos. `2` significa que la verificación sigue en curso. `3` significa que falló: lee `failReason` y, si la cuenta ya existe, usa `sameAccountNumberId` en lugar de crear un registro nuevo. Registra un beneficiario una sola vez y reutilízalo. Consulta [Administrar beneficiarios](https://docs.velafi.com/es/docs/guides/managing-beneficiaries.md). **3. Opcional: fija el tipo de cambio con una cotización** Llama a [Obtener una cotización cripto/fiat](https://docs.velafi.com/es/api-reference/quote/get-user-quote-for-crypto-fiat.md) con `from` igual a la cripto, `to` igual al fiat y `createQuoteId=true`. El `price` está expresado en fiat por 1 unidad de cripto. ```bash theme={null} curl "https://api.velafi.com/v2/user/crypto-quote?country=Mexico&from=USDT&to=MXN&createQuoteId=true" \ -H "X-BH-TOKEN: YOUR_TOKEN" ``` Un `quoteId` es válido durante 10 segundos en producción (300 segundos en el sandbox), es de un solo uso y está vinculado al `country`, la cripto y el fiat para los que se emitió. Sin un `quoteId`, la orden se cotiza al momento de crearse. **4. Crea la orden de pago** Llama a `POST /v2/order/crypto_to_fiat` con el `userPaymentId` del beneficiario. Usa el `country` y el `fiat` del beneficiario. Envía `fiatAmount` para fijar lo que recibe el beneficiario, o `cryptoAmount` para fijar lo que gastas. Si envías ambos, prevalece `fiatAmount`. Envía siempre un `clientId` único. ```bash theme={null} curl -X POST https://api.velafi.com/v2/order/crypto_to_fiat \ -H "X-BH-TOKEN: YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "merchantId": 100001, "clientId": "payout-0001", "country": "Mexico", "fiat": "MXN", "crypto": "USDT", "fiatAmount": 1000, "userPaymentId": 456, "quoteId": "YOUR_QUOTE_ID" }' ``` ```json Response theme={null} { "code": 200, "msg": "SUCCESS", "data": { "orderId": 1123123123 } } ``` **Cómo se fondea la orden.** La cripto proviene del saldo de la billetera del comercio para esa `crypto`. VelaFi la descuenta cuando crea la orden, y la orden pasa a `40` (o primero a `10`, `11` o `31` cuando se requiere revisión o documentos). Si el saldo es demasiado bajo, la solicitud se rechaza con un error de saldo insuficiente y no se crea ninguna orden. **Variante con fondeo posterior.** Si VelaFi habilitó el off-ramp con fondeo posterior para tu cuenta (puede variar según la moneda fiat), una orden sin fondos suficientes se acepta y espera en `32` (En espera de depósito cripto). El detalle de la orden devuelve entonces `orderExpireTimestamp`, la fecha límite en segundos Unix. Deposita suficiente cripto en la billetera antes de la fecha límite. VelaFi revisa el saldo cada minuto, lo aplica a las órdenes en espera empezando por la más antigua y mueve una orden cubierta a `40`. Si primero pasa la fecha límite, la orden se cancela (`70`). Consulta [Fondeo de la orden](https://docs.velafi.com/es/api-reference/order/create-a-crypto-to-fiat-order.md#funding-the-order). Si la solicitud excede el tiempo de espera, busca la orden por `clientId` antes de reintentar. Consulta [Idempotencia y reintentos](https://docs.velafi.com/es/api-reference/order/create-a-fiat-to-crypto-order.md#idempotency-and-retries). **5. Da seguimiento al pago hasta que se complete** Espera los eventos `ORDER_WEBHOOK` (`orderType` es `SELL`) o consulta periódicamente `GET /v2/order/detail?orderType=crypto_to_fiat&clientId={clientId}`. | `orderStatus` | Significado para un pago | | - | - | | `32` | Solo fondeo posterior: en espera de tu depósito de cripto | | `40` | Cripto descontada, pago fiat en curso | | `50` | Paso de pago terminado, la orden todavía no está completada. En los canales automatizados la orden se completa sola. También puedes completarla con [Confirmar una orden](https://docs.velafi.com/es/api-reference/order/confirm-a-specific-order.md) | | `60` | Completada. Se le pagó al beneficiario | | `70` | Cancelada. El webhook también envía como `70` los rechazos en revisión y en revisión de riesgos | | `80` | Rechazada en revisión (al consultar) | | `81` | Rechazada en revisión de riesgos (al consultar) | | `72` | Reembolsada: la cripto regresó a la billetera | `traceNumber` contiene el número de referencia del banco central para el pago cuando el riel devuelve uno. Compártelo con el beneficiario si pide un comprobante de pago. ## Pagos en USD y EUR mediante Circle Payment Network CPN transporta pagos en USD y EUR. Es solo para pagos: no puedes cobrar fondos ni crear órdenes `fiat_to_crypto` en CPN. 1. Activa una cuenta CPN para el comercio y la moneda con `trench` establecido en `Circle Payment Network`. Consulta [Activar la cuenta de un comercio empresa](https://docs.velafi.com/es/api-reference/merchant/activate-merchant-account-for-business.md). 2. Registra el beneficiario en un método de pago de CPN, por ejemplo `120` Wire (CPN) o `127` FEDWIRE (CPN) para USD y `124` SEPA (CPN) para EUR. Las plantillas de CPN piden la dirección del beneficiario, un `useCase` y un código `reasonForPayment`. Consulta las plantillas de CPN en [Obtener plantillas de métodos de pago](https://docs.velafi.com/es/api-reference/beneficiary/get-payment-templates.md). 3. Crea la orden `crypto_to_fiat` con `fiat` establecido en `USD` o `EUR` y el `userPaymentId` del beneficiario de CPN, exactamente como se describe arriba. Como cualquier pago, una orden de CPN puede pasar a revisión de riesgos (`11`). Cuando eso ocurre, sube los documentos solicitados con [Subir documentos de una orden](https://docs.velafi.com/es/api-reference/order/upload-invoice-documents-for-a-specific-order.md). Después, la orden pasa a `12` y espera una decisión. ## Webhooks que debes manejar | Evento | Cuándo | Clave | Qué hacer | | - | - | - | - | | `ORDER_WEBHOOK` | La orden entra a `10`, `11`, `12`, `31`, `32`, `40`, `50`, `60`, `70` o `72` | `orderId` + `orderStatus` | Marca como pagada en `60`. En `70` o `72`, libera el pago de tu lado y lee `failCode` / `failReason` | `ORDER_WEBHOOK` se envía solo para órdenes creadas mediante la API. No envía `71` (Cancelando) ni `73` (Reembolsando), y las órdenes rechazadas en revisión o en revisión de riesgos se envían como `70`. Los eventos pueden llegar más de una vez y fuera de orden, y se pueden omitir estados intermedios. Elimina duplicados sobre `orderId` + `orderStatus`, y lee la orden con `GET /v2/order/detail` cuando un evento no coincida con el estado que tienes. ## Maneja las fallas | Lo que ves | Causa probable | Qué hacer | | - | - | - | | Creación rechazada con un error de saldo insuficiente | El saldo `free` de la billetera no cubre la orden | Deposita más cripto y después crea la orden otra vez con un nuevo `clientId` y una nueva cotización. | | Creación rechazada por el beneficiario | `userPaymentId` no tiene `status` `1`, pertenece a otro comercio, o su moneda o canal no coincide con la orden | Revisa el beneficiario con [Listar beneficiarios](https://docs.velafi.com/es/api-reference/beneficiary/get-beneficiary.md) y las cuentas activadas del comercio. | | Creación rechazada como envío repetido | El `clientId` ya se usó | Busca la orden por `clientId`. No la vuelvas a crear. | | `70` después de `32` | La fecha límite del fondeo posterior pasó antes de que la billetera cubriera la orden | Primero fondea la billetera y después crea una nueva orden. | | `80` u `81` al consultar (`70` en el webhook) | Rechazada en revisión o en revisión de riesgos | No la vuelvas a enviar sin cambios. Contacta a VelaFi si necesitas el motivo. | | La orden se queda en `40` | El riel de pago rechazó el pago o todavía no lo ha confirmado. Un pago rechazado no mueve la orden a un estado final por sí solo; el equipo de operaciones de VelaFi lo reintenta o cancela la orden | Contacta al soporte de VelaFi con el `orderId` si la orden se queda en `40` más tiempo de lo habitual para ese riel. No crees una segunda orden para el mismo pago mientras la primera siga abierta. | | `60` y después `72` | El pago fue devuelto después de completarse, por ejemplo, porque el banco del beneficiario lo rebotó | La cripto está de vuelta en la billetera del comercio. Corrige los datos del beneficiario y crea una nueva orden con un nuevo `clientId`. | `failReason` con frecuencia está vacío, porque muchos rieles no devuelven ningún motivo. Trata un `failReason` vacío como "desconocido", no como éxito. Para evitar pagar dos veces, crea un pago de reemplazo solo después de que la orden original sea final (`70` o `72`). ## Concilia * **Cada pago:** [Obtener una orden](https://docs.velafi.com/es/api-reference/order/retrieve-a-specific-order.md) por `orderId` o `clientId` es la fuente de verdad: `orderStatus`, `cryptoAmount` (descontado de la billetera), `fiatAmount` (pagado al beneficiario), `fiatFee`, `orderPrice`, `orderFeeDetail`, `traceNumber`, `failCode` y `failReason`. * **Totales diarios:** [Listar órdenes](https://docs.velafi.com/es/api-reference/order/retrieve-a-list-of-orders.md) con `orderType=crypto_to_fiat` y un rango de tiempo. También lista órdenes que no se crearon mediante la API. * **Billetera:** [Listar depósitos cripto](https://docs.velafi.com/es/api-reference/crypto-wallet/get-crypto-deposit-history.md) para las recargas, y [Obtener el saldo cripto](https://docs.velafi.com/es/api-reference/merchant/get-crypto-assets-balance.md) para `free` y `locked`. Ejecuta un proceso programado que vuelva a leer cada pago que siga abierto de tu lado, y marca las órdenes que permanezcan en `40` o `50` más allá de tu tiempo normal de pago. Los webhooks se pueden perder después de tres intentos de entrega fallidos. ## Prueba en el sandbox * Usa `https://api-test.velafi.com`. Los webhooks **no** se envían en el sandbox, así que consulta periódicamente `GET /v2/order/detail`. * Agrega USDT o USDC de prueba a la billetera de un comercio con el simulador de depósitos de cripto. Consulta [Herramientas de prueba del sandbox](https://docs.velafi.com/es/docs/sandbox.md#sandbox-testing-tools). * Algunos IDs de métodos de pago son distintos en el sandbox; por ejemplo, CBU/CVU (Momentum) es `18` en lugar de `63`. Consulta [Métodos de pago](https://docs.velafi.com/es/docs/payment-methods.md#sandbox-vs-production-ids). * Los simuladores solo producen depósitos exitosos. No puedes simular un pago rebotado, así que prueba tu manejo de `70` y `72` con payloads grabados. ## Lista de verificación para salir a producción * [ ] La billetera está fondeada antes de crear las órdenes, o el off-ramp con fondeo posterior está habilitado y tu sistema fondea las órdenes en `32` antes de `orderExpireTimestamp`. * [ ] Los beneficiarios se registran una sola vez, se guardan por `userPaymentId` y solo se usan cuando `status` es `1`. * [ ] Cada solicitud de creación envía un `clientId` único, y los timeouts se resuelven buscando el `clientId` antes de reintentar. * [ ] El endpoint de `ORDER_WEBHOOK` verifica la firma, devuelve `{"callbackStatus":"SUCCESS"}` con HTTP `2xx` y elimina duplicados sobre `orderId` + `orderStatus`. * [ ] `70` y `72` (incluido `72` después de `60`) liberan o revierten el pago de tu lado, y un reemplazo solo se crea después de que el original sea final. * [ ] Las órdenes atoradas en `40` o `50` se marcan y se escalan con el `orderId`. * [ ] Para USD y EUR, la cuenta CPN está activada y los beneficiarios de CPN incluyen los campos de cumplimiento requeridos. Consulta la [lista de verificación para salir a producción](https://docs.velafi.com/es/docs/use-cases/go-live-checklist.md) completa. ## Related topics - [Casos de uso principales](https://docs.velafi.com/es/docs/use-cases/overview.md) - [Agent Skills](https://docs.velafi.com/es/docs/developer-tools/agent-skills.md) - [Convertir moneda local a stablecoins](https://docs.velafi.com/es/docs/use-cases/convert-to-stablecoins.md) - [Dispersar moneda local desde el saldo](https://docs.velafi.com/es/docs/use-cases/payouts-from-balance.md) - [Cobrar pagos locales con cuentas virtuales](https://docs.velafi.com/es/docs/use-cases/collect-with-virtual-accounts.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.