Visão geral
O pedido (order) é a compra do cliente na API v2. Ele reúne os itens e um ou mais pagamentos: você pode cobrar um cartão, um PIX, dois cartões ou cartão + PIX no mesmo pedido.
Criar um pedido
Campos principais
Campos do cliente
A v2 não tem recurso de cliente. Envie o comprador em cada pedido.Todos os campos de
customer.address são opcionais: um endereço parcial é aceito e o pedido é criado normalmente. Isso é diferente da assinatura, onde enviar customer.address obriga a preencher o endereço completo.Campos do pagamento (payments[])
Campos do cartão (payments[].card)
¹ Alternativa aos dados do cartão.
² Obrigatório quando
token não é enviado.
Campos do split (payments[].split[])
Campos dos itens (items[])
Análise de fraude (fraud_analysis)
Regras de validação
- A soma de
items[].amount × items[].quantityprecisa ser igual à soma depayments[].amount. - Um pagamento com cartão precisa de
card.tokenou de todos os dados do cartão. - Quando o pedido tem cartão, o
pix_expirationde um pagamento PIX pode ser de no máximo 86400 segundos (24 horas). O cartão fica pré-autorizado enquanto o PIX não é pago. - A soma de
split[].amountprecisa ser igual aoamountdo pagamento. - Quando o split está habilitado na plataforma, exatamente um recebedor precisa ter
options.charge_processing_fee: true, e o valor dele precisa cobrir as taxas de processamento. Pelo menos um recebedor precisa teroptions.charge_remainder_fee: truee pelo menos um precisa teroptions.liable: true. Um split que não pode ser aplicado retorna422(split_error).
Exemplos
Cartão com captura manual
Request
Resposta (HTTP 201)
PIX
Pagamento
Resposta (HTTP 201)
Cartão + PIX
Envie dois itens empayments. O pedido é criado com dois pagamentos e fica em requires_action com o QR Code em next_action. O cartão fica em requires_capture e é capturado automaticamente quando o PIX é pago.
Pagamentos
Captura
Um pagamento com cartão pode ser só autorizado (o limite fica reservado) ou capturado (a venda é concluída).Moeda e conversão
Ocurrency da requisição indica em que moeda estão os valores que você envia (payments[].amount e items[].amount). Ele não tem relação com international.
A 4SeletPay converte os valores para real uma única vez, na criação de cada pagamento, com a cotação do momento. A adquirente sempre recebe o valor em BRL. O valor enviado e a cotação ficam registrados.
Por isso, pedidos, pagamentos, cobranças e faturas respondem com o valor cobrado, em real, e trazem o valor enviado em campos próprios:
Pedido de US$ 10,00
O pedido não tem
exchange_rate. Cada pagamento é convertido no próprio momento, com a cotação vigente, então não existe uma cotação única do pedido. Consulte a cotação em cada item de payments. O amount do pedido é a soma dos pagamentos, em real.Em pedidos em BRL,
original_amount é igual a amount, original_currency é brl e exchange_rate é null. Os valores de estorno (amount, amount_refunded e amount_refundable) também são em centavos de real.O objeto pedido
Status do pedido
O status do pedido é calculado a partir de todos os pagamentos, não apenas do primeiro.Pagamentos
Cada item depayments é um objeto payment_intent. O id do pagamento é o mesmo id da cobrança: use-o em GET /v2/charges/{id} e no estorno.
O objeto
card só aparece quando a cobrança tem um cartão vinculado. Sem cartão, a chave card não é enviada — ela não vem com null. O id do cartão não é devolvido em pedidos nem em cobranças. No webhook de cobrança, ao contrário, card vem como null quando não há cartão.Status do pagamento
Próxima ação (next_action)
Quando o cliente precisa fazer algo, o pedido traz um next_action. Se nada for necessário, o campo vem null.
QR Code PIX
qr_code (código copia e cola) ou a imagem de qr_code_url para o cliente. O expires_at do PIX vem no formato AAAA-MM-DD HH:MM:SS, sem indicação de fuso. O expires_at do código de verificação vem em UTC (ISO 8601).
Código de verificação
A análise de fraude pode pedir que o cliente confirme um código antes do pagamento:- Peça ao cliente o código que ele recebeu.
- Envie o código em
POST /v2/orders/{id}/confirm. - Se o código expirar, gere outro com
POST /v2/orders/{id}/confirm/resend.
Nenhum pagamento é cobrado antes da confirmação. O código de verificação tem prioridade sobre o QR Code PIX. A verificação por código não gera webhook no formato v2: ela gera
order.challenged no formato v1, inclusive a cada reenvio do código. Acompanhe pelo next_action da resposta.Fluxo de um pedido
Limites e bloqueios
- Por comprador:
POST /v2/ordersaceita no máximo 2 tentativas por minuto do mesmo comprador (e-mail ou documento) para os mesmos itens. Acima disso, a resposta é429(rate_limit_exceeded) comcustomer_messageeRetry-After. - Bloqueios: conta, item ou cliente bloqueado (e-mail, documento ou BIN do cartão, inclusive de cartão salvo) retorna
403comcustomer_message.
Pontos de atenção
GET /v2/orders/{id}só encontra pedidos criados pela API v2. Pedidos da v1 retornam404.internationalnão tem relação comcurrency: ele só restringe a escolha às adquirentes habilitadas para compra internacional, e uma cobrança em BRL pode ser internacional. Se nenhuma adquirente da conta atender, a resposta é422(acquirer_feature_not_supported). O campo não é devolvido na resposta.- O PayPal processa apenas cobranças em
BRL. Um pedido comcurrencydiferente deBRLprocessado pelo PayPal é recusado, mesmo com a conversão para real: a resposta é402comfailure_reason, como qualquer recusa de pagamento, e não um erro de requisição. - O PayPal nunca é escolhido para pedidos com dois ou mais pagamentos, porque não tem as capacidades exigidas por esse tipo de pedido. Ele atende pedidos com um único pagamento com cartão. Se o PayPal for a única adquirente da conta, um pedido com dois ou mais pagamentos retorna
422(acquirer_feature_not_supported). É uma limitação do PayPal, não uma falha. - Os pedidos da v2 não salvam cartão. O
idde um cartão salvo vem dePOST /v2/cards, de uma assinatura ou de um cartão salvo no checkout da v1. - Quando o PIX de um pedido com vários pagamentos expira sem ser pago, o pedido é encerrado: ele fica
canceledemGET /v2/orders/{id}e a autorização do cartão é desfeita. O webhook que chega éorder.failed, não um evento de cancelamento — a v2 não temorder.canceled. Status e evento diferem de propósito: em ambos os casos a venda não se concretizou.
Erros específicos
Resposta (HTTP 422)
