Você está no sandbox: ambiente de testes. Use chaves rk_sandbox_. Nada aqui movimenta dinheiro real.
URL basehttps://sandbox-api.rcheckout.com.br
API REST/JSON para criar e acompanhar cobranças por boleto, PIX e cartão.
Só transações: cada chave enxerga apenas as cobranças do próprio cliente.
Valores em reais (BRL), com no máximo 2 casas decimais (ex.: 150.01, 150 ou "150.01"). Datas em ISO 8601 (UTC) e AAAA-MM-DD.
document (CPF/CNPJ) e phone são apenas dígitos, sem pontuação. O CEP ainda pode ir com ou sem máscara.
Um validation_error devolve um único campo inválido por vez (field + reason).
Todo POST exige o cabeçalho Idempotency-Key.
O ambiente (sandbox ou produção) é definido pela URL informada pela Rapp e pela chave:
rk_sandbox_... só funciona no sandbox e rk_live_... só em produção.
Toda resposta traz o cabeçalho X-Rapp-Environment.
A chave rk_sandbox_... é emitida pela equipe da Rapp e entregue por canal seguro. Ela aparece uma única vez: guarde no cofre de segredos do seu servidor. Mais sobre chaves.
Comece por um PIX ou um boleto. Todo POST exige o cabeçalho Idempotency-Key e os valores vão em reais, com no máximo 2 casas decimais.
5
Teste no Postman
A coleção reúne todas as rotas desta página, com os exemplos do contrato. Importe os dois arquivos no Postman (Importar), selecione o ambiente de sandbox e cole a sua chave rk_sandbox_... na variável apiKey. Os valores dos exemplos estão em reais (por exemplo, 150.00 é R$ 150,00), não em centavos.
Este guia mostra, passo a passo, como o seu sistema cria e acompanha cobranças por boleto, PIX e cartão na API da Rapp Checkout. Todos os exemplos abaixo usam exatamente os campos que a API envia e recebe (eles são conferidos por testes automáticos contra o código).
O contrato técnico completo, em formato OpenAPI 3, está em ../openapi.yaml. Você pode importá-lo no Postman, Insomnia ou em um gerador de cliente. No manual publicado também há o botão Baixar coleção Postman, com o ambiente de sandbox já apontando para https://sandbox-api.rcheckout.com.br: importe os dois arquivos, selecione o ambiente e preencha só a variável apiKey. Os valores dos exemplos estão em reais (ex.: 150.00 = R$ 150,00), não em centavos.
Para testar sem escrever código, use Baixar coleção Postman e Baixar environment no manual (em "Primeiros passos"). A coleção é gerada do mesmo contrato a cada versão da API e já traz todas as rotas com exemplos. No environment, preencha só apiKey com a sua chave. Os valores vão em reais: "amount": 1.00 é R$ 1,00.
API REST com JSON. Você envia JSON comum e recebe JSON comum.
A API cuida só de transações: criar, consultar e listar cobranças, e (no sandbox) cancelar e simular pagamento.
Cada resposta traz todos os dados da transação: status, valores, linha digitável, código de barras e PDF do boleto, PIX copia-e-cola e expiração, dados de autorização do cartão e datas.
Cada chave enxerga apenas as cobranças do próprio cliente.
As mudanças de status (pagamento, cancelamento, expiração etc.) chegam no seu sistema por webhook assinado.
A Rapp informa para você duas URLs base e duas chaves, uma para cada ambiente:
Ambiente
Para quê
Prefixo da chave
Dinheiro real
sandbox
Desenvolver e testar a integração
rk_sandbox_
Não
production
Cobrar seus clientes de verdade
rk_live_
Sim
A URL base do sandbox é https://sandbox-api.rcheckout.com.br. A URL de produção é informada pela Rapp quando a sua integração for liberada.
Neste guia, a URL base aparece como a variável $RAPP_API_URL e a chave como $RAPP_API_KEY:
Terminal
# Sandbox (a chave é informada pela Rapp)export RAPP_API_URL="https://sandbox-api.rcheckout.com.br"export RAPP_API_KEY="rk_sandbox_..."
Regras importantes:
Uma chave só funciona no ambiente dela. Chave rk_live_ na URL de sandbox (ou o contrário) recebe 401 environment_mismatch.
Cobranças, cardTokens e configurações de webhook de um ambiente não aparecem no outro.
Toda resposta traz o cabeçalho X-Rapp-Environment: sandbox ou X-Rapp-Environment: production, e toda cobrança traz o campo "environment".
A rota de simulação (/v1/sandbox/charges/{id}/simulate-payment) não existe em produção (responde 404). Cancelamento e estorno existem nos dois ambientes.
Para conferir onde você está e o que a instância oferece, use GET /v1/environment.
A chave é emitida pela equipe da Rapp e entregue por canal seguro. Ela aparece uma única vez: guarde no cofre de segredos do seu sistema (variável de ambiente, secret manager). A Rapp guarda só um hash e não consegue recuperá-la.
Formato: rk_sandbox_<16 caracteres>_<43 caracteres> ou rk_live_<16 caracteres>_<43 caracteres>.
Escopos possíveis:
charges:read — consultar e listar cobranças;
charges:write — criar cobranças (e, no sandbox, cancelar e simular pagamento).
Opcionalmente a chave pode ser limitada a uma lista de IPs de origem. Chamadas de outro IP recebem 403 ip_not_allowed.
Para trocar uma chave (rotação) ou revogar uma chave vazada, peça à Rapp. A revogação vale na hora.
Nunca use a chave no navegador ou no aplicativo do seu cliente: as chamadas devem sair do seu servidor.
Valores em reais, com no máximo 2 casas decimais: R$ 150,00 = 150 ou 150.00; R$ 150,01 = 150.01. Também aceita o valor como texto ("150.01"). A API converte internamente para centavos inteiros, sem aritmética de ponto flutuante.
Mudança de contrato: até esta versão amount era inteiro em centavos (15000 = R$ 150,00). Agora 15000 significa R$ 15.000,00. A API está só em sandbox e ainda não há chaves de cliente, por isso o significado do campo foi trocado em vez de criar um campo novo ou uma versão /v2.
Datas: vencimento em AAAA-MM-DD; datas e horas em ISO 8601 UTC (2026-11-16T13:05:12Z).
IDs têm prefixo: chg_ (cobrança), ctok_ (cartão salvo), evt_ (evento de webhook), req_ (requisição).
Documento (CPF/CNPJ) e telefone: apenas dígitos, sem ponto, traço, barra, parênteses, espaço ou +. CPF com 11 dígitos, CNPJ com 14; telefone com DDD, 10 a 13 dígitos. Valores formatados são recusados (400 validation_error). A API não remove a pontuação sozinha.
CEP ainda pode ir com ou sem pontuação; a API normaliza.
Corpo de até 64 KB.
Campos desconhecidos no corpo são ignorados; campos da resposta podem ganhar novos itens no futuro — não quebre se aparecer um campo novo.
Cobrança × transação: uma cobrança (charge) agrupa transações (transactions). Hoje cada cobrança nasce com uma transação; o status da cobrança é o da transação.
Todo POST exige o cabeçalho Idempotency-Key com um valor único por operação no seu sistema (1 a 255 caracteres ASCII visíveis, sem espaço; um UUID ou pedido-123-boleto funcionam bem). A comparação diferencia maiúsculas de minúsculas: Pedido-1 e pedido-1 são chaves diferentes. Espaços nas pontas do cabeçalho são ignorados. Isso evita cobrança duplicada quando a rede cai e você repete a chamada.
Situação
Resposta
Primeira chamada com a chave
Executa normalmente
Repetição com o mesmo corpo (sem expiração automática)
Mesma resposta da primeira, com Idempotent-Replayed: true; nada é criado de novo
Repetição com corpo diferente
422 idempotency_key_reused
Repetição enquanto a primeira ainda processa
409 idempotency_in_progress (espere e repita)
Validação falhou antes do envio ao provedor
Corrija os campos indicados; a reserva pode ser liberada
Resultado incerto depois de iniciar o envio
409 idempotency_outcome_unknown: preserve a chave e solicite conciliação; não crie uma nova cobrança
A chave vale por cliente. Confirmações financeiras não expiram automaticamente. Resultado desconhecido exige conciliação, nunca uma nova chave para repetir a mesma operação. Em cobranças de cartão, o número e o CVV não entram no controle de idempotência (só os 4 últimos dígitos, a validade e o nome).
Cada chave tem um limite de requisições por minuto (padrão 120/min, ajustável pela Rapp). O limite atual aparece em X-RateLimit-Limit e em GET /v1/environment. Ao passar do limite, a API responde:
JSON
{"error":{"code":"rate_limited","message":"Limite de requisições da chave excedido. Tente novamente em instantes.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
com status 429 e o cabeçalho Retry-After (em segundos). Espere esse tempo antes de tentar de novo. Para acompanhar pagamentos, prefira webhooks a consultas repetidas.
{"error":{"code":"codigo_estavel","message":"Texto em português para pessoas.","details":[],"requestId":"req_..."}}
Trate pelo code (estável). O message pode mudar.
Em validation_error, a API devolve um único campo inválido por vez (field + reason + message). Corrija esse campo e envie de novo; se houver outro problema, ele aparece na próxima resposta.
Em provider_rejected, details traz o que o processador recusou (providerField, providerCode, message).
Guarde o requestId para falar com o suporte.
HTTP
code
Quando acontece
O que fazer
400
validation_error
Campo ausente ou inválido
Corrija os campos de details
400
invalid_json
Corpo não é JSON válido
Corrija o JSON
400
idempotency_key_required
POST sem Idempotency-Key
Envie o cabeçalho
401
unauthorized
Chave ausente, inválida ou revogada
Confira a chave
401
environment_mismatch
Chave de outro ambiente
Use a URL do ambiente da chave
403
insufficient_scope
Chave sem o escopo da operação
Peça o escopo à Rapp
403
ip_not_allowed
IP de origem fora da lista da chave
Peça a liberação do IP
403
client_inactive
Cliente desativado
Fale com a Rapp
403
client_not_configured
Cliente sem estabelecimento configurado
Fale com a Rapp
403
sandbox_only
Operação exclusiva do sandbox
Use o sandbox
404
not_found
Cobrança não existe (ou é de outro cliente), ou rota inexistente neste ambiente
Confira o id e a URL
405
method_not_allowed
Método HTTP errado para a rota
Confira o método
409
idempotency_outcome_unknown
Resultado financeiro não confirmado
Preserve a chave e solicite conciliação; não crie outra cobrança
409
idempotency_in_progress
Mesma Idempotency-Key ainda processando
Espere e repita
409
charge_not_cancelable
Cobrança já paga ou encerrada
—
409
charge_not_refundable
Cobrança ainda não paga, já estornada por completo, ou sem saldo
—
409
charge_not_payable
Simulação em cobrança que não está awaiting_payment
—
413
payload_too_large
Corpo acima de 64 KB
Reduza o corpo
415
unsupported_media_type
Corpo sem Content-Type: application/json
Envie o cabeçalho
422
idempotency_key_reused
Mesma chave com corpo diferente
Use uma chave nova
422
card_token_invalid
cardToken não existe para este cliente/ambiente
Envie o cartão de novo
422
simulation_not_supported
Simulação em cobrança de cartão
Simule só boleto/PIX
422
refund_not_supported
Estorno em cobrança de boleto
Estorne só cartão ou Pix
422
cancel_not_confirmed
O processador de pagamentos não confirmou o cancelamento (ex.: boleto já emitido em que só o chargeVoid não altera a transação)
Nada foi gravado; trate o erro e, se for o caso, tente de novo
422
insufficient_receivables
O saldo a receber do estabelecimento não cobre o valor do estorno
Nada foi gravado; tente de novo quando houver saldo, ou peça o estorno pela Rapp
422
provider_rejected
O processador recusou a cobrança ou o estorno
Veja details
429
rate_limited
Limite por minuto excedido
Espere Retry-After
500
internal_error
Erro inesperado na Rapp
Repita; se persistir, envie o requestId
502
provider_unavailable
O processador não respondeu
Repita com a mesma Idempotency-Key
Exemplos:
400 validation_error
JSON
{"error":{"code":"validation_error","field":"payer.document","reason":"invalid_format","message":"Use apenas números, sem pontuação (CPF com 11 dígitos ou CNPJ com 14).","requestId":"req_3b9d0c7a1e2f4a5b"}}
401 environment_mismatch
JSON
{"error":{"code":"environment_mismatch","message":"Este ambiente é sandbox e aceita só chaves rk_sandbox_. Use a URL do ambiente da sua chave.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
403 insufficient_scope
JSON
{"error":{"code":"insufficient_scope","message":"A chave não tem o escopo charges:write.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
404 not_found
JSON
{"error":{"code":"not_found","message":"Cobrança não encontrada.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
422 idempotency_key_reused
JSON
{"error":{"code":"idempotency_key_reused","message":"Esta Idempotency-Key já foi usada com outro corpo de requisição.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
422 insufficient_receivables
JSON
{"error":{"code":"insufficient_receivables","message":"O saldo a receber não cobre o valor do estorno.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
422 provider_rejected
JSON
{"error":{"code":"provider_rejected","message":"O processador de pagamentos recusou a cobrança.","details":[{"providerField":"amount","message":"Valor abaixo do mínimo permitido.","providerCode":"invalid"}],"requestId":"req_3b9d0c7a1e2f4a5b"}}
502 provider_unavailable
JSON
{"error":{"code":"provider_unavailable","message":"O processador de pagamentos não respondeu. Tente novamente com a mesma Idempotency-Key.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
A API valida toda a entrada da superfície pública: corpo, query, id no caminho e os cabeçalhos relevantes (Authorization, Content-Type e Idempotency-Key). Outros cabeçalhos HTTP comuns (por exemplo User-Agent ou Accept) são ignorados.
Quando um campo é inválido, a resposta é um único400 validation_error, com o primeiro problema encontrado, nesta ordem determinística:
Cabeçalhos relevantes, quando se aplicam à rota (Idempotency-Key nas operações POST tem código próprio, idempotency_key_required).
id no caminho (formato chg_ seguido de letras, números ou _).
Query: os parâmetros conhecidos, nesta ordem — method, status, createdFrom, createdTo, externalReference, page, pageSize — e, por último, qualquer parâmetro desconhecido.
Corpo: objeto JSON; depois os campos conhecidos na ordem do contrato (por exemplo, no boleto: amount, description, externalReference, payer e seus campos, dueDate, pixEnabled); por último, campos desconhecidos daquele objeto.
reason é estável, para o seu sistema tratar por programa:
reason
Significado
required
Campo obrigatório ausente
invalid_type
Tipo errado (ex.: número onde se espera texto)
invalid_format
Formato inválido (documento com pontuação, data, notação científica, id)
unexpected_field
Campo ou parâmetro que a API não reconhece
out_of_range
Fora da faixa ou do tamanho (mais de 2 casas no valor, texto longo demais, pageSize acima de 100)
invalid_value
Valor conhecido, mas não aceito (enum, zero ou negativo em amount, vencimento no passado)
Campos desconhecidos são recusados, não ignorados: um typo no nome do campo não pode passar em silêncio. JSON malformado responde 400 invalid_json. Corpo acima de 64 KB responde 413 payload_too_large. Content-Type diferente de application/json (quando há corpo) responde 415 unsupported_media_type.
O envelope de validation_error não inclui details e nunca revela stack, SQL ou caminhos internos.
Mostre ao pagador transactions[0].boleto.digitableLine (linha digitável) e/ou o link transactions[0].boleto.pdfUrl (URL da Rapp: GET /v1/charges/{id}/transactions/{transactionId}/boleto.pdf, autenticado com a mesma chave de API).
Use transactions[0].pix.copyPaste para o botão "copiar código" e transactions[0].pix.qrCodeText para desenhar o QR Code (qualquer biblioteca de QR Code serve). expiresAt indica até quando o PIX pode ser pago.
O cardToken é devolvido quando o processador confirma o perfil de pagamento (PaymentProfile.id) na primeira cobrança com persist: true. Nas próximas cobranças, envie esse cardToken: a API reapresenta o ID do perfil (paymentProfileId) e o cartão é reutilizado, mesmo que o processador não devolva um campo token. O cardToken só funciona para o cliente e o ambiente que o receberam. O status de cartão pode começar como pending (análise de risco) e mudar para paid ou rejected; acompanhe pelo webhook.
POST /v1/charges/{id}/cancel — sem corpo. Existe no sandbox e em produção (features.cancelCharges é sempre true). Só cobranças pending ou awaiting_payment podem ser canceladas.
O processador de pagamentos trata os dois casos de forma diferente: chargeVoid cancela transações ainda agendadas (SCHEDULED); transação já emitida (BILLED, boleto ou Pix com linha digitável/QR) precisa de transactionVoid. A API escolhe a mutation certa e só grava canceled/canceledAt quando o processador de pagamentos devolver a transação como cancelada (VOIDED). Se o processador não confirmar, a resposta é 422 cancel_not_confirmed e nada é alterado aqui.
POST /v1/sandbox/charges/{id}/simulate-payment — sem corpo. Marca um boleto ou PIX como pago no sandbox, para você testar o fluxo de ponta a ponta (inclusive o webhook charge.paid). Não vale para cartão (422 simulation_not_supported) e não existe em produção.
POST /v1/charges/{id}/refund — existe no sandbox e em produção. Estorna a transação da cobrança no processador de pagamentos (transactionRefund). Só cartão ou Pix online em paid ou partially_refunded. Boleto responde 422 refund_not_supported. Sem amount, estorna o saldo restante. reason é informativo (DUPLICATE, FRAUDULENT, REQUESTED_BY_CUSTOMER ou OTHER); o padrão é REQUESTED_BY_CUSTOMER. A cobrança só é atualizada depois da confirmação do processador de pagamentos.
Se o saldo a receber do estabelecimento não cobrir o valor do estorno, a API devolve 422 insufficient_receivables e nada é gravado.
Criada, aguardando emissão ou análise de risco (cartão)
não
awaiting_payment
Boleto/PIX emitido, aguardando pagamento
não
paid
Pago
sim*
partially_refunded
Parte do valor estornada
não
refunded
Valor estornado por completo
sim
canceled
Cancelada antes do pagamento
sim
expired
Venceu sem pagamento
sim
rejected
Recusada (ex.: cartão negado ou análise de risco)
sim
* Uma cobrança paid ainda pode ir para partially_refunded ou refunded se houver estorno, e receber o evento charge.disputed em caso de contestação (chargeback).
Informe à Rapp a URL HTTPS que vai receber os avisos (uma para o sandbox e outra para produção, se quiser) e, opcionalmente, quais eventos deseja (lista vazia = todos). A Rapp devolve um segredo de webhook (whsec_...), mostrado uma única vez, que você usa para validar a assinatura. URLs http:// ou de rede interna não são aceitas.
X-Rapp-Signature tem o formato t=<unix em segundos>,v1=<assinatura>, onde a assinatura é o HMAC-SHA256 em hexadecimal do texto "<t>.<corpo bruto>" usando o seu segredo whsec_....
Leia o corpo bruto exatamente como chegou (antes de converter para JSON).
Separe t e v1 do cabeçalho.
Calcule HMAC-SHA256(segredo, t + "." + corpoBruto) em hexadecimal.
Compare com v1 usando comparação em tempo constante.
Recuse se t tiver mais de 5 minutos de diferença do seu relógio (evita reenvio de mensagens antigas).
Confira o ambiente: GET /v1/environment deve devolver "environment": "sandbox" e os escopos esperados.
Teste os erros de autenticação: chame sem Authorization (espere 401 unauthorized) e com uma chave inventada.
Crie um boleto (seção 9.2) com um externalReference do seu sistema. Guarde o id.
Repita a mesma chamada com a mesma Idempotency-Key: a resposta deve ser igual, com Idempotent-Replayed: true, e nenhuma cobrança nova deve aparecer na listagem.
Envie um corpo inválido (ex.: amount: 0 ou document com pontuação) e confira o 400 validation_error de um campo só (field + reason).
Configure o webhook com a Rapp e confirme que a sua URL valida a assinatura (seção 11.4).
Simule o pagamento (seção 9.9). Confira:
a resposta com "status": "paid";
o webhook charge.paid recebido e validado;
GET /v1/charges/{id} com "status": "paid".
Crie um PIX (seção 9.4), mostre o QR Code a partir de qrCodeText e simule o pagamento.
Crie um boleto híbrido (seção 9.3) e confira boleto.pixCopyPaste.
Liste com filtros e paginação (seção 9.7).
Cancelamento: cancele um boleto não pago e confira o webhook charge.canceled.
Estorno: depois de simular o pagamento de um Pix (ou pagar um cartão), chame POST /v1/charges/{id}/refund e confira refunded ou partially_refunded.
Cartão: crie com card, guarde o cardToken e crie outra cobrança com ele.
Teste o limite: trate 429 respeitando Retry-After.
Teste a queda: simule falha de rede no seu lado e repita com a mesma Idempotency-Key.
Nada no sandbox movimenta dinheiro real. Para repetir este roteiro no Postman, baixe a coleção e o ambiente de sandbox no manual.
Recebi da Rapp a URL de produção e a chave rk_live_, guardada em cofre de segredos (nunca no código, no Git ou no front-end).
GET /v1/environment na URL de produção devolve "environment": "production" e "livemode": true.
Meu sistema troca URL e chave juntas por configuração (sandbox × produção) e confere o cabeçalho X-Rapp-Environment.
Todo POST envia uma Idempotency-Key única por operação, e as repetições usam a mesma chave.
Trato os erros pelo code e registro o requestId.
Respeito 429 e Retry-After, e repito 502 provider_unavailable com a mesma Idempotency-Key.
Webhook de produção configurado com URL HTTPS e segredo de produção diferente do sandbox.
Valido X-Rapp-Signature com tolerância de 5 minutos, ignoro eventos repetidos pelo id e respondo 2xx em até 10 segundos.
Não dependo da rota de sandbox (simulate-payment) em produção. Cancelamento e estorno existem também em produção.
Valores enviados em reais, com no máximo 2 casas decimais.
Se usar cartão: o sessionId antifraude é um UUID gerado pelo script da ClearSale no checkout, e os dados do cartão nunca ficam gravados no meu sistema.
Se a chave tiver lista de IPs, os IPs de saída do meu servidor de produção foram informados à Rapp.
Fiz uma primeira cobrança real de valor baixo e acompanhei até o webhook.
Ao falar com a Rapp, envie: o ambiente (X-Rapp-Environment), o requestId (ou X-Request-Id), o id da cobrança e a data/hora da chamada. Nunca envie a chave de API nem o segredo de webhook.
Referência da API
Gerada do contrato openapi.yaml. Toda rota exige Authorization: Bearer com a chave do ambiente (Authorization: Bearer rk_sandbox_... (sandbox) ou rk_live_... (produção)).
Aceita qualquer chave válida (não exige escopo). Use para conferir a configuração antes de integrar.
Respostas
200 Ambiente atual.
Cabeçalhos: X-Rapp-Environment
401 Chave ausente, inválida, revogada ou de outro ambiente.
Chave inválida
{"error":{"code":"unauthorized","message":"Chave de API ausente ou inválida.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
Chave de outro ambiente
{"error":{"code":"environment_mismatch","message":"Este ambiente é sandbox e aceita só chaves rk_sandbox_. Use a URL do ambiente da sua chave.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
429 Limite de requisições por minuto da chave excedido. Veja o cabeçalho Retry-After.
Cabeçalhos: Retry-After
Limite excedido
{"error":{"code":"rate_limited","message":"Limite de requisições da chave excedido. Tente novamente em instantes.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
cURL
curl -X GET "https://sandbox-api.rcheckout.com.br/v1/environment" \
-H "Authorization: Bearer $RAPP_API_KEY"
Node.js
// Node.js 18 ou superior (fetch nativo). Rode no seu servidor, nunca no navegador.const response = awaitfetch('https://sandbox-api.rcheckout.com.br/v1/environment', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.RAPP_API_KEY}`,
},
});
const data = await response.json();
console.log(response.status, response.headers.get('x-rapp-environment'), data);
Boleto registrado no processador de pagamentos. Com pixEnabled: true, o boleto também traz um PIX copia-e-cola (boleto híbrido).
Parâmetros
Nome
Tipo e regras
Idempotency-Keyobrigatório
no cabeçalho
string
Identificador único da operação no seu sistema (1 a 255 caracteres visíveis, sem espaço). Confirmações financeiras são duráveis; preserve a chave até a conciliação.
máx. 255 caracteres
ex.: pedido-123-tentativa-1
Corpo (JSON)
Campo
Tipo e descrição
amountobrigatório
number
Valor em reais (BRL) com no máximo 2 casas decimais (ex.: 150.01, 150 ou 150.1). Também aceita o mesmo valor como texto ("150.01"). Não use notação científica nem mais de 2 casas. A API converte internamente para centavos inteiros, sem aritmética de ponto flutuante.
{"amount":150,"dueDate":"2026-11-30","description":"Mensalidade novembro","externalReference":"pedido-124","pixEnabled":true,"payer":{"name":"Maria Teste da Silva","email":"maria@exemplo.com.br","document":"12345678909","phone":"47999990000","address":{"street":"Rua XV de Novembro","number":"100","complement":"Sala 2","district":"Centro","city":"Blumenau","state":"SC","zipCode":"89010-000"}}}
{"error":{"code":"validation_error","field":"payer.document","reason":"invalid_format","message":"Use apenas números, sem pontuação (CPF com 11 dígitos ou CNPJ com 14).","requestId":"req_3b9d0c7a1e2f4a5b"}}
Sem Idempotency-Key
{"error":{"code":"idempotency_key_required","message":"Envie o cabeçalho Idempotency-Key (1 a 255 caracteres visíveis, ex.: um UUID).","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
401 Chave ausente, inválida, revogada ou de outro ambiente.
Chave inválida
{"error":{"code":"unauthorized","message":"Chave de API ausente ou inválida.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
Chave de outro ambiente
{"error":{"code":"environment_mismatch","message":"Este ambiente é sandbox e aceita só chaves rk_sandbox_. Use a URL do ambiente da sua chave.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
403 Chave válida, mas sem permissão para esta operação.
Sem escopo
{"error":{"code":"insufficient_scope","message":"A chave não tem o escopo charges:write.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
409 Conflito de estado.
Em andamento
{"error":{"code":"idempotency_in_progress","message":"Uma requisição com esta Idempotency-Key ainda está em andamento.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
Não cancelável
{"error":{"code":"charge_not_cancelable","message":"Cobrança com status paid não pode ser cancelada.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
Não estornável
{"error":{"code":"charge_not_refundable","message":"Cobrança com status awaiting_payment não pode ser estornada.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
422 Requisição entendida, mas recusada.
Chave reutilizada
{"error":{"code":"idempotency_key_reused","message":"Esta Idempotency-Key já foi usada com outro corpo de requisição.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
Recusada pelo processador
{"error":{"code":"provider_rejected","message":"O processador de pagamentos recusou a cobrança.","details":[{"providerField":"amount","message":"Valor abaixo do mínimo permitido.","providerCode":"invalid"}],"requestId":"req_3b9d0c7a1e2f4a5b"}}
Saldo a receber insuficiente para o estorno
{"error":{"code":"insufficient_receivables","message":"O saldo a receber não cobre o valor do estorno.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
Estorno não suportado
{"error":{"code":"refund_not_supported","message":"O estorno está disponível só para cobranças de cartão ou Pix online, não para boleto.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
429 Limite de requisições por minuto da chave excedido. Veja o cabeçalho Retry-After.
Cabeçalhos: Retry-After
Limite excedido
{"error":{"code":"rate_limited","message":"Limite de requisições da chave excedido. Tente novamente em instantes.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
502 O processador não respondeu. Repita com a mesma Idempotency-Key.
Processador fora
{"error":{"code":"provider_unavailable","message":"O processador de pagamentos não respondeu. Tente novamente com a mesma Idempotency-Key.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
Identificador único da operação no seu sistema (1 a 255 caracteres visíveis, sem espaço). Confirmações financeiras são duráveis; preserve a chave até a conciliação.
máx. 255 caracteres
ex.: pedido-123-tentativa-1
Corpo (JSON)
Campo
Tipo e descrição
amountobrigatório
number
Valor em reais (BRL) com no máximo 2 casas decimais (ex.: 150.01, 150 ou 150.1). Também aceita o mesmo valor como texto ("150.01"). Não use notação científica nem mais de 2 casas. A API converte internamente para centavos inteiros, sem aritmética de ponto flutuante.
{"error":{"code":"validation_error","field":"payer.document","reason":"invalid_format","message":"Use apenas números, sem pontuação (CPF com 11 dígitos ou CNPJ com 14).","requestId":"req_3b9d0c7a1e2f4a5b"}}
Sem Idempotency-Key
{"error":{"code":"idempotency_key_required","message":"Envie o cabeçalho Idempotency-Key (1 a 255 caracteres visíveis, ex.: um UUID).","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
401 Chave ausente, inválida, revogada ou de outro ambiente.
Chave inválida
{"error":{"code":"unauthorized","message":"Chave de API ausente ou inválida.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
Chave de outro ambiente
{"error":{"code":"environment_mismatch","message":"Este ambiente é sandbox e aceita só chaves rk_sandbox_. Use a URL do ambiente da sua chave.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
403 Chave válida, mas sem permissão para esta operação.
Sem escopo
{"error":{"code":"insufficient_scope","message":"A chave não tem o escopo charges:write.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
409 Conflito de estado.
Em andamento
{"error":{"code":"idempotency_in_progress","message":"Uma requisição com esta Idempotency-Key ainda está em andamento.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
Não cancelável
{"error":{"code":"charge_not_cancelable","message":"Cobrança com status paid não pode ser cancelada.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
Não estornável
{"error":{"code":"charge_not_refundable","message":"Cobrança com status awaiting_payment não pode ser estornada.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
422 Requisição entendida, mas recusada.
Chave reutilizada
{"error":{"code":"idempotency_key_reused","message":"Esta Idempotency-Key já foi usada com outro corpo de requisição.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
Recusada pelo processador
{"error":{"code":"provider_rejected","message":"O processador de pagamentos recusou a cobrança.","details":[{"providerField":"amount","message":"Valor abaixo do mínimo permitido.","providerCode":"invalid"}],"requestId":"req_3b9d0c7a1e2f4a5b"}}
Saldo a receber insuficiente para o estorno
{"error":{"code":"insufficient_receivables","message":"O saldo a receber não cobre o valor do estorno.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
Estorno não suportado
{"error":{"code":"refund_not_supported","message":"O estorno está disponível só para cobranças de cartão ou Pix online, não para boleto.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
429 Limite de requisições por minuto da chave excedido. Veja o cabeçalho Retry-After.
Cabeçalhos: Retry-After
Limite excedido
{"error":{"code":"rate_limited","message":"Limite de requisições da chave excedido. Tente novamente em instantes.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
502 O processador não respondeu. Repita com a mesma Idempotency-Key.
Processador fora
{"error":{"code":"provider_unavailable","message":"O processador de pagamentos não respondeu. Tente novamente com a mesma Idempotency-Key.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
Envie cardToken (devolvido por uma cobrança de cartão anterior do mesmo cliente) OU card + payer.
Os dados do cartão vão direto para a facilitadora; a Rapp não grava nem registra em log número ou CVV.
Parâmetros
Nome
Tipo e regras
Idempotency-Keyobrigatório
no cabeçalho
string
Identificador único da operação no seu sistema (1 a 255 caracteres visíveis, sem espaço). Confirmações financeiras são duráveis; preserve a chave até a conciliação.
máx. 255 caracteres
ex.: pedido-123-tentativa-1
Corpo (JSON)
Campo
Tipo e descrição
amountobrigatório
number
Valor em reais (BRL) com no máximo 2 casas decimais (ex.: 150.01, 150 ou 150.1). Também aceita o mesmo valor como texto ("150.01"). Não use notação científica nem mais de 2 casas. A API converte internamente para centavos inteiros, sem aritmética de ponto flutuante.
description
string
máx. 255 caracteres
externalReference
string
máx. 64 caracteres
cardToken
string
Token ctok_ de cobrança anterior (não envie junto com card)
UUID da sessão do fingerprint antifraude (SessionID da ClearSale; o processador exige UUID)
máx. 128 caracteres
shippingAmount
number
Valor em reais (BRL) com no máximo 2 casas decimais, inclusive zero. Também aceita texto decimal ("0" ou "5.50").
mínimo 0
payerIp
string
máx. 45 caracteres
itemsobrigatório
array de object
pelo menos 1 item(ns)
items[].nameobrigatório
string
máx. 120 caracteres
items[].amountobrigatório
number
Valor em reais (BRL) com no máximo 2 casas decimais (ex.: 150.01, 150 ou 150.1). Também aceita o mesmo valor como texto ("150.01"). Não use notação científica nem mais de 2 casas. A API converte internamente para centavos inteiros, sem aritmética de ponto flutuante.
{"error":{"code":"validation_error","field":"payer.document","reason":"invalid_format","message":"Use apenas números, sem pontuação (CPF com 11 dígitos ou CNPJ com 14).","requestId":"req_3b9d0c7a1e2f4a5b"}}
Sem Idempotency-Key
{"error":{"code":"idempotency_key_required","message":"Envie o cabeçalho Idempotency-Key (1 a 255 caracteres visíveis, ex.: um UUID).","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
401 Chave ausente, inválida, revogada ou de outro ambiente.
Chave inválida
{"error":{"code":"unauthorized","message":"Chave de API ausente ou inválida.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
Chave de outro ambiente
{"error":{"code":"environment_mismatch","message":"Este ambiente é sandbox e aceita só chaves rk_sandbox_. Use a URL do ambiente da sua chave.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
403 Chave válida, mas sem permissão para esta operação.
Sem escopo
{"error":{"code":"insufficient_scope","message":"A chave não tem o escopo charges:write.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
409 Conflito de estado.
Em andamento
{"error":{"code":"idempotency_in_progress","message":"Uma requisição com esta Idempotency-Key ainda está em andamento.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
Não cancelável
{"error":{"code":"charge_not_cancelable","message":"Cobrança com status paid não pode ser cancelada.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
Não estornável
{"error":{"code":"charge_not_refundable","message":"Cobrança com status awaiting_payment não pode ser estornada.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
422 Requisição entendida, mas recusada.
Chave reutilizada
{"error":{"code":"idempotency_key_reused","message":"Esta Idempotency-Key já foi usada com outro corpo de requisição.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
Recusada pelo processador
{"error":{"code":"provider_rejected","message":"O processador de pagamentos recusou a cobrança.","details":[{"providerField":"amount","message":"Valor abaixo do mínimo permitido.","providerCode":"invalid"}],"requestId":"req_3b9d0c7a1e2f4a5b"}}
Saldo a receber insuficiente para o estorno
{"error":{"code":"insufficient_receivables","message":"O saldo a receber não cobre o valor do estorno.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
Estorno não suportado
{"error":{"code":"refund_not_supported","message":"O estorno está disponível só para cobranças de cartão ou Pix online, não para boleto.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
429 Limite de requisições por minuto da chave excedido. Veja o cabeçalho Retry-After.
Cabeçalhos: Retry-After
Limite excedido
{"error":{"code":"rate_limited","message":"Limite de requisições da chave excedido. Tente novamente em instantes.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
502 O processador não respondeu. Repita com a mesma Idempotency-Key.
Processador fora
{"error":{"code":"provider_unavailable","message":"O processador de pagamentos não respondeu. Tente novamente com a mesma Idempotency-Key.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
{"error":{"code":"validation_error","field":"payer.document","reason":"invalid_format","message":"Use apenas números, sem pontuação (CPF com 11 dígitos ou CNPJ com 14).","requestId":"req_3b9d0c7a1e2f4a5b"}}
Sem Idempotency-Key
{"error":{"code":"idempotency_key_required","message":"Envie o cabeçalho Idempotency-Key (1 a 255 caracteres visíveis, ex.: um UUID).","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
401 Chave ausente, inválida, revogada ou de outro ambiente.
Chave inválida
{"error":{"code":"unauthorized","message":"Chave de API ausente ou inválida.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
Chave de outro ambiente
{"error":{"code":"environment_mismatch","message":"Este ambiente é sandbox e aceita só chaves rk_sandbox_. Use a URL do ambiente da sua chave.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
403 Chave válida, mas sem permissão para esta operação.
Sem escopo
{"error":{"code":"insufficient_scope","message":"A chave não tem o escopo charges:write.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
429 Limite de requisições por minuto da chave excedido. Veja o cabeçalho Retry-After.
Cabeçalhos: Retry-After
Limite excedido
{"error":{"code":"rate_limited","message":"Limite de requisições da chave excedido. Tente novamente em instantes.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
cURL
curl -X GET "https://sandbox-api.rcheckout.com.br/v1/charges?page=1&pageSize=20" \
-H "Authorization: Bearer $RAPP_API_KEY"
Node.js
// Node.js 18 ou superior (fetch nativo). Rode no seu servidor, nunca no navegador.const response = awaitfetch('https://sandbox-api.rcheckout.com.br/v1/charges?page=1&pageSize=20', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.RAPP_API_KEY}`,
},
});
const data = await response.json();
console.log(response.status, response.headers.get('x-rapp-environment'), data);
Enquanto o status não é final, a Rapp consulta o processador de pagamentos e atualiza. Se o processador de pagamentos estiver fora, devolve o último estado conhecido.
Parâmetros
Nome
Tipo e regras
idobrigatório
no caminho
string
ex.: chg_7f3a9c2e1b4d5a6f8e9c0b1a
Respostas
200 Cobrança.
Cabeçalhos: X-Rapp-Environment
401 Chave ausente, inválida, revogada ou de outro ambiente.
Chave inválida
{"error":{"code":"unauthorized","message":"Chave de API ausente ou inválida.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
Chave de outro ambiente
{"error":{"code":"environment_mismatch","message":"Este ambiente é sandbox e aceita só chaves rk_sandbox_. Use a URL do ambiente da sua chave.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
403 Chave válida, mas sem permissão para esta operação.
Sem escopo
{"error":{"code":"insufficient_scope","message":"A chave não tem o escopo charges:write.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
404 Cobrança não encontrada (ou de outro cliente), ou rota inexistente neste ambiente.
Não encontrada
{"error":{"code":"not_found","message":"Cobrança não encontrada.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
429 Limite de requisições por minuto da chave excedido. Veja o cabeçalho Retry-After.
Cabeçalhos: Retry-After
Limite excedido
{"error":{"code":"rate_limited","message":"Limite de requisições da chave excedido. Tente novamente em instantes.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
cURL
curl -X GET "https://sandbox-api.rcheckout.com.br/v1/charges/chg_7f3a9c2e1b4d5a6f8e9c0b1a" \
-H "Authorization: Bearer $RAPP_API_KEY"
Node.js
// Node.js 18 ou superior (fetch nativo). Rode no seu servidor, nunca no navegador.const response = awaitfetch('https://sandbox-api.rcheckout.com.br/v1/charges/chg_7f3a9c2e1b4d5a6f8e9c0b1a', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.RAPP_API_KEY}`,
},
});
const data = await response.json();
console.log(response.status, response.headers.get('x-rapp-environment'), data);
Devolve o arquivo PDF da transação, autenticado com a chave de API.
Use o campo transactions[].boleto.pdfUrl. Não há redirecionamento para o processador.
Parâmetros
Nome
Tipo e regras
idobrigatório
no caminho
string
ex.: chg_7f3a9c2e1b4d5a6f8e9c0b1a
transactionIdobrigatório
no caminho
string
ex.: 5001
Respostas
200 Arquivo PDF do boleto.
Cabeçalhos: X-Rapp-Environment
401 Chave ausente, inválida, revogada ou de outro ambiente.
Chave inválida
{"error":{"code":"unauthorized","message":"Chave de API ausente ou inválida.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
Chave de outro ambiente
{"error":{"code":"environment_mismatch","message":"Este ambiente é sandbox e aceita só chaves rk_sandbox_. Use a URL do ambiente da sua chave.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
403 Chave válida, mas sem permissão para esta operação.
Sem escopo
{"error":{"code":"insufficient_scope","message":"A chave não tem o escopo charges:write.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
404 Cobrança não encontrada (ou de outro cliente), ou rota inexistente neste ambiente.
Não encontrada
{"error":{"code":"not_found","message":"Cobrança não encontrada.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
429 Limite de requisições por minuto da chave excedido. Veja o cabeçalho Retry-After.
Cabeçalhos: Retry-After
Limite excedido
{"error":{"code":"rate_limited","message":"Limite de requisições da chave excedido. Tente novamente em instantes.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
cURL
curl -X GET "https://sandbox-api.rcheckout.com.br/v1/charges/chg_7f3a9c2e1b4d5a6f8e9c0b1a/transactions/5001/boleto.pdf" \
-H "Authorization: Bearer $RAPP_API_KEY"
Node.js
// Node.js 18 ou superior (fetch nativo). Rode no seu servidor, nunca no navegador.const response = awaitfetch('https://sandbox-api.rcheckout.com.br/v1/charges/chg_7f3a9c2e1b4d5a6f8e9c0b1a/transactions/5001/boleto.pdf', {
method: 'GET',
headers: {
Authorization: `Bearer ${process.env.RAPP_API_KEY}`,
},
});
const data = await response.json();
console.log(response.status, response.headers.get('x-rapp-environment'), data);
Disponível no sandbox e em produção (features.cancelCharges é sempre true).
Só cobranças pending ou awaiting_payment podem ser canceladas.
Não precisa de corpo.
Parâmetros
Nome
Tipo e regras
idobrigatório
no caminho
string
ex.: chg_7f3a9c2e1b4d5a6f8e9c0b1a
Idempotency-Keyobrigatório
no cabeçalho
string
Identificador único da operação no seu sistema (1 a 255 caracteres visíveis, sem espaço). Confirmações financeiras são duráveis; preserve a chave até a conciliação.
401 Chave ausente, inválida, revogada ou de outro ambiente.
Chave inválida
{"error":{"code":"unauthorized","message":"Chave de API ausente ou inválida.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
Chave de outro ambiente
{"error":{"code":"environment_mismatch","message":"Este ambiente é sandbox e aceita só chaves rk_sandbox_. Use a URL do ambiente da sua chave.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
403 Chave válida, mas sem permissão para esta operação.
Sem escopo
{"error":{"code":"insufficient_scope","message":"A chave não tem o escopo charges:write.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
404 Cobrança não encontrada (ou de outro cliente), ou rota inexistente neste ambiente.
Não encontrada
{"error":{"code":"not_found","message":"Cobrança não encontrada.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
409 Conflito de estado.
Em andamento
{"error":{"code":"idempotency_in_progress","message":"Uma requisição com esta Idempotency-Key ainda está em andamento.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
Não cancelável
{"error":{"code":"charge_not_cancelable","message":"Cobrança com status paid não pode ser cancelada.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
Não estornável
{"error":{"code":"charge_not_refundable","message":"Cobrança com status awaiting_payment não pode ser estornada.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
502 O processador não respondeu. Repita com a mesma Idempotency-Key.
Processador fora
{"error":{"code":"provider_unavailable","message":"O processador de pagamentos não respondeu. Tente novamente com a mesma Idempotency-Key.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
Estorna a transação da cobrança via transactionRefund do processador de pagamentos.
Disponível no sandbox e em produção (features.refundCharges é sempre true).
Só cartão ou Pix online em paid ou partially_refunded. Boleto responde 422 refund_not_supported.
Sem amount, estorna o saldo restante. reason é informativo; o padrão é REQUESTED_BY_CUSTOMER.
A cobrança só é atualizada depois da confirmação do processador de pagamentos.
Parâmetros
Nome
Tipo e regras
idobrigatório
no caminho
string
ex.: chg_7f3a9c2e1b4d5a6f8e9c0b1a
Idempotency-Keyobrigatório
no cabeçalho
string
Identificador único da operação no seu sistema (1 a 255 caracteres visíveis, sem espaço). Confirmações financeiras são duráveis; preserve a chave até a conciliação.
máx. 255 caracteres
ex.: pedido-123-tentativa-1
Corpo (JSON)
Campo
Tipo e descrição
amount
object
Valor a estornar em reais. Sem este campo, estorna o saldo restante.
reason
string
Motivo informativo do estorno. O padrão é REQUESTED_BY_CUSTOMER.
valores: DUPLICATE, FRAUDULENT, REQUESTED_BY_CUSTOMER, OTHER · padrão: REQUESTED_BY_CUSTOMER
{"error":{"code":"validation_error","field":"payer.document","reason":"invalid_format","message":"Use apenas números, sem pontuação (CPF com 11 dígitos ou CNPJ com 14).","requestId":"req_3b9d0c7a1e2f4a5b"}}
Sem Idempotency-Key
{"error":{"code":"idempotency_key_required","message":"Envie o cabeçalho Idempotency-Key (1 a 255 caracteres visíveis, ex.: um UUID).","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
401 Chave ausente, inválida, revogada ou de outro ambiente.
Chave inválida
{"error":{"code":"unauthorized","message":"Chave de API ausente ou inválida.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
Chave de outro ambiente
{"error":{"code":"environment_mismatch","message":"Este ambiente é sandbox e aceita só chaves rk_sandbox_. Use a URL do ambiente da sua chave.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
403 Chave válida, mas sem permissão para esta operação.
Sem escopo
{"error":{"code":"insufficient_scope","message":"A chave não tem o escopo charges:write.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
404 Cobrança não encontrada (ou de outro cliente), ou rota inexistente neste ambiente.
Não encontrada
{"error":{"code":"not_found","message":"Cobrança não encontrada.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
409 Conflito de estado.
Em andamento
{"error":{"code":"idempotency_in_progress","message":"Uma requisição com esta Idempotency-Key ainda está em andamento.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
Não cancelável
{"error":{"code":"charge_not_cancelable","message":"Cobrança com status paid não pode ser cancelada.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
Não estornável
{"error":{"code":"charge_not_refundable","message":"Cobrança com status awaiting_payment não pode ser estornada.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
422 Requisição entendida, mas recusada.
Chave reutilizada
{"error":{"code":"idempotency_key_reused","message":"Esta Idempotency-Key já foi usada com outro corpo de requisição.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
Recusada pelo processador
{"error":{"code":"provider_rejected","message":"O processador de pagamentos recusou a cobrança.","details":[{"providerField":"amount","message":"Valor abaixo do mínimo permitido.","providerCode":"invalid"}],"requestId":"req_3b9d0c7a1e2f4a5b"}}
Saldo a receber insuficiente para o estorno
{"error":{"code":"insufficient_receivables","message":"O saldo a receber não cobre o valor do estorno.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
Estorno não suportado
{"error":{"code":"refund_not_supported","message":"O estorno está disponível só para cobranças de cartão ou Pix online, não para boleto.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
502 O processador não respondeu. Repita com a mesma Idempotency-Key.
Processador fora
{"error":{"code":"provider_unavailable","message":"O processador de pagamentos não respondeu. Tente novamente com a mesma Idempotency-Key.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
Marca um boleto ou PIX como pago no sandbox do processador de pagamentos. Não existe para cartão nem em produção. Não precisa de corpo.
Parâmetros
Nome
Tipo e regras
idobrigatório
no caminho
string
ex.: chg_7f3a9c2e1b4d5a6f8e9c0b1a
Idempotency-Keyobrigatório
no cabeçalho
string
Identificador único da operação no seu sistema (1 a 255 caracteres visíveis, sem espaço). Confirmações financeiras são duráveis; preserve a chave até a conciliação.
401 Chave ausente, inválida, revogada ou de outro ambiente.
Chave inválida
{"error":{"code":"unauthorized","message":"Chave de API ausente ou inválida.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
Chave de outro ambiente
{"error":{"code":"environment_mismatch","message":"Este ambiente é sandbox e aceita só chaves rk_sandbox_. Use a URL do ambiente da sua chave.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
403 Chave válida, mas sem permissão para esta operação.
Sem escopo
{"error":{"code":"insufficient_scope","message":"A chave não tem o escopo charges:write.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
404 Cobrança não encontrada (ou de outro cliente), ou rota inexistente neste ambiente.
Não encontrada
{"error":{"code":"not_found","message":"Cobrança não encontrada.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
409 Conflito de estado.
Em andamento
{"error":{"code":"idempotency_in_progress","message":"Uma requisição com esta Idempotency-Key ainda está em andamento.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
Não cancelável
{"error":{"code":"charge_not_cancelable","message":"Cobrança com status paid não pode ser cancelada.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
Não estornável
{"error":{"code":"charge_not_refundable","message":"Cobrança com status awaiting_payment não pode ser estornada.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
422 Requisição entendida, mas recusada.
Chave reutilizada
{"error":{"code":"idempotency_key_reused","message":"Esta Idempotency-Key já foi usada com outro corpo de requisição.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
Recusada pelo processador
{"error":{"code":"provider_rejected","message":"O processador de pagamentos recusou a cobrança.","details":[{"providerField":"amount","message":"Valor abaixo do mínimo permitido.","providerCode":"invalid"}],"requestId":"req_3b9d0c7a1e2f4a5b"}}
Saldo a receber insuficiente para o estorno
{"error":{"code":"insufficient_receivables","message":"O saldo a receber não cobre o valor do estorno.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
Estorno não suportado
{"error":{"code":"refund_not_supported","message":"O estorno está disponível só para cobranças de cartão ou Pix online, não para boleto.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
502 O processador não respondeu. Repita com a mesma Idempotency-Key.
Processador fora
{"error":{"code":"provider_unavailable","message":"O processador de pagamentos não respondeu. Tente novamente com a mesma Idempotency-Key.","details":[],"requestId":"req_3b9d0c7a1e2f4a5b"}}
Valor em reais (BRL) com no máximo 2 casas decimais (ex.: 150.01, 150 ou 150.1). Também aceita o mesmo valor como texto ("150.01"). Não use notação científica nem mais de 2 casas. A API converte internamente para centavos inteiros, sem aritmética de ponto flutuante.
Valor em reais (BRL) com no máximo 2 casas decimais (ex.: 150.01, 150 ou 150.1). Também aceita o mesmo valor como texto ("150.01"). Não use notação científica nem mais de 2 casas. A API converte internamente para centavos inteiros, sem aritmética de ponto flutuante.
Valor em reais (BRL) com no máximo 2 casas decimais (ex.: 150.01, 150 ou 150.1). Também aceita o mesmo valor como texto ("150.01"). Não use notação científica nem mais de 2 casas. A API converte internamente para centavos inteiros, sem aritmética de ponto flutuante.
description
string
máx. 255 caracteres
externalReference
string
máx. 64 caracteres
cardToken
string
Token ctok_ de cobrança anterior (não envie junto com card)
Valor em reais (BRL) com no máximo 2 casas decimais (ex.: 150.01, 150 ou 150.1). Também aceita o mesmo valor como texto ("150.01"). Não use notação científica nem mais de 2 casas. A API converte internamente para centavos inteiros, sem aritmética de ponto flutuante.
currencyobrigatório
string
valores: BRL
installmentsobrigatório
integer
descriptionobrigatório
stringpode ser null
externalReferenceobrigatório
stringpode ser null
dueDateobrigatório
string (date)pode ser null
splitobrigatório
objectpode ser null
cardTokenobrigatório
stringpode ser null
Token ctok_ para reusar o mesmo cartão (baseado no payment profile da cobrança anterior)
Não. O sandbox serve para desenvolver e testar a integração, e nada nele movimenta dinheiro real. Ver no guia.
Posso usar a chave de produção no sandbox (ou o contrário)?
Não. Uma chave só funciona no ambiente dela: rk_sandbox_ no sandbox e rk_live_ em produção. A chave de outro ambiente recebe 401 environment_mismatch. Ver no guia.
Em que unidade eu envio os valores?
Em reais, com no máximo 2 casas decimais: R$ 150,00 = 150 ou 150.00; R$ 150,01 = 150.01. Também aceita texto ("150.01"). Ver no guia.
A rede caiu no meio de um POST. Posso repetir?
Sim, com a mesma Idempotency-Key e o mesmo corpo. Até 24 h, a API devolve a mesma resposta da primeira chamada com Idempotent-Replayed: true e não cria nada de novo. Ver no guia.
Como fico sabendo que uma cobrança foi paga?
Pelo webhook charge.paid, assinado com o seu segredo whsec_.... Em caso de dúvida, GET /v1/charges/{id} é a fonte da verdade. Ver no guia.
Como testo um pagamento sem pagar?
No sandbox, use POST /v1/sandbox/charges/{id}/simulate-payment em um boleto ou PIX. A rota não existe em produção e não vale para cartão. Ver no guia.
Posso chamar a API direto do navegador ou do aplicativo?
Não. A chave de API não pode ficar no navegador nem no aplicativo do seu cliente: as chamadas devem sair do seu servidor. Ver no guia.
Minha chave vazou. E agora?
Peça à Rapp a revogação: ela vale na hora. A troca de chave (rotação) também é pedida à Rapp. Ver no guia.
Quantas requisições posso fazer?
Cada chave tem um limite por minuto (padrão 120/min, ajustável pela Rapp). Ao passar dele, a API responde 429 rate_limited com o cabeçalho Retry-After. Ver no guia.
O que mando para o suporte quando algo dá errado?
O ambiente (X-Rapp-Environment), o requestId (ou X-Request-Id), o id da cobrança e a data e hora da chamada. Nunca envie a chave de API nem o segredo de webhook. Ver no guia.