Visión general
La API Base concentra el flujo principal de pagos: autenticación, customers, tarjetas/tokenización y transacciones. Sellers y Split tienen superficies propias porque atienden operaciones de plataforma y distribución.
Identidad reutilizable.
Crea el comprador una vez y reutiliza el contexto en nuevos recorridos.
Crea y sigue pagos.
Pix, tarjeta y boleto entran en el mismo ciclo transaccional de la API.
Menos exposición.
Asocia instrumentos de pago al customer para recorridos recurrentes y de recompra.
Autenticación
Envía email, secret e io_seller_id para obtener el access_token. Utiliza el token devuelto en el header Authorization de las siguientes requests.
curl --request POST \
--url https://api.iopay.com.br/api/auth/login \
--header 'Content-Type: application/json' \
--data '{
"email": "tu_email",
"secret": "tu_secret",
"io_seller_id": "<IO_SELLER_ID>"
}'access_token, token_type, token_scope y expires_in. Usa el access token como Authorization: Bearer tu_token en las siguientes llamadas y no expongas credenciales ni tokens en el frontend, el repositorio o logs públicos.Flujo básico
Envía tus credenciales y obtén el access token.
Recibe un identificador reutilizable para el recorrido.
Crea Pix, tarjeta o boleto asociado al customer.
Usa la consulta por ID y los webhooks para seguir los cambios.
Crear customer
curl --request POST \
--url https://api.iopay.com.br/api/v1/customer/new \
--header 'Authorization: Bearer tu_token' \
--header 'Content-Type: application/json' \
--data '{
"first_name": "Maria",
"last_name": "Oliveira",
"customer_type": "person_natural",
"email": "[email protected]",
"taxpayer_id": "12345678909",
"phone_number": "+5511999999999",
"address": {
"line1": "Av. Paulista, 1000",
"line2": "Apto 101",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"state": "SP",
"postal_code": "01310100",
"country_code": "BR"
}
}'Crear transacción Pix
curl --request POST \
--url https://api.iopay.com.br/api/v1/transaction/new/:CustomerID \
--header 'Authorization: Bearer tu_token' \
--header 'Content-Type: application/json' \
--data '{
"amount": 12990,
"currency": "BRL",
"description": "Pedido #102938",
"statement_descriptor": "IOPAY STORE",
"io_seller_id": "<IO_SELLER_ID>",
"payment_type": "pix",
"reference_id": "order_102938"
}'Recursos
| Área | Uso | Siguiente referencia |
|---|---|---|
| Customers | Registro, consulta e identidad del pagador. | API Base |
| Tarjetas / tokenización | Instrumentos asociados al customer y recompra. | API Base |
| Transacciones | Creación, consulta, captura y cancelación. | API Base |
| Pix | Cobro, identificadores y seguimiento del estado. | API Base + Webhooks |
| Boleto | Creación y ciclo del cobro bancario. | API Base + Webhooks |
| Sellers | Participantes de plataforma / marketplace. | Sellers API → |
| Split | Distribución entre participantes. | Split API → |