How Péso works

Péso accepts payments from your customers and routes each one through a cascade of payment providers. You create an order, we find a provider that can take it right now, the customer pays, and you receive a signed callback with the result. Settlement is always in USD.

Three things to know

A cash desk is an integration. Every cash desk has its own key and secret, one payment method, its own callback URL and its own limits. If you sell several products or work in several countries, create a cash desk for each: traffic, limits and reporting stay separate. The payment method is fixed for the life of the cash desk.

An order is one payment. It carries two amounts: what the customer pays, in their currency, and what you see, in USD. The exchange rate is captured when the order is created and never recalculated, however long the customer takes to pay. The fee is a percentage of the USD amount, from the tariff attached to the cash desk.

A callback is the source of truth. When an order closes, we POST a signed event to your cash desk's callback URL. Verify the signature, drop duplicates by event id, answer 2xx. You do not need to poll; GET on an order is for reconciliation.

The path of a payment

1. Your server calls POST /gw/v1/orders with the amount and, optionally, your own reference. Everything you need to validate first is in Orders.
2. The cascade picks a provider that currently offers the rail and currency, and the response carries the payment details the customer needs: a phone number, a card number or a payment page URL, plus the time by which they are valid.
3. The customer pays. Show the details yourself, or send the customer to our payment page.
4. The provider confirms. The order becomes Completed, your balance is credited in USD minus the fee, and order.completed reaches your callback URL.
5. If the customer did not pay in time, the order closes with order.cancelled.

If the customer insists they paid but the order was cancelled, you open an appeal. When it is accepted, the order is completed and credited as usual.

Where things live

Surface	Path	Authentication	Who calls it
Gateway	/gw/v1/*	HMAC signature with the cash desk secret	Your server
Callbacks	your callback URL	HMAC signature, verified by you	Us, to your server
Payment page	/payment/{orderId}	None	The customer's browser
Cabinet	the merchant cabinet	Login and password	You, in a browser

The rest of this guide covers the gateway and the callbacks. The API reference is generated from the same code that serves the gateway. The cabinet guide covers what you can do without writing code, and the FAQ answers the questions support hears most.

Environments

There is one API. An account starts in the sandbox: orders are routed to a test provider, signatures and callbacks are real, no money moves. After an administrator approves the account, the same keys route to live providers. See Sandbox and approval.