API atual/Referência completa/Pedidos e conta do cliente

Retomar pagamento

Consulta, refaz ou desiste do pagamento de um pedido pendente, com cliente logado ou visitante.

O cliente fecha o pedido, o PIX expira, o cartão é recusado ou o aplicativo cai. O pedido continua lá, pendente, e esta é a forma de o cliente pagar de novo sem montar o carrinho outra vez, inclusive trocando a forma de pagamento. A janela de retomada é aberta quando o pedido é criado e, no pedido feito por Criar pedido, dura 24 horas.

As três rotas aceitam cliente logado ou visitante. O dono logado basta com o token. O visitante prova que é o comprador com o token de retomada (que vem em payment_retry_token quando ele abre o pedido, ou no link de retomada) ou com o e-mail da compra. Quem não tem nenhuma das duas credenciais recebe 404 not found, como se o pedido não existisse.

GET/api/v1/storefront/orders/{id}/payment-retryAutenticada

Consulta se o pedido pode ter o pagamento retomado

Parâmetros de caminho

iduuidobrigatório

Id do pedido.

Parâmetros de consulta

tokenstring

Visitante: token de retomada do pedido.

emailstring

Visitante: e-mail usado na compra (alternativa ao token).

bash

curl "$BASE_URL/api/v1/storefront/orders/$ORDER_ID/payment-retry" \
  -H "Authorization: Bearer $TOKEN"

200Situação da retomada

json

{
  "retryable": true,
  "expires_at": "2026-10-12T20:55:25Z",
  "total_cents": 5266,
  "available_methods": [
    { "code": "pix", "name": "PIX", "provider": "pix", "gateway": "pix", "total_cents": 5266, "adjustment_cents": 0 },
    { "code": "credit_card", "name": "Cartão de Crédito", "provider": "credit_card", "gateway": "pagarme", "total_cents": 5266, "adjustment_cents": 0 }
  ]
}

Campos da resposta

retryableboolean

true enquanto a janela está aberta, o pedido não foi cancelado e o pagamento não foi capturado nem autorizado. Com false, não ofereça o botão.

expires_atstring

Fim da janela, RFC 3339.

total_centsinteger

Total do pedido gravado na compra, em centavos. Nunca é recalculado.

available_methodsarray

Formas de pagamento que dá para usar agora. Cada uma traz o code (o valor para mandar em payment_method), name, provider, gateway, total_cents (o que aquela forma cobraria, já com o desconto ou o acréscimo dela sobre a base do pedido) e adjustment_cents (a diferença, negativa quando é desconto).

Status	Quando	Corpo
404	Pedido inexistente, ou credencial que não comprova que o pedido é seu	`{"error":"not found"}`

POST/api/v1/storefront/orders/{id}/payment-retryAutenticada

Paga o pedido de novo (PIX ou cartão)

Cria uma nova tentativa de pagamento para o pedido. Com PIX, a resposta traz o QR code e o copia-e-cola novos. Com cartão, a cobrança é feita na hora e status diz se foi aprovada. O estoque dos itens é conferido de novo: se acabou, a resposta é 422 out_of_stock.

Parâmetros de caminho

iduuidobrigatório

Id do pedido.

Corpo da requisição

payment_methodstringpadrão: pix

Código de uma das available_methods. Vazio vale pix.

tokenstring

Visitante: token de retomada.

emailstring

Visitante: e-mail da compra (alternativa ao token).

card_tokenstring

Cartão: token do cartão gerado pelo gateway no navegador ou aplicativo. Prefira sempre este caminho: assim o número do cartão nunca passa pelo seu servidor.

card_numberstring

Cartão sem token: número do cartão. Use só se a sua integração tem a certificação necessária.

card_holderstring

Nome impresso no cartão.

card_exp_monthstring

Mês de validade, 2 dígitos.

card_exp_yearstring

Ano de validade.

card_cvvstring

Código de segurança.

installmentsinteger

Parcelas no cartão.

bash

curl -X POST "$BASE_URL/api/v1/storefront/orders/$ORDER_ID/payment-retry" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "payment_method": "pix"
}'

200Nova tentativa criada

json

{
  "attempt_id": "c8f2b1a7-5e3d-4b9c-a0f6-1d2e3f4a5b6c",
  "status": "pending",
  "payment_data": {
    "qr_code": "00020126580014br.gov.bcb.pix...",
    "copy_paste": "00020126580014br.gov.bcb.pix...",
    "expires_at": "2026-10-11T21:25:25Z"
  }
}

O conteúdo de payment_data depende do meio de pagamento e do gateway da loja (no PIX, o código e a expiração; no cartão, o resultado da operadora). Leia status e mostre o que vier em payment_data; confirme o pagamento consultando o pedido (Consultar pedido), que é a fonte de verdade.

Status	Quando	Corpo
404	Pedido inexistente ou credencial inválida	`{"error":"not found"}`
409	O pedido já está pago	`{"error":"order_already_paid"}`
409	Já existe uma tentativa em andamento; tente de novo depois do tempo indicado	`{"error":"in_progress","retry_after_ms":1500}`
422	Janela encerrada, pedido cancelado ou já pago	`{"error":"order is not resumable"}`
422	Forma de pagamento que não está em `available_methods`	`{"error":"payment method not available"}`
422	Um item ficou sem estoque	`{"error":"out_of_stock","product":"Caneca Exemplo"}`
502	O gateway recusou ou falhou	`{"error":"<mensagem do gateway>"}`

POST/api/v1/storefront/orders/{id}/payment-retry/cancelAutenticada

Desiste do pagamento e cancela o pedido

Cancela um pedido ainda não pago cuja janela de retomada está aberta. É o botão "Desistir da compra" da tela de retomada. Diferente de Cancelar pedido, não passa pela política de cancelamento da loja nem por análise: como não há dinheiro a devolver, o pedido é cancelado e o estoque volta.

Parâmetros de caminho

iduuidobrigatório

Id do pedido.

Corpo da requisição

tokenstring

Visitante: token de retomada.

emailstring

Visitante: e-mail da compra.

bash

curl -X POST "$BASE_URL/api/v1/storefront/orders/$ORDER_ID/payment-retry/cancel" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

200Pedido cancelado

json

{ "cancelled": true }

Status	Quando	Corpo
404	Pedido inexistente ou credencial inválida	`{"error":"not found"}`
422	Pedido não retomável (janela encerrada ou já pago), ou falha ao cancelar	`{"error":"order is not resumable"}` / `{"error":"could not cancel order"}`

Veja também

Retomar pagamento

Consulta, refaz ou desiste do pagamento de um pedido pendente, com cliente logado ou visitante.

GET/api/v1/storefront/orders/{id}/payment-retryAutenticada

Consulta se o pedido pode ter o pagamento retomado

Parâmetros de caminho

iduuidobrigatório

Id do pedido.

Parâmetros de consulta

tokenstring

Visitante: token de retomada do pedido.

emailstring

Visitante: e-mail usado na compra (alternativa ao token).

bash

curl "$BASE_URL/api/v1/storefront/orders/$ORDER_ID/payment-retry" \
  -H "Authorization: Bearer $TOKEN"

200Situação da retomada

json

{
  "retryable": true,
  "expires_at": "2026-10-12T20:55:25Z",
  "total_cents": 5266,
  "available_methods": [
    { "code": "pix", "name": "PIX", "provider": "pix", "gateway": "pix", "total_cents": 5266, "adjustment_cents": 0 },
    { "code": "credit_card", "name": "Cartão de Crédito", "provider": "credit_card", "gateway": "pagarme", "total_cents": 5266, "adjustment_cents": 0 }
  ]
}

Campos da resposta

retryableboolean

true enquanto a janela está aberta, o pedido não foi cancelado e o pagamento não foi capturado nem autorizado. Com false, não ofereça o botão.

expires_atstring

Fim da janela, RFC 3339.

total_centsinteger

Total do pedido gravado na compra, em centavos. Nunca é recalculado.

available_methodsarray

Status	Quando	Corpo
404	Pedido inexistente, ou credencial que não comprova que o pedido é seu	`{"error":"not found"}`

POST/api/v1/storefront/orders/{id}/payment-retryAutenticada

Paga o pedido de novo (PIX ou cartão)

Parâmetros de caminho

iduuidobrigatório

Id do pedido.

Corpo da requisição

payment_methodstringpadrão: pix

Código de uma das available_methods. Vazio vale pix.

tokenstring

Visitante: token de retomada.

emailstring

Visitante: e-mail da compra (alternativa ao token).

card_tokenstring

Cartão: token do cartão gerado pelo gateway no navegador ou aplicativo. Prefira sempre este caminho: assim o número do cartão nunca passa pelo seu servidor.

card_numberstring

Cartão sem token: número do cartão. Use só se a sua integração tem a certificação necessária.

card_holderstring

Nome impresso no cartão.

card_exp_monthstring

Mês de validade, 2 dígitos.

card_exp_yearstring

Ano de validade.

card_cvvstring

Código de segurança.

installmentsinteger

Parcelas no cartão.

bash

curl -X POST "$BASE_URL/api/v1/storefront/orders/$ORDER_ID/payment-retry" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "payment_method": "pix"
}'

200Nova tentativa criada

json

{
  "attempt_id": "c8f2b1a7-5e3d-4b9c-a0f6-1d2e3f4a5b6c",
  "status": "pending",
  "payment_data": {
    "qr_code": "00020126580014br.gov.bcb.pix...",
    "copy_paste": "00020126580014br.gov.bcb.pix...",
    "expires_at": "2026-10-11T21:25:25Z"
  }
}

Status	Quando	Corpo
404	Pedido inexistente ou credencial inválida	`{"error":"not found"}`
409	O pedido já está pago	`{"error":"order_already_paid"}`
409	Já existe uma tentativa em andamento; tente de novo depois do tempo indicado	`{"error":"in_progress","retry_after_ms":1500}`
422	Janela encerrada, pedido cancelado ou já pago	`{"error":"order is not resumable"}`
422	Forma de pagamento que não está em `available_methods`	`{"error":"payment method not available"}`
422	Um item ficou sem estoque	`{"error":"out_of_stock","product":"Caneca Exemplo"}`
502	O gateway recusou ou falhou	`{"error":"<mensagem do gateway>"}`

POST/api/v1/storefront/orders/{id}/payment-retry/cancelAutenticada

Desiste do pagamento e cancela o pedido

Parâmetros de caminho

iduuidobrigatório

Id do pedido.

Corpo da requisição

tokenstring

Visitante: token de retomada.

emailstring

Visitante: e-mail da compra.

bash

curl -X POST "$BASE_URL/api/v1/storefront/orders/$ORDER_ID/payment-retry/cancel" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

200Pedido cancelado

json

{ "cancelled": true }

Status	Quando	Corpo
404	Pedido inexistente ou credencial inválida	`{"error":"not found"}`
422	Pedido não retomável (janela encerrada ou já pago), ou falha ao cancelar	`{"error":"order is not resumable"}` / `{"error":"could not cancel order"}`