Overview

Retorna Gateway is one integration for sending payments across several payment networks. You ask for a price, you commit to it, and we deliver the funds — the differences between the networks underneath are ours to deal with, not yours.

The model

Three objects, in this order:

Object	What it is
Route	A corridor enabled for your company: method + destination country + currency, with its rate, fees and limits.
Quotation	A price locked for a short window. Single-use.
Order	The payment itself, executing exactly one quotation.

The flow is always the same:

GET  /me/routes      → what you can send, and how much is left in your limits
POST /quotations     → lock a rate
POST /orders         → execute that quotation
GET  /orders/{id}    → follow it, or let a webhook tell you

An order never carries a price of its own. It inherits everything from the quotation it references, which is why a quotation backs exactly one order and cannot be reused.

What you need before the first call

• A clientId and clientSecret. They are an API key, not a login — one credential means one company, and no endpoint takes a company parameter. See authentication.
• Your RSA private key, handed to you once when your organization was provisioned. Most endpoints require a signed request; without the key you can get a token and little else.

Environments

Environment	Base URL
Sandbox	https://api.gateway.sandbox.retorna.app
Production	https://api.gateway.retorna.app

Integrate against sandbox first: same contract, same signing, no real money. Your credentials are issued per environment — a sandbox clientId will not authenticate against production.

Conventions worth knowing up front

• Fields are snake_case — idempotency_key, payment_instructions, created_at.
• Money is a decimal string, never a number: "56.00", so nothing is lost to floating point. No exceptions.
• Unknown fields are rejected with a 400. Send exactly what the schema declares — there is no silent ignoring.
• Error message text is in Spanish, whatever language you read these docs in. Branch on code, not on the message. See errors.
• bank_name is a closed catalog, not free text — the API name of the bank, like BANCO_BANESCO_VE. See bank entities.

Where payouts land today

Payouts are enabled for Venezuela. The bank catalogs for Colombia and Peru are published so you can map your own UI ahead of time, but those corridors are not open on this API yet — bank_name only accepts the Venezuela catalog.

Ready? The quickstart walks the whole flow with real requests.