Overview

Retorna Gateway es una sola integración para enviar pagos a través de varias redes de pago. Pides un precio, te comprometes con él y nosotros entregamos los fondos — las diferencias entre las redes de abajo son nuestro problema, no tuyo.

El modelo

Tres objetos, en este orden:

Objeto	Qué es
Route	Un corredor habilitado para tu compañía: método + país de destino + divisa, con su tasa, fees y límites.
Quotation	Un precio fijado por una ventana corta. De uso único.
Order	El pago en sí, que ejecuta exactamente una quotation.

El flujo es siempre el mismo:

GET  /me/routes      → qué puedes enviar, y cuánto queda de tus límites
POST /quotations     → fijas una tasa
POST /orders         → ejecutas esa quotation
GET  /orders/{id}    → la sigues, o dejas que un webhook te avise

Una orden nunca lleva un precio propio: hereda todo de la quotation que referencia. Por eso una quotation respalda exactamente una orden y no se puede reutilizar.

Qué necesitas antes de la primera llamada

• Un clientId y un clientSecret. Son una API key, no un login — una credencial es una compañía, y ningún endpoint recibe un parámetro de compañía. Ver autenticación.
• Tu clave privada RSA, entregada una única vez cuando se aprovisionó tu organización. La mayoría de los endpoints exige request firmada; sin la clave puedes obtener un token y poco más.

Ambientes

Ambiente	URL base
Sandbox	https://api.gateway.sandbox.retorna.app
Production	https://api.gateway.retorna.app

Integra primero contra sandbox: mismo contrato, misma firma, sin dinero real. Las credenciales se emiten por ambiente — un clientId de sandbox no autentica contra producción.

Convenciones que conviene saber de entrada

• Los campos son snake_case — idempotency_key, payment_instructions, created_at.
• El dinero es decimal string, nunca número: "56.00", así no se pierde nada por punto flotante. Sin excepciones.
• Los campos desconocidos se rechazan con 400. Envía exactamente lo que declara el schema — no hay ignorado silencioso.
• El texto de message en los errores viene en español, en cualquier idioma que leas esta doc. Ramifica por code, no por el mensaje. Ver errores.
• bank_name es un catálogo cerrado, no texto libre — el nombre API del banco, tipo BANCO_BANESCO_VE. Ver entidades bancarias.

Dónde caen los payouts hoy

Los payouts están habilitados para Venezuela. Los catálogos bancarios de Colombia y Perú están publicados para que puedas mapear tu UI con anticipación, pero esos corredores todavía no están abiertos en esta API — bank_name solo acepta el catálogo de Venezuela.

¿Listo? El quickstart recorre el flujo completo con requests reales.