Pagamentos — API Pública v1

Dois endpoints formam o fechamento do checkout:

Endpoint	Função
`POST /order/{uuid}/payment-data/`	Simula a forma de pagamento: seleciona o método, calcula parcelas, descontos e juros e devolve os totais finais.
`POST /order/{uuid}/payments/`	Processa o pagamento, gera o pedido e devolve o link do próximo passo.

Base URL

https://{sua-loja}/api/v1/public/

Identificação do cliente

Envie o header Authorization: Bearer {access_token} obtido no Login (SSO). O processamento exige um cliente identificado, com cadastro completo e endereço de entrega válido.

Os valores de group, id e installments vêm de payment_data.payments[] do carrinho (ver Carrinho).

`POST /order/{uuid}/payment-data/`

Define a forma de pagamento e devolve o carrinho com totalizers recalculados e payment_selected.

Body

{
  "group": "CartaoDeCredito",
  "payments": [
    { "bin": "411111", "value": 199.90, "installments": 3 }
  ]
}

Campo	Descrição
`group`	Grupo da forma de pagamento (`CartaoDeCredito`, `CartaoDeDebito`, `PIX`, `Boleto`, `GiftCard`, ...).
`id`	ID da forma de pagamento em `payment_data.payments[]`, quando o grupo tem mais de uma opção.
`payments[]`	Um item por cartão. `bin` (6 primeiros dígitos) ou `token` (cartão salvo), `value` e `installments` (default `1`).

Grupos

`group`	Comportamento
`CartaoDeCredito`	Identifica a bandeira pelo `bin`/`token`, calcula as parcelas e aplica desconto ou juros da forma escolhida.
`CartaoDeDebito`	Idem, sem parcelamento.
`PrivateLabel`	Cartão da loja.
`GiftCard`	Adiciona ou remove um vale-presente. Adicionar: `{"group": "GiftCard", "action": "add", "code": "<uuid do vale>"}`. Remover: `{"group": "GiftCard", "action": "remove", "id": "<uuid do item em payment_data.giftcards[]>"}`. O saldo aplicado abate `totalizers.total_payment`.
Demais (`PIX`, `Boleto`, ...)	Aplica o desconto configurado para a forma.

Resposta `200 OK`

O objeto completo do carrinho mais:

{
  "payment_selected": {
    "group": "CartaoDeCredito",
    "cards": [
      {
        "card_number": { "flag": "Visa", "id": 4 },
        "installments": [
          { "parcel": 1, "value": 199.90, "total": 199.90, "interest_rate": 0.0 },
          { "parcel": 3, "value": 66.63, "total": 199.90, "interest_rate": 0.0 }
        ]
      }
    ]
  },
  "totalizers": {
    "total_price": 199.90,
    "total_payment": 199.90,
    "payment_discount": 0.0,
    "interest": 0.0
  }
}

Mensagem	Causa
`Login Requerido.` (`login_required: true`)	O BIN exige cliente identificado.
`Valor dos pagamentos estão divergentes do valor total do pedido!`	A soma de `payments[].value` difere de `totalizers.total_payment`.
`Código do Vale {code} é inválido.` / `Vale não encontrado.` / `Este Vale já esta em uso.`	Vale-presente inválido, inexistente ou já aplicado em outro carrinho. Sucesso responde `Vale adicionado com sucesso.` ou `Vale removido com sucesso.` com `level: "SUCCESS"`.

`POST /order/{uuid}/payments/`

Processa o pagamento e gera o pedido.

Headers

Header	Descrição
`Authorization`	`Bearer {access_token}`.
`X-Idempotency-Key`	Recomendado. Chave única por tentativa (ex.: UUID). Uma repetição com a mesma chave dentro de 24 h não cria nova cobrança e responde `Este pagamento já foi processado, verifique seus pedidos antes de tentar novamente.`
`User-Agent`	Obrigatório. Requisições sem `User-Agent` são rejeitadas.

Body

Um array com um objeto por forma de pagamento (normalmente um só; dois em pagamento com dois cartões).

Cartão de crédito

[
  {
    "group": "CartaoDeCredito",
    "channel": "APP",
    "value": 199.90,
    "installments": 3,
    "card_number": "4111111111111111",
    "card_holders_name": "CAROLINE TARTARO",
    "exp_date_0": "12",
    "exp_date_1": "2030",
    "card_code": "123",
    "document": "12345678909",
    "save": false
  }
]

Campo	Descrição
`group`	Grupo selecionado na simulação.
`channel`	Canal de venda. Integrações servidor-a-servidor devem enviar `APP`; nesse canal o reCAPTCHA e o token de sessão do checkout web não são exigidos.
`value`	Valor cobrado nesta forma. A soma de todas as formas deve bater com `totalizers.total_payment`.
`installments`	Número de parcelas.
`card_number`, `card_holders_name`, `exp_date_0` (mês), `exp_date_1` (ano com 4 dígitos), `card_code`, `document` (CPF do titular)	Dados do cartão.
`token`	Alternativa aos dados do cartão: `token` de um item de `payment_data.saved_cards[]`.
`save`	`true` para salvar o cartão para compras futuras (aparece depois em `payment_data.saved_cards[]`).
`observation`	Opcional. Observação gravada no pedido.

Cartão de débito usa group: "CartaoDeDebito" e os mesmos campos, sem installments.

PIX, boleto e outras formas sem cartão

[
  { "group": "PIX", "id": 12, "channel": "APP", "value": 199.90 }
]

Vale-presente

Vales aplicados na simulação (GiftCard) são consumidos automaticamente; informe em value apenas o restante a pagar nas demais formas.

Resposta `200 OK`

A resposta tem sempre HTTP 200. O resultado está no corpo:

Pedido gerado

{
  "order": "a1b2c3d4-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "links": [
    { "method": "GET", "rel": "_self", "href": "/checkout/sucesso/a1b2c3d4-.../" }
  ]
}

order é o UUID do pedido. Consulte o detalhe em Consulta de pedidos. Pagamentos aprovados na hora (cartão) geram o pedido já com a transação vinculada; PIX e boleto geram o pedido pendente, com os dados para pagamento em payments[] do pedido.

Redirecionamento externo (3DS, carteira digital, link de pagamento)

{
  "links": [ { "method": "GET", "rel": "_self", "href": "https://gateway.exemplo.com/..." } ]
}

Leve o cliente para href; ao concluir, ele retorna para a loja e o pedido é gerado.

Pendência de cadastro ou entrega

Sem mensagem de erro, mas com links[].href apontando para /checkout/cadastro/, /checkout/endereco/ ou /checkout/carrinho/: faltam dados do cliente, endereço válido, frete selecionado ou há item sem estoque. Corrija pelos endpoints correspondentes e repita.

Erro

O objeto completo do carrinho com messages[]:

Mensagem	Causa
`Seu pagamento já está em processamento, por favor aguarde alguns instantes.`	Já existe uma requisição de pagamento em andamento para este carrinho. Aguarde a resposta dela; não reenvie.
`Este pagamento já foi processado, verifique seus pedidos antes de tentar novamente.`	`X-Idempotency-Key` repetida.
`Cliente bloqueado, não é possível realizar o pagamento.`	Cliente bloqueado na loja.
`Valor dos pagamentos estão divergentes do valor total do pedido.`	Soma de `value` diferente do total.
`Não é permitido informar o mesmo cartão mais de uma vez no pagamento.`	Dois itens do array com o mesmo cartão.
`Alguns dos items em seu carrinho não possuem a quantidade selecionada em estoque.`	Estoque mudou após montar o carrinho.
`Forma de pagamento não encontrada!`	`group`/`id` inválido ou forma inativa.
`{campo}: {erro}`	Validação dos dados do cartão (número, validade, código, CPF).
Mensagem do adquirente, com `type: "payment_unauthorized"`	Transação negada. `links[]` aponta de volta para o passo de pagamento.
`Erro ao gerar o pedido no OMS`	Falha interna ao criar o pedido; cobranças já aprovadas são estornadas automaticamente.
`{"message": "JSON mal formatado."}`	Body inválido, `User-Agent` ausente ou cliente sem e-mail válido.

Observações gerais

Sempre chame payment-data antes de payments: é ela que grava a forma selecionada e calcula os totais que serão validados.
Qualquer alteração em itens, cupons, serviços ou frete zera desconto e juros de pagamento. Refaça a simulação.
Há limite de tentativas de pagamento por cliente, cartão e carrinho em 24 h. Ao excedê-lo, as requisições passam a ser recusadas até a janela expirar.

Pagamentos — API Pública v1

POST /order/{uuid}/payment-data/

Body

Grupos

Resposta 200 OK

POST /order/{uuid}/payments/

Headers

Body

Cartão de crédito

PIX, boleto e outras formas sem cartão

Vale-presente

Resposta 200 OK

Observações gerais

`POST /order/{uuid}/payment-data/`

Resposta `200 OK`

`POST /order/{uuid}/payments/`

Resposta `200 OK`