Visão geral
A API Base concentra o fluxo principal de pagamentos: autenticação, customers, cartões/tokenização e transações. Sellers e Split possuem superfícies próprias porque atendem operações de plataforma e distribuição.
Identidade reutilizável.
Crie o comprador uma vez e reutilize o contexto em novas jornadas.
Crie e acompanhe pagamentos.
Pix, cartão e boleto entram no mesmo ciclo transacional da API.
Menos exposição.
Associe instrumentos de pagamento ao customer para jornadas recorrentes e recompra.
Autenticação
Envie email, secret e io_seller_id para obter o access_token. Utilize o token retornado no header Authorization das próximas requests.
curl --request POST \
--url https://api.iopay.com.br/api/auth/login \
--header 'Content-Type: application/json' \
--data '{
"email": "seu_email",
"secret": "seu_secret",
"io_seller_id": "<IO_SELLER_ID>"
}'access_token, token_type, token_scope e expires_in. Use o access token como Authorization: Bearer seu_token nas próximas chamadas e não exponha credenciais ou tokens no frontend, repositório ou logs públicos.Fluxo básico
Envie suas credenciais e obtenha o access token.
Receba um identificador reutilizável para a jornada.
Crie Pix, cartão ou boleto associado ao customer.
Use consulta por ID e webhooks para acompanhar mudanças.
Criar customer
curl --request POST \
--url https://api.iopay.com.br/api/v1/customer/new \
--header 'Authorization: Bearer seu_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"
}
}'Criar transação Pix
curl --request POST \
--url https://api.iopay.com.br/api/v1/transaction/new/:CustomerID \
--header 'Authorization: Bearer seu_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 | Próxima referência |
|---|---|---|
| Customers | Cadastro, consulta e identidade do pagador. | API Base |
| Cartões / tokenização | Instrumentos associados ao customer e recompra. | API Base |
| Transações | Criação, consulta, captura e cancelamento. | API Base |
| Pix | Cobrança, identificadores e acompanhamento do status. | API Base + Webhooks |
| Boleto | Criação e ciclo de cobrança bancária. | API Base + Webhooks |
| Sellers | Participantes de plataforma / marketplace. | Sellers API → |
| Split | Distribuição entre participantes. | Split API → |