Docs - API Payments

Process QR code payments across LATAM with a single integration

## Sections
• [Introducción](https://docs.manteca.dev/payments/getting-started/introduction.md): API Payments está diseñada para empresas que buscan agilizar el proceso de pagos de sus usuarios sin incurrir en costos elevados y con la ventaja de realizar una única integración para brindar servicios en múltiples países. A través de nuestro servicio, es posible realizar pagos QR, cumpliendo con las normativas vigentes. Nuestro servicio admite: Generación y procesamiento de pagos QR estáticos y dinámicos Operaciones en descubierto con liquidación en múltiples monedas Una única integración para todos los países soportados Actualizaciones de estado en tiempo real Seguridad y cumplimiento con estándares regulatorios locales Arquitectura y formato de respuesta Manteca está organizada alrededor de la interfaz REST . Tiene URLs predecibles orientadas a recursos y usa códigos de respuesta HTTP estándar. Todos los valores de retorno son en formato JSON. Contamos con un sandbox para que puedas probar el API sin alterar los flujos productivos. Para acceder al mismo, tendrás que usar la URL correspondiente (junto con sus API keys). Por otro lado, para todo lo que es notificaciones hacia el lado del cliente, utilizamos webhooks. También contamos con un servicio de websockets para escuchar algunos eventos como los precios. El API utiliza el protocolo HTTPS para exponer los endpoints. No soporta HTTP. Entorno de pruebas (sandbox) Disponemos de un entorno sandbox para que puedas probar la API sin afectar los flujos productivos. Para acceder, es necesario utilizar la base URL https://sandbox.manteca.dev junto con las API keys entregadas. Notificaciones Como medio para las notificaciones utilizamos webhooks con exponential-backoff; es decir, que seguiremos enviando los avisos hasta que nos respondas con un estado 2xx. Para más información, ir a Webhooks .
• [Autenticación](https://docs.manteca.dev/payments/getting-started/theneo-api-documentation.md): Manteca utiliza API keys para autenticar los requests. Las mismas son enviadas a través del header md-api-key Las credenciales poseen privilegios completos por lo que es imprescindible que sean guardadas de manera segura. La interacción con Manteca debe ser siempre del lado del servidor, especialmente para los llamados autenticados. En algunos casos, también proveemos la posibilidad de realizar IP whitelisting o acceder vía una VPN exclusiva para aumentar la seguridad.
• [Webhooks](https://docs.manteca.dev/payments/getting-started/webhook.md): Podés configurar los webhook endpoints a través del API para ser notificado por cada uno de los eventos que ocurran y te sean de interés. Para garantizar la integridad de los datos enviados mediante webhooks, utilizamos un sistema de validación basado en HMAC. Cada webhook se envía con una firma en md-webhook-signature como header que, junto con el secret que tenemos en conjunto, permitirá realizar la verificación de autenticidad de los mensajes. Básicamente, el sigature enviado tiene que ser el mismo que generan de su lado, aplicando HMAC al contenido que llega con el secreto en común. Para garantizar que la serialización del JSON sea determinística, es necesario ordenar las claves del objeto de manera alfabética antes de realizar la conversión a string. Esto asegura consistencia en las respuestas y es especialmente útil para firmas criptográficas o validaciones HMAC. En nuestro caso particular, utilizamos la librería fast-json-stable-stringify para hacer la serialización del mismo. Los webhooks, tanto en el entorno de desarrollo como en el productivo, llegarán de la IP 18.229.68.94 . La misma se encuentra fija para poder ajustar las políticas de seguridad pertinentes de su lado. Además, tenemos un sistema de reintentos automáticos que operan con exponential backoff; esto significa que se reintentará múltiples veces y cada reintento será después de un intervalo mayor. Realizamos hasta 8 reintentos de cada envío. Además, contamos con un sistema de reintentos automáticos con exponential backoff, lo que significa que: Si un webhook no se recibe correctamente, el sistema intentará reenviarlo. Cada reintento se realizará después de un intervalo de tiempo creciente. Se realizarán hasta 8 intentos antes de descartar el mensaje.
  • [Crear webhook](https://docs.manteca.dev/payments/getting-started/webhook/crear-webhook.md)
  • [Obtener configuración](https://docs.manteca.dev/payments/getting-started/webhook/obtener-webhook.md)
  • [Eventos de interés](https://docs.manteca.dev/payments/getting-started/webhook/eventos.md): Contamos con dos tipos de eventos para notificar a través de webhooks. Cada vez que ocurre un cambio de estado relevante en un proceso, se dispara automáticamente un webhook a la URL configurada.
    • [Estado sintético](https://docs.manteca.dev/payments/getting-started/webhook/eventos/sinteticos.md): Este evento se dispara ante cada nuevo cambio de estado sobre un sintético. Los estados posibles de un sintético son: STARTING El sintético aún no comenzó a ejecutarse. ACTIVE Algún stage del sintético se está ejecutando. WAITING Espera el momento de ejecución de la siguiente etapa (en caso que aplique). COMPLETED Todos los stages se ejecutaron con éxito. CANCELLED El sintético falló y fue cancelado. Las operaciones se reversan automáticamente. EXPIRED El sinté tico expiró por inactividad prolongada (por ejemplo, vencimiento del trigger de depósito). JSON { "data": { "companyId": "66671e9cc44a8c0007ecfd64", "creationTime": "2025-02-26T17:19:55.005-03:00", "currentStage": 3, "details": { "againstAmountOperated": "0.72692903", "assetAmountOperated": "0.72692903", "depositAddress": "0x32B35da602824Cc2bccdB2AC17FE14914FCb0d6F", "paymentAgainstAmount": "0.72692903", "paymentAssetAmount": "4.23", "paymentPrice": "0.172", "price": "1", "priceExpireAt": "2025-02-26T17:24:49.811-03:00" }, "id": "67bf776b3b23da4c03f66774", "numberId": "534", "sessionId": "sessionId-pix-1", "stages": [ { "against": "USDT", "asset": "USDC", "assetAmount": "0.72692903", "disallowDebt": false, "orderId": "67bf776b3b23da4c03f6677e", "price": "1", "priceCode": "192c0a6f-08df-4d50-8baf-834698afb30c", "ruleId": "6433efa7-4f60-449a-893e-e3b3e542d348", "side": "BUY", "stageType": "ORDER", "type": "MARKET" }, { "amount": "4.23", "asset": "BRL", "network": "PIX", "ruleId": "0a13b69e-b8cf-4e02-b237-50bce5869f09", "stageType": "WITHDRAW", "to": "USDC-.-0.72692903-.-Zeca Pagodinho Silva-.-BRA-.-12345678909-.-asdjkajksdasdsa", "withdrawId": "67bf776b3b23da4c03f6678e" } ], "status": "COMPLETED", "type": "PIX_PAYMENT", "updatedAt": "2025-02-26T17:19:58.181-03:00", "userExternalId": "user-external-2", "userId": "6747c83224f33735397a3a46", "userNumberId": "100004699" }, "event": "SYNTHETIC_STATUS_UPDATE" }
    • [Estado documentación](https://docs.manteca.dev/payments/getting-started/webhook/eventos/nuevo-estado-validacion-de-documentacion.md): Este evento se dispara ante cada validación de documentación de un usuario. Si tanto el DNI_FRONT como el DNI_BACK se encuentran en estado validados, el usuario debería pasar a estar activo para poder operar. Por ejemplo: JSON { "data": { "date": "2024-11-27T02:37:10.151Z", "document": "DNI_BACK", "numberId": "100004683", "sessionId": "session-v2-2", "comment": "Ok", "userExternalId": "user-external-1", "validated": true }, "event": "DOCUMENT_VALIDATION" }
• [Dashboard](https://docs.manteca.dev/payments/getting-started/dashboard.md): El Dashboard es una interfaz centralizada que permite a las empresas monitorear y gestionar los procesos integrados a través de nuestra API. Desde esta plataforma, es posible visualizar el estado de los usuarios, analizar la documentación cargada y monitorear las operaciones en tiempo real. Para acceder, bastaría con dirigirse a: Entorno productivo : https://dashboard.manteca.dev/login Entorno sandbox : https://dashboard-qa.manteca.dev/login El acceso a la plataforma requiere autenticación mediante credenciales de usuario y cuenta con un segundo factor de autenticación (2FA) para garantizar un nivel adicional de seguridad en el ingreso.
• [Widget](https://docs.manteca.dev/payments/onboarding-users/customizing.md): El widget es un sistema embebible diseñado para facilitar integraciones sin necesidad de desarrollo front-end. Este feature permite a las plataformas integrar procesos complejos como KYC, compra y venta de criptomonedas de forma trivial, adaptándose incluso a casos en los que normalmente no se requiere KYC en sus operaciones regulares. Además, el sistema cuenta con webhooks configurables que notifican en tiempo real a la URL definida por la plataforma integradora cada vez que ocurre un evento de interés en el widget. Esto incluye eventos clave como la finalización del KYC. El widget sigue un funcionamiento estándar para todos los casos de uso. Los pasos principales son: 1 Generación de url Se realiza un POST a nuestras APIs con configuraciones específicas, para lograr el flujo esperado (onboarding, ramp-on, ramp-off). Entre estas configuraciones, se puede enviar un externalId que permitirá identificar al usuario posteriormente y un sessionId que permitirá conocer el historial de actividades que ocurrieron en una misma corrida. 2 Redirección del usuario al widget Una vez tenemos la URL, se redirecciona allî al usuario, donde podrá seguir los pasos presentados de manera interactiva. Es importante destacar que el KYC se hace una única vez por usuario; es decir, si el mismo ya se encuentra registrado, el widget se da cuenta de manera automatica y evitar solicitarlo nuevamente. 3 Redirección a la successUrl En cuanto el flujo termina, se redirigirá al usuario a la URL que fue configurada como successUrl; es decir, la url en caso de éxito. Si hubiera un error, el mismo sería informado vía esa URL o bien, se puede configurar para que se utilice una failureUrl. Flujo del registro Al acceder a la primera pantalla y completar los datos iniciales, la cuenta del usuario será creada. Luego, el usuario debe completar la información necesaria para verificar sus datos e identidad. Estos son todos los pasos que deberá seguir durante el proceso de creación de su cuenta, hasta que quede validado para operar. Identificadores de usuario Para identificar al usuario y a la operación de onboarding, contamos con distintos tipos de identificadores: externalId: Permite identificar al usuario posteriormente. sessionId: Facilita el seguimiento del historial de actividades dentro de una misma sesión.
  • [Alta de usuario](https://docs.manteca.dev/payments/onboarding-users/customizing/kyc.md): Al utilizar el widget de onboarding , solo es necesario redirigir al usuario a la URL generada , donde podrá completar sus datos de manera autónoma. Una vez finalizado el proceso de verificación, el usuario será redirigido automáticamente a la returnUrl proporcionada. Además, el sistema enviará webhooks para notificar en tiempo real el estado del proceso de verificación. El body que se debe enviar para crear la URL de onboarding tiene el siguiente formato:
• [API](https://docs.manteca.dev/payments/onboarding-users/api.md): Contamos también con APIs raw; es decir, APIs REST mediante la cuales se puede procesar las altas de los usuarios. El alta de usuario por esta vía consta de dos pasos principales. Los dos pasos son obligatorios para considerar a un usuario como dado de alta correctamente y que el mismo pueda realizar pagos. Crear un usuario: se debe realizar el alta usando el POST de crear usuario . Subir documentación: la subida de documentación consta de dos pasos. Primero, se realiza la generación del link de suba de documentación . Una vez obtenida se debe subir a esa URL mediante PUT la imagen correspondiente como un binario . Es necesario subirle tanto DNI_FRONT (frente del documento de identidad) como DNI_BACK (dorso del documento de identidad) a un usuario.
  • [Alta de usuario](https://docs.manteca.dev/payments/onboarding-users/api/crear-usuarios.md): Crea un nuevo usuario y devuelve el objeto correspondiente al usuario creado. Existe dos alternativas al momento de crear el usuario: 1) Utilizar el pseudolegalid que corresponde, en Argentina, al número de DNI del usuario. 2) Utilizar el legalid que corresponde, en Argentina, al cuit del usuario.
  • [Carga de documentación](https://docs.manteca.dev/payments/onboarding-users/api/carga-de-documentacion.md): El proceso de carga de documentación consta de dos pasos esenciales: 1 Obtener la URL de subida Antes de cargar un documento, es necesario obtener una URL de subida. Esta URL permite adjuntar los siguientes documentos: Frente y dorso del DNI. Declaración jurada (para usuarios PEP). Documentos de origen de fondos (requeridos para el aumento de límites operativos). Los formatos soportados son jpg , webp , png , gif , pdf , jpeg , bmp , heic , jfif , tif , tiff . 2 Subir el archivo mediante un PUT Una vez obtenida la URL, el archivo debe enviarse en formato binario utilizando el método PUT. Si la carga se realiza correctamente, la API responderá con un status 200.
  • [Obtener usuario por ID](https://docs.manteca.dev/payments/onboarding-users/api/obtener-usuario-por-id.md): Retorna un usuario utilizando cualquier identificador relacionado (puede ser el numberId o el externalId).
• [Sintéticos](https://docs.manteca.dev/payments/qr-payments/sinteticos-1.md): Los sintéticos funcionan como una capa de abstracción que permite agrupar múltiples operaciones en una sola. Básicamente, son una cadena de operaciones unificadas en una entidad. Para poder relacionar todas las operaciones que ocurren dentro de un sintético, se usa el sessionId que no es mas que un identificador opcional que puede enviarse como parte del request y el mismo estará en todas las entidades participantes (depósito, órden, retiro y webhook). Actualmente, un pago QR se compone de tres pasos internamente: Depósito: se pueden configurar los pagos para que salgan una vez se realiza un depósito en una dirección particular. También, se puede configurar al sistema para que opere en descubierto, permitiendo que este paso sea omitido y siempre se genere deuda a favor de Manteca. Ó rden: gestiona la operación de venta de la moneda origen a la moneda destino del pago. Esto significa que, si por ejemplo se realiza un pago PIX en reales (BRL) y las liquidaciones son en pesos argentinos (ARS), veremos como en cada sintético, tendremos una operación ARS → BRL. Los ARS de origen se sumaran a la deuda de la entidad con Manteca y los BRL son los que se usarán para hacer el pago per sé. Pago : gestiona todo lo necesario para realizar un pago QR.
  • [Preview de pago](https://docs.manteca.dev/payments/qr-payments/sinteticos-1/preview-de-pago-1.md): Para poder realizar un pago QR es condición necesaria la lectura del mismo para obtener la información asociada. La idea de funcionamiento de este endpoint es no solo informar los datos asociados de pago, sino también, generar y devolver un código que luego será utilizado para realizar el pago final. Entre la información devuelta, también estará el tipo de cambio utilizado para la operación, entre otros datos de interés. En caso que se solicite un preview de un QR que ya se encuentre pago, se obtendrá un error de PIX_STATUS y, si el mismo es inválido, se obtendrá un error de INVALID_PIX_CODE . Los QRs pueden ser estáticos o dinámicos . En los QRs estáticos, el monto de pago que devuelve el endpoint será 0 , ya que no llevan un valor predefinido. En los QRs dinámicos, en cambio, el monto estará preestablecido y será mayor a 0. Si el QR es estático, no se generará un código de pago. En ese caso, es necesario realizar nuevamente el preview, esta vez enviando un monto fijo que represente el valor que el usuario desea abonar. Tener en cuenta que en Sandbox, para el caso de PIX, se puede mandar cualquier string como qrCode. Si el string incluye la palabra “inactive”, se devolverá un QR no activo (o sea, ya pago). Si el string incluye la palabra “manualamount”, se devolverá un QR estático sin valor. En cualquier otro caso, se generará un QR aleatorio. En caso de QR 3.0, se recomienda utilizar el siguiente QR a modo de ejemplo 00020101021140200010com.yacare02022350150011336972350495204739953030325802AR5910HAVANNA SA6012BUENOS AIRES81220010com.yacare0204Y2156304E401.
  • [Generar pago QR](https://docs.manteca.dev/payments/qr-payments/sinteticos-1/crear-sintetico-de-ramp-on.md): Después de realizar el preview, podemos avanzar con el pago. Para ello, es necesario llamar a este endpoint utilizando el código generado en el preview. El pago se inicia con el estado STARTING . Una vez procesado, su estado cambia a COMPLETED si se realizó con éxito o a CANCELLED si ocurrió un error.
  • [Consulta de estado](https://docs.manteca.dev/payments/qr-payments/sinteticos-1/consulta-de-estado.md): Para conocer el estado del pago, tenemos dos opciones: realizar long-polling sobre el estado del sintético o escuchar los cambios de estado vía webhook. En este último caso, estaríamos recibiendo el webhook SYNTHETIC_STATUS_UPDATE (Ver webhooks ). Para consultar el estado mediante REST, podemos utilizar el siguiente endpoint:
• [Argentina QR 3.0](https://docs.manteca.dev/payments/qr-payments/paises-soportados/argentina-qr-3-0.md): QR 3.0 es el estándar interoperable de pagos con QR en Argentina. Permite que cualquier billetera pueda escanear y procesar pagos a través de diferentes proveedores, facilitando transacciones instantáneas entre comercios y usuarios. Su integración permite aceptar pagos desde múltiples fuentes sin fricción, incluyendo los QRs de MercadoPago.
• [Brasil PIX](https://docs.manteca.dev/payments/qr-payments/paises-soportados/brasil-pix.md): PIX es el sistema de pagos instantáneos del Banco Central de Brasil. Funciona 24/7 y permite transferencias y pagos inmediatos entre bancos y billeteras digitales mediante claves, códigos QR o datos bancarios. Es ampliamente utilizado tanto para pagos entre personas como para compras en comercios.
• [Mexico CODI](https://docs.manteca.dev/payments/qr-payments/paises-soportados/mexico-codi.md): CoDi (Cobro Digital) es el sistema de pagos electrónicos desarrollado por el Banco de México. Basado en tecnología QR y NFC, permite realizar pagos y cobros de forma instantánea sin comisiones, integrándose con cuentas bancarias y billeteras digitales para transacciones rápidas y seguras.