Overview
The Base API concentrates the main payment flow: authentication, customers, cards/tokenization and transactions. Sellers and Split have their own surfaces because they serve platform and distribution operations.
Reusable identity.
Create the buyer once and reuse the context in new journeys.
Create and track payments.
Pix, cards and boleto enter the same transactional cycle of the API.
Less exposure.
Associate payment instruments with the customer for recurring and repurchase journeys.
Authentication
Send email, secret and io_seller_id to obtain the access_token. Use the returned token in the Authorization header of the next requests.
curl --request POST \
--url https://api.iopay.com.br/api/auth/login \
--header 'Content-Type: application/json' \
--data '{
"email": "your_email",
"secret": "your_secret",
"io_seller_id": "<IO_SELLER_ID>"
}'access_token, token_type, token_scope and expires_in. Use the access token as Authorization: Bearer your_token in the next calls and don't expose credentials or tokens in the frontend, repository or public logs.Basic flow
Send your credentials and get the access token.
Receive a reusable identifier for the journey.
Create Pix, card or boleto associated with the customer.
Use queries by ID and webhooks to track changes.
Create customer
curl --request POST \
--url https://api.iopay.com.br/api/v1/customer/new \
--header 'Authorization: Bearer your_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"
}
}'Create Pix transaction
curl --request POST \
--url https://api.iopay.com.br/api/v1/transaction/new/:CustomerID \
--header 'Authorization: Bearer your_token' \
--header 'Content-Type: application/json' \
--data '{
"amount": 12990,
"currency": "BRL",
"description": "Order #102938",
"statement_descriptor": "IOPAY STORE",
"io_seller_id": "<IO_SELLER_ID>",
"payment_type": "pix",
"reference_id": "order_102938"
}'Resources
| Area | Use | Next reference |
|---|---|---|
| Customers | Registration, queries and payer identity. | Base API |
| Cards / tokenization | Instruments associated with the customer and repurchase. | Base API |
| Transactions | Creation, query, capture and cancellation. | Base API |
| Pix | Charging, identifiers and status tracking. | Base API + Webhooks |
| Boleto | Creation and lifecycle of bank slip charges. | Base API + Webhooks |
| Sellers | Platform / marketplace participants. | Sellers API → |
| Split | Distribution among participants. | Split API → |