Visão geral da API v2

A API v2 é a nova API REST da 4SeletPay para criar pedidos com um ou mais meios de pagamento, assinaturas recorrentes e cartões salvos. Ela usa JSON, autentica com a sua chave de API e responde com objetos planos, sem envelope.

https://app.4seletpay.com.br/api/v2

A API v1 continua disponível. Veja Migrando da v1 para entender o que muda.

Convenções

Convenção	Como funciona na v2
Autenticação	`Authorization: Bearer sk_...` com a sua chave de API. Não existe header `account`
Valores	Sempre em centavos, como inteiro (R$ 10,00 = `1000`)
Moeda	Enviada como `BRL` ou `USD`; devolvida em minúsculas (`brl`)
Datas	ISO 8601
Erros	Envelope `{ "error": { ... } }` — veja Erros
Reenvio seguro	Header `Idempotency-Key` — veja Idempotência e limites

Conceitos

Pedido (order)

A compra do cliente. Reúne os itens e um ou mais pagamentos (por exemplo, dois cartões ou cartão + PIX).

Pagamento (payment_intent)

Cada meio de pagamento dentro de um pedido ou fatura. O id do pagamento é o mesmo id da cobrança.

Cobrança (charge)

A visão financeira de um pagamento: quanto foi pago, estornado e ainda pode ser estornado.

Cartão (card)

Um cartão salvo do cliente. Use o id como card.token em pedidos, assinaturas e faturas.

Assinatura (subscription)

Cobrança recorrente. Cada ciclo gera uma fatura.

Fatura (invoice)

Uma cobrança de um ciclo da assinatura, com os próprios pagamentos e status.

Recursos e rotas

Recurso	Método	Rota
Pedidos	`POST`	`/v2/orders`
	`GET`	`/v2/orders/{id}`
	`POST`	`/v2/orders/{id}/capture`
	`POST`	`/v2/orders/{id}/cancel`
	`POST`	`/v2/orders/{id}/confirm`
	`POST`	`/v2/orders/{id}/confirm/resend`
Cobranças	`GET`	`/v2/charges/{id}`
	`POST`	`/v2/charges/{id}/refund`
Cartões	`POST`	`/v2/cards`
	`GET`	`/v2/cards/{id}`
Assinaturas	`POST`	`/v2/subscriptions`
	`GET`	`/v2/subscriptions/{id}`
	`POST`	`/v2/subscriptions/{id}/cancel`
	`POST`	`/v2/subscriptions/{id}/payment-method`
	`POST`	`/v2/subscriptions/{id}/items/{code}`
	`POST`	`/v2/subscriptions/{id}/next-billing-date`
	`GET`	`/v2/subscriptions/{id}/invoices`
Faturas	`GET`	`/v2/invoices/{id}`
	`POST`	`/v2/invoices/{id}/pay`
	`POST`	`/v2/invoices/{id}/confirm`
	`POST`	`/v2/invoices/{id}/confirm/resend`

Como um pagamento acontece

Você cria o pedido com POST /v2/orders.
A resposta traz o status do pedido e, quando o cliente precisa agir, um next_action (QR Code PIX ou código de verificação).
A confirmação final chega por webhook (order.paid, charge.paid).

201 Created não significa pago. A resposta traz o resultado da autorização: requires_capture, requires_action, processing ou failed. Um cartão aprovado pode ficar em processing até a confirmação. Use os webhooks para saber quando o pedido foi pago.

Uma resposta 402 também traz o recurso completo, com status: "failed" e o motivo em failure_reason. Veja Pagamento recusado.

Próximos passos

Autenticação

Envie a sua chave de API em todas as chamadas.

Criar pedido

Cobre com cartão, PIX ou os dois no mesmo pedido.

Erros

Formato de erro e catálogo de códigos.

Webhooks

Receba a confirmação dos pagamentos.

​Convenções

​Conceitos

Pedido (order)

Pagamento (payment_intent)

Cobrança (charge)

Cartão (card)

Assinatura (subscription)

Fatura (invoice)

​Recursos e rotas

​Como um pagamento acontece

​Próximos passos

Autenticação

Criar pedido

Erros

Webhooks

Convenções

Conceitos

Recursos e rotas

Como um pagamento acontece

Próximos passos