Skip to main content

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.
201 Created não significa pago. A resposta traz o resultado da autorização. Um pagamento com cartão aceito pode ficar em processing até a confirmação da adquirente. Use os webhooks order.paid e charge.paid para saber quando o pedido foi pago.

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)

Pular a análise de fraude exige permissão na sua conta. Sem ela, a resposta é 422 (fraud_bypass_not_allowed).

Regras de validação

  • A soma de items[].amount × items[].quantity precisa ser igual à soma de payments[].amount.
  • Um pagamento com cartão precisa de card.token ou de todos os dados do cartão.
  • Quando o pedido tem cartão, o pix_expiration de 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[].amount precisa ser igual ao amount do 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 ter options.charge_remainder_fee: true e pelo menos um precisa ter options.liable: true. Um split que não pode ser aplicado retorna 422 (split_error).

Exemplos

Cartão com captura manual

Request
Resposta (HTTP 201)

PIX

Pagamento
Resposta (HTTP 201)

Cartão + PIX

Envie dois itens em payments. 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).
Um pedido com vários pagamentos é tudo ou nada. Se um pagamento for recusado, os que já foram autorizados são desfeitos e o pedido falha. O mesmo vale para a captura: se a adquirente recusar a captura de um cartão, os demais são desfeitos e o pedido fica failed, com o motivo em failure_reason.

Moeda e conversão

O currency 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 de payments é 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.
Um pedido em requires_action nem sempre traz um next_action. Quando o código de verificação já foi confirmado ou expirou, o pedido continua em requires_action e o next_action vem null. Trate o nulo: gere um novo código com POST /v2/orders/{id}/confirm/resend em vez de assumir que o objeto existe.

QR Code PIX

Exiba o 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:
  1. Peça ao cliente o código que ele recebeu.
  2. Envie o código em POST /v2/orders/{id}/confirm.
  3. 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.
O reenvio do código aceita 5 requisições por minuto por IP de origem. O limite não é separado por conta: se a sua plataforma atende várias contas a partir do mesmo servidor, todas dividem os mesmos 5 reenvios por minuto. Ao exceder, a resposta é 429 fora do envelope de erro da v2 ({ "message": "Too Many Attempts." }).

Fluxo de um pedido


Limites e bloqueios

  • Por comprador: POST /v2/orders aceita 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) com customer_message e Retry-After.
  • Bloqueios: conta, item ou cliente bloqueado (e-mail, documento ou BIN do cartão, inclusive de cartão salvo) retorna 403 com customer_message.
Veja todos os limites em Idempotência e limites.

Pontos de atenção

  • GET /v2/orders/{id} só encontra pedidos criados pela API v2. Pedidos da v1 retornam 404.
  • international não tem relação com currency: 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 com currency diferente de BRL processado pelo PayPal é recusado, mesmo com a conversão para real: a resposta é 402 com failure_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 id de um cartão salvo vem de POST /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 canceled em GET /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 tem order.canceled. Status e evento diferem de propósito: em ambos os casos a venda não se concretizou.

Erros específicos

Resposta (HTTP 422)
Veja o catálogo completo em Erros.