Rapp CheckoutManual da API SANDBOX

Rapp Checkout · API v1

Rapp Checkout — API pública de pagamentos

Você está no sandbox: ambiente de testes. Use chaves rk_sandbox_. Nada aqui movimenta dinheiro real.

URL base https://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.

Primeiros passos#

  1. Receba a sua chave

    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.

  2. Configure a URL base e a chave

    Os exemplos deste manual usam estas variáveis.

    Terminal
    export RAPP_API_URL="https://sandbox-api.rcheckout.com.br"
    export RAPP_API_KEY="rk_sandbox_..."
  3. Faça a primeira chamada

    Toda chamada leva Authorization: Bearer <sua chave>. GET /v1/environment confirma o ambiente, o que está liberado e os escopos da chave.

    cURL
    curl -X GET "https://sandbox-api.rcheckout.com.br/v1/environment" \
      -H "Authorization: Bearer $RAPP_API_KEY"
    Resposta 200
    {
      "object": "environment",
      "environment": "sandbox",
      "livemode": false,
      "apiVersion": "v1",
      "features": {
        "cardCharges": true,
        "cancelCharges": true,
        "refundCharges": true,
        "simulatePayment": true
      },
      "apiKey": {
        "scopes": [
          "charges:read",
          "charges:write"
        ],
        "rateLimitPerMinute": 120
      }
    }
  4. Crie a primeira cobrança

    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.

    Baixar coleção Postman Baixar ambiente de sandbox

  6. Receba os avisos e teste tudo

    Configure os webhooks com a Rapp, valide a assinatura e siga o roteiro de testes no sandbox antes de pedir produção.

Guia de integração

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.

1. Visão geral#

  • 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.

2. Ambientes: sandbox e produção#

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.

3. Chaves de API#

  • 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.

4. Autenticação e cabeçalhos#

Cabeçalho Quando Exemplo
Authorization Sempre Bearer rk_sandbox_...
Content-Type Quando houver corpo application/json
Idempotency-Key Em todo POST pedido-123-boleto

Cabeçalhos que a API devolve:

Cabeçalho Significado
X-Request-Id Identificador da chamada (informe ao suporte)
X-Rapp-Environment sandbox ou production
X-RateLimit-Limit / X-RateLimit-Remaining Limite por minuto da chave e quanto ainda resta
Idempotent-Replayed: true A resposta é a repetição de um POST anterior
Retry-After Em 429, segundos para tentar de novo

5. Convenções#

  • 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.

6. Idempotência (Idempotency-Key)#

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).

7. Limite de requisições#

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.

8. Erros#

Todos os erros seguem o mesmo formato:

JSON
{
  "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"
  }
}

8.1 Erros de validação#

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 único 400 validation_error, com o primeiro problema encontrado, nesta ordem determinística:

  1. Cabeçalhos relevantes, quando se aplicam à rota (Idempotency-Key nas operações POST tem código próprio, idempotency_key_required).
  2. id no caminho (formato chg_ seguido de letras, números ou _).
  3. Query: os parâmetros conhecidos, nesta ordem — method, status, createdFrom, createdTo, externalReference, page, pageSize — e, por último, qualquer parâmetro desconhecido.
  4. 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.

9. Endpoints#

Método Rota Escopo Ambiente
GET /v1/environment qualquer chave ambos
POST /v1/charges/boleto charges:write ambos
POST /v1/charges/pix charges:write ambos
POST /v1/charges/card charges:write ambos
GET /v1/charges charges:read ambos
GET /v1/charges/{id} charges:read ambos
GET /v1/charges/{id}/transactions/{transactionId}/boleto.pdf charges:read ambos
POST /v1/charges/{id}/cancel charges:write ambos
POST /v1/charges/{id}/refund charges:write ambos
POST /v1/sandbox/charges/{id}/simulate-payment charges:write só sandbox

9.1 Consultar o ambiente#

GET /v1/environment — diz em que ambiente a chave está, o que a instância oferece e os escopos e o limite da chave.

Terminal
curl "$RAPP_API_URL/v1/environment" \
  -H "Authorization: Bearer $RAPP_API_KEY"

Resposta 200 no sandbox:

JSON
{
  "object": "environment",
  "environment": "sandbox",
  "livemode": false,
  "apiVersion": "v1",
  "features": {
    "cardCharges": true,
    "cancelCharges": true,
    "refundCharges": true,
    "simulatePayment": true
  },
  "apiKey": {
    "scopes": [
      "charges:read",
      "charges:write"
    ],
    "rateLimitPerMinute": 120
  }
}

Resposta 200 em produção:

JSON
{
  "object": "environment",
  "environment": "production",
  "livemode": true,
  "apiVersion": "v1",
  "features": {
    "cardCharges": true,
    "cancelCharges": true,
    "refundCharges": true,
    "simulatePayment": false
  },
  "apiKey": {
    "scopes": [
      "charges:read",
      "charges:write"
    ],
    "rateLimitPerMinute": 120
  }
}
  • features.cardCharges: cobrança no cartão (sempre true).
  • features.cancelCharges: cancelamento de cobrança em aberto (sempre true).
  • features.refundCharges: estorno de cartão ou Pix pago (sempre true).
  • features.simulatePayment: simulação de pagamento disponível (só sandbox).

9.2 Criar boleto#

POST /v1/charges/boleto

Campo Tipo Obrigatório Descrição
amount número ou texto sim Valor em reais, até 2 casas decimais (> 0). Ex.: 150.01, 150 ou "150.01"
dueDate AAAA-MM-DD não Vencimento, hoje ou depois (horário de Brasília). Sem data, vence amanhã
description texto (até 255) não Descrição da cobrança
externalReference texto (até 64) não Seu identificador (ex.: número do pedido); serve de filtro na listagem
pixEnabled booleano não true gera boleto híbrido, com PIX copia-e-cola (padrão false)
payer.name texto (até 120) sim Nome do pagador
payer.email texto sim E-mail do pagador
payer.document texto sim CPF (11 dígitos) ou CNPJ (14 dígitos), apenas números
payer.phone texto não Telefone com DDD, apenas números (10 a 13 dígitos)
payer.address.street texto sim Logradouro
payer.address.number texto sim Número
payer.address.complement texto não Complemento
payer.address.district texto sim Bairro
payer.address.city texto sim Cidade
payer.address.state texto (2) sim UF (ex.: SC)
payer.address.zipCode texto sim CEP com 8 dígitos
Terminal
curl -X POST "$RAPP_API_URL/v1/charges/boleto" \
  -H "Authorization: Bearer $RAPP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-123-boleto" \
  --data-binary @- <<'JSON'
{
  "amount": 150.00,
  "dueDate": "2026-11-30",
  "description": "Mensalidade novembro",
  "externalReference": "pedido-123",
  "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"
    }
  }
}
JSON

Resposta 201:

JSON
{
  "id": "chg_7f3a9c2e1b4d5a6f8e9c0b1a",
  "object": "charge",
  "environment": "sandbox",
  "method": "boleto",
  "status": "awaiting_payment",
  "amount": 150.00,
  "currency": "BRL",
  "installments": 1,
  "description": "Mensalidade novembro",
  "externalReference": "pedido-123",
  "dueDate": "2026-11-30",
  "split": {
    "payoutRuleId": "55"
  },
  "cardToken": null,
  "transactions": [
    {
      "id": "5001",
      "object": "transaction",
      "status": "awaiting_payment",
      "amount": 150.00,
      "paidAmount": 0,
      "refundedAmount": 0,
      "installmentNumber": 1,
      "dueDate": "2026-11-30",
      "billedAt": "2026-11-16T13:05:12Z",
      "paidAt": null,
      "failureReason": null,
      "boleto": {
        "digitableLine": "34191.79001 01043.510047 91020.150008 1 12340000015000",
        "barcode": "34191123400000150001790010435100479102015000",
        "pdfUrl": "https://sandbox-api.rcheckout.com.br/v1/charges/chg_7f3a9c2e1b4d5a6f8e9c0b1a/transactions/5001/boleto.pdf",
        "pixCopyPaste": null
      },
      "pix": null,
      "card": null
    }
  ],
  "canceledAt": null,
  "createdAt": "2026-11-16T13:05:12.345Z",
  "updatedAt": "2026-11-16T13:05:12.345Z"
}

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).

9.3 Criar boleto com PIX (híbrido)#

Mesmo endpoint, com "pixEnabled": true. O pagador escolhe pagar pelo boleto ou pelo PIX copia-e-cola.

Terminal
curl -X POST "$RAPP_API_URL/v1/charges/boleto" \
  -H "Authorization: Bearer $RAPP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-124-boleto-pix" \
  --data-binary @- <<'JSON'
{
  "amount": 150.00,
  "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"
    }
  }
}
JSON

Resposta 201 (repare em boleto.pixCopyPaste):

JSON
{
  "id": "chg_0c1d2e3f4a5b6c7d8e9f0a1b",
  "object": "charge",
  "environment": "sandbox",
  "method": "boleto",
  "status": "awaiting_payment",
  "amount": 150.00,
  "currency": "BRL",
  "installments": 1,
  "description": "Mensalidade novembro",
  "externalReference": "pedido-124",
  "dueDate": "2026-11-30",
  "split": {
    "payoutRuleId": "55"
  },
  "cardToken": null,
  "transactions": [
    {
      "id": "5002",
      "object": "transaction",
      "status": "awaiting_payment",
      "amount": 150.00,
      "paidAmount": 0,
      "refundedAmount": 0,
      "installmentNumber": 1,
      "dueDate": "2026-11-30",
      "billedAt": "2026-11-16T13:05:12Z",
      "paidAt": null,
      "failureReason": null,
      "boleto": {
        "digitableLine": "34191.79001 01043.510047 91020.150008 1 12340000015000",
        "barcode": "34191123400000150001790010435100479102015000",
        "pdfUrl": "https://sandbox-api.rcheckout.com.br/v1/charges/chg_0c1d2e3f4a5b6c7d8e9f0a1b/transactions/5002/boleto.pdf",
        "pixCopyPaste": "00020101021226830014br.gov.bcb.pix2561qrcodes.exemplo.com.br/v2/cobv/9d36b84fc70b478fb95c12729b90ca255204000053039865406150.005802BR5920LOJA EXEMPLO LTDA6008BLUMENAU62070503***63041D3D"
      },
      "pix": null,
      "card": null
    }
  ],
  "canceledAt": null,
  "createdAt": "2026-11-16T13:05:12.345Z",
  "updatedAt": "2026-11-16T13:05:12.345Z"
}

9.4 Criar PIX#

POST /v1/charges/pix — mesmos campos do boleto, sem pixEnabled. dueDate é opcional.

Terminal
curl -X POST "$RAPP_API_URL/v1/charges/pix" \
  -H "Authorization: Bearer $RAPP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-125-pix" \
  --data-binary @- <<'JSON'
{
  "amount": 150.00,
  "description": "Pedido 125",
  "externalReference": "pedido-125",
  "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"
    }
  }
}
JSON

Resposta 201:

JSON
{
  "id": "chg_a1b2c3d4e5f60718293a4b5c",
  "object": "charge",
  "environment": "sandbox",
  "method": "pix",
  "status": "awaiting_payment",
  "amount": 150.00,
  "currency": "BRL",
  "installments": 1,
  "description": "Pedido 125",
  "externalReference": "pedido-125",
  "dueDate": "2026-11-16",
  "split": {
    "payoutRuleId": "55"
  },
  "cardToken": null,
  "transactions": [
    {
      "id": "6001",
      "object": "transaction",
      "status": "awaiting_payment",
      "amount": 150.00,
      "paidAmount": 0,
      "refundedAmount": 0,
      "installmentNumber": 1,
      "dueDate": "2026-11-16",
      "billedAt": "2026-11-16T13:05:12Z",
      "paidAt": null,
      "failureReason": null,
      "boleto": null,
      "pix": {
        "copyPaste": "00020101021226830014br.gov.bcb.pix2561qrcodes.exemplo.com.br/v2/cobv/9d36b84fc70b478fb95c12729b90ca255204000053039865406150.005802BR5920LOJA EXEMPLO LTDA6008BLUMENAU62070503***63041D3D",
        "qrCodeText": "00020101021226830014br.gov.bcb.pix2561qrcodes.exemplo.com.br/v2/cobv/9d36b84fc70b478fb95c12729b90ca255204000053039865406150.005802BR5920LOJA EXEMPLO LTDA6008BLUMENAU62070503***63041D3D",
        "expiresAt": "2026-11-17T02:59:59Z",
        "endToEndId": null
      },
      "card": null
    }
  ],
  "canceledAt": null,
  "createdAt": "2026-11-16T13:05:12.345Z",
  "updatedAt": "2026-11-16T13:05:12.345Z"
}

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.

9.5 Criar cobrança no cartão#

POST /v1/charges/card — envie card + payer ou um cardToken devolvido por uma cobrança de cartão anterior do mesmo cliente.

Campo Tipo Obrigatório Descrição
amount número ou texto sim Valor total em reais, até 2 casas decimais
installments inteiro não Número de parcelas (padrão 1)
card objeto um dos dois number, holderName, expiryMonth, expiryYear, securityCode
cardToken texto um dos dois Token ctok_ devolvido por uma cobrança de cartão anterior
payer objeto com card Mesmo formato do boleto
antifraud.sessionId UUID sim SessionID do script ClearSale; o processador de pagamentos exige formato UUID
items lista sim Itens do pedido: name, amount (reais, até 2 casas) e opcionais description, category, reference
shippingAmount número ou texto não Frete em reais, até 2 casas (zero permitido)
payerIp texto não IP do comprador
description, externalReference texto não Como no boleto

Envie card ou cardToken, nunca os dois. Os dados do cartão seguem direto para o processador; a Rapp não grava nem registra em log o número ou o CVV.

Com os dados do cartão:

Terminal
curl -X POST "$RAPP_API_URL/v1/charges/card" \
  -H "Authorization: Bearer $RAPP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-126-cartao" \
  --data-binary @- <<'JSON'
{
  "amount": 300.00,
  "installments": 3,
  "description": "Pedido 126",
  "externalReference": "pedido-126",
  "card": {
    "number": "4111111111111111",
    "holderName": "MARIA T SILVA",
    "expiryMonth": 12,
    "expiryYear": 2030,
    "securityCode": "123"
  },
  "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"
    }
  },
  "antifraud": {
    "sessionId": "3f1a0c2e-9b74-4d21-8a6e-0c5b7d4e91aa"
  },
  "shippingAmount": 0,
  "payerIp": "203.0.113.10",
  "items": [
    {
      "name": "Plano anual",
      "amount": 300.00,
      "reference": "SKU-001"
    }
  ]
}
JSON

Resposta 201:

JSON
{
  "id": "chg_9e8d7c6b5a4f3e2d1c0b9a88",
  "object": "charge",
  "environment": "sandbox",
  "method": "card",
  "status": "paid",
  "amount": 300.00,
  "currency": "BRL",
  "installments": 3,
  "description": "Pedido 126",
  "externalReference": "pedido-126",
  "dueDate": null,
  "split": {
    "payoutRuleId": "55"
  },
  "cardToken": "ctok_4d5e6f708192a3b4c5d6e7f8",
  "transactions": [
    {
      "id": "7001",
      "object": "transaction",
      "status": "paid",
      "amount": 300.00,
      "paidAmount": 300.00,
      "refundedAmount": 0,
      "installmentNumber": 3,
      "dueDate": null,
      "billedAt": "2026-11-16T13:05:12Z",
      "paidAt": "2026-11-16T13:05:14Z",
      "failureReason": null,
      "boleto": null,
      "pix": null,
      "card": {
        "brand": "VISA",
        "lastFourDigits": "1111",
        "authorizationCode": "A1B2C3"
      }
    }
  ],
  "canceledAt": null,
  "createdAt": "2026-11-16T13:05:12.345Z",
  "updatedAt": "2026-11-16T13:05:12.345Z"
}

Guarde o cardToken para cobrar o mesmo cartão de novo, sem pedir os dados outra vez:

Terminal
curl -X POST "$RAPP_API_URL/v1/charges/card" \
  -H "Authorization: Bearer $RAPP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-127-cartao" \
  --data-binary @- <<'JSON'
{
  "amount": 99.00,
  "installments": 1,
  "description": "Pedido 127",
  "externalReference": "pedido-127",
  "cardToken": "ctok_4d5e6f708192a3b4c5d6e7f8",
  "antifraud": {
    "sessionId": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
  },
  "items": [
    {
      "name": "Mensalidade",
      "amount": 99.00
    }
  ]
}
JSON

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.

9.6 Consultar uma cobrança#

GET /v1/charges/{id}

Terminal
curl "$RAPP_API_URL/v1/charges/chg_7f3a9c2e1b4d5a6f8e9c0b1a" \
  -H "Authorization: Bearer $RAPP_API_KEY"

Resposta 200 (boleto já pago):

JSON
{
  "id": "chg_7f3a9c2e1b4d5a6f8e9c0b1a",
  "object": "charge",
  "environment": "sandbox",
  "method": "boleto",
  "status": "paid",
  "amount": 150.00,
  "currency": "BRL",
  "installments": 1,
  "description": "Mensalidade novembro",
  "externalReference": "pedido-123",
  "dueDate": "2026-11-30",
  "split": {
    "payoutRuleId": "55"
  },
  "cardToken": null,
  "transactions": [
    {
      "id": "5001",
      "object": "transaction",
      "status": "paid",
      "amount": 150.00,
      "paidAmount": 150.00,
      "refundedAmount": 0,
      "installmentNumber": 1,
      "dueDate": "2026-11-30",
      "billedAt": "2026-11-16T13:05:12Z",
      "paidAt": "2026-11-16T13:20:00Z",
      "failureReason": null,
      "boleto": {
        "digitableLine": "34191.79001 01043.510047 91020.150008 1 12340000015000",
        "barcode": "34191123400000150001790010435100479102015000",
        "pdfUrl": "https://sandbox-api.rcheckout.com.br/v1/charges/chg_7f3a9c2e1b4d5a6f8e9c0b1a/transactions/5001/boleto.pdf",
        "pixCopyPaste": null
      },
      "pix": null,
      "card": null
    }
  ],
  "canceledAt": null,
  "createdAt": "2026-11-16T13:05:12.345Z",
  "updatedAt": "2026-11-16T13:20:01.002Z"
}

Enquanto a cobrança não está num status final, a consulta busca o estado mais recente no processador. Cobrança de outro cliente responde 404.

9.7 Listar cobranças#

GET /v1/charges — mais recentes primeiro.

Parâmetro Descrição
method boleto, pix ou card
status Um dos status da seção 10
createdFrom / createdTo Período de criação (AAAA-MM-DD, em UTC)
externalReference Seu identificador
page Página (padrão 1)
pageSize Itens por página, de 1 a 100 (padrão 20)
Terminal
curl "$RAPP_API_URL/v1/charges?status=awaiting_payment&page=1&pageSize=2" \
  -H "Authorization: Bearer $RAPP_API_KEY"

Resposta 200:

JSON
{
  "data": [
    {
      "id": "chg_a1b2c3d4e5f60718293a4b5c",
      "object": "charge",
      "environment": "sandbox",
      "method": "pix",
      "status": "awaiting_payment",
      "amount": 150.00,
      "currency": "BRL",
      "installments": 1,
      "description": "Pedido 125",
      "externalReference": "pedido-125",
      "dueDate": "2026-11-16",
      "split": {
        "payoutRuleId": "55"
      },
      "cardToken": null,
      "transactions": [
        {
          "id": "6001",
          "object": "transaction",
          "status": "awaiting_payment",
          "amount": 150.00,
          "paidAmount": 0,
          "refundedAmount": 0,
          "installmentNumber": 1,
          "dueDate": "2026-11-16",
          "billedAt": "2026-11-16T13:05:12Z",
          "paidAt": null,
          "failureReason": null,
          "boleto": null,
          "pix": {
            "copyPaste": "00020101021226830014br.gov.bcb.pix2561qrcodes.exemplo.com.br/v2/cobv/9d36b84fc70b478fb95c12729b90ca255204000053039865406150.005802BR5920LOJA EXEMPLO LTDA6008BLUMENAU62070503***63041D3D",
            "qrCodeText": "00020101021226830014br.gov.bcb.pix2561qrcodes.exemplo.com.br/v2/cobv/9d36b84fc70b478fb95c12729b90ca255204000053039865406150.005802BR5920LOJA EXEMPLO LTDA6008BLUMENAU62070503***63041D3D",
            "expiresAt": "2026-11-17T02:59:59Z",
            "endToEndId": null
          },
          "card": null
        }
      ],
      "canceledAt": null,
      "createdAt": "2026-11-16T13:05:12.345Z",
      "updatedAt": "2026-11-16T13:05:12.345Z"
    },
    {
      "id": "chg_7f3a9c2e1b4d5a6f8e9c0b1a",
      "object": "charge",
      "environment": "sandbox",
      "method": "boleto",
      "status": "awaiting_payment",
      "amount": 150.00,
      "currency": "BRL",
      "installments": 1,
      "description": "Mensalidade novembro",
      "externalReference": "pedido-123",
      "dueDate": "2026-11-30",
      "split": {
        "payoutRuleId": "55"
      },
      "cardToken": null,
      "transactions": [
        {
          "id": "5001",
          "object": "transaction",
          "status": "awaiting_payment",
          "amount": 150.00,
          "paidAmount": 0,
          "refundedAmount": 0,
          "installmentNumber": 1,
          "dueDate": "2026-11-30",
          "billedAt": "2026-11-16T13:05:12Z",
          "paidAt": null,
          "failureReason": null,
          "boleto": {
            "digitableLine": "34191.79001 01043.510047 91020.150008 1 12340000015000",
            "barcode": "34191123400000150001790010435100479102015000",
            "pdfUrl": "https://sandbox-api.rcheckout.com.br/v1/charges/chg_7f3a9c2e1b4d5a6f8e9c0b1a/transactions/5001/boleto.pdf",
            "pixCopyPaste": null
          },
          "pix": null,
          "card": null
        }
      ],
      "canceledAt": null,
      "createdAt": "2026-11-16T13:05:12.345Z",
      "updatedAt": "2026-11-16T13:05:12.345Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 2,
    "total": 3,
    "totalPages": 2
  }
}

Para ler todas as páginas, aumente page até page > pagination.totalPages.

9.8 Cancelar uma cobrança#

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.

Terminal
curl -X POST "$RAPP_API_URL/v1/charges/chg_7f3a9c2e1b4d5a6f8e9c0b1a/cancel" \
  -H "Authorization: Bearer $RAPP_API_KEY" \
  -H "Idempotency-Key: cancelar-pedido-123"

Resposta 200:

JSON
{
  "id": "chg_7f3a9c2e1b4d5a6f8e9c0b1a",
  "object": "charge",
  "environment": "sandbox",
  "method": "boleto",
  "status": "canceled",
  "amount": 150.00,
  "currency": "BRL",
  "installments": 1,
  "description": "Mensalidade novembro",
  "externalReference": "pedido-123",
  "dueDate": "2026-11-30",
  "split": {
    "payoutRuleId": "55"
  },
  "cardToken": null,
  "transactions": [
    {
      "id": "5001",
      "object": "transaction",
      "status": "canceled",
      "amount": 150.00,
      "paidAmount": 0,
      "refundedAmount": 0,
      "installmentNumber": 1,
      "dueDate": "2026-11-30",
      "billedAt": "2026-11-16T13:05:12Z",
      "paidAt": null,
      "failureReason": null,
      "boleto": {
        "digitableLine": "34191.79001 01043.510047 91020.150008 1 12340000015000",
        "barcode": "34191123400000150001790010435100479102015000",
        "pdfUrl": "https://sandbox-api.rcheckout.com.br/v1/charges/chg_7f3a9c2e1b4d5a6f8e9c0b1a/transactions/5001/boleto.pdf",
        "pixCopyPaste": null
      },
      "pix": null,
      "card": null
    }
  ],
  "canceledAt": "2026-11-16T14:00:00.000Z",
  "createdAt": "2026-11-16T13:05:12.345Z",
  "updatedAt": "2026-11-16T14:00:00.000Z"
}

9.9 Simular pagamento (só sandbox)#

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.

Terminal
curl -X POST "$RAPP_API_URL/v1/sandbox/charges/chg_7f3a9c2e1b4d5a6f8e9c0b1a/simulate-payment" \
  -H "Authorization: Bearer $RAPP_API_KEY" \
  -H "Idempotency-Key: simular-pedido-123"

Resposta 200:

JSON
{
  "id": "chg_7f3a9c2e1b4d5a6f8e9c0b1a",
  "object": "charge",
  "environment": "sandbox",
  "method": "boleto",
  "status": "paid",
  "amount": 150.00,
  "currency": "BRL",
  "installments": 1,
  "description": "Mensalidade novembro",
  "externalReference": "pedido-123",
  "dueDate": "2026-11-30",
  "split": {
    "payoutRuleId": "55"
  },
  "cardToken": null,
  "transactions": [
    {
      "id": "5001",
      "object": "transaction",
      "status": "paid",
      "amount": 150.00,
      "paidAmount": 150.00,
      "refundedAmount": 0,
      "installmentNumber": 1,
      "dueDate": "2026-11-30",
      "billedAt": "2026-11-16T13:05:12Z",
      "paidAt": "2026-11-16T13:20:00Z",
      "failureReason": null,
      "boleto": {
        "digitableLine": "34191.79001 01043.510047 91020.150008 1 12340000015000",
        "barcode": "34191123400000150001790010435100479102015000",
        "pdfUrl": "https://sandbox-api.rcheckout.com.br/v1/charges/chg_7f3a9c2e1b4d5a6f8e9c0b1a/transactions/5001/boleto.pdf",
        "pixCopyPaste": null
      },
      "pix": null,
      "card": null
    }
  ],
  "canceledAt": null,
  "createdAt": "2026-11-16T13:05:12.345Z",
  "updatedAt": "2026-11-16T13:20:01.002Z"
}

9.10 Estornar uma cobrança#

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.

Terminal
curl -X POST "$RAPP_API_URL/v1/charges/chg_a1b2c3d4e5f60718293a4b5c/refund" \
  -H "Authorization: Bearer $RAPP_API_KEY" \
  -H "Idempotency-Key: estornar-pedido-125" \
  -H "Content-Type: application/json" \
  -d @- <<'JSON'
{
  "reason": "REQUESTED_BY_CUSTOMER"
}
JSON

Resposta 200:

JSON
{
  "id": "chg_a1b2c3d4e5f60718293a4b5c",
  "object": "charge",
  "environment": "sandbox",
  "method": "pix",
  "status": "refunded",
  "amount": 150.00,
  "currency": "BRL",
  "installments": 1,
  "description": "Pedido 125",
  "externalReference": "pedido-125",
  "dueDate": "2026-11-16",
  "split": {
    "payoutRuleId": "55"
  },
  "cardToken": null,
  "transactions": [
    {
      "id": "6001",
      "object": "transaction",
      "status": "refunded",
      "amount": 150.00,
      "paidAmount": 150.00,
      "refundedAmount": 150.00,
      "installmentNumber": 1,
      "dueDate": "2026-11-16",
      "billedAt": "2026-11-16T13:05:12Z",
      "paidAt": "2026-11-16T13:20:00Z",
      "failureReason": null,
      "boleto": null,
      "pix": {
        "copyPaste": "00020101021226830014br.gov.bcb.pix2561qrcodes.exemplo.com.br/v2/cobv/9d36b84fc70b478fb95c12729b90ca255204000053039865406150.005802BR5920LOJA EXEMPLO LTDA6008BLUMENAU62070503***63041D3D",
        "qrCodeText": "00020101021226830014br.gov.bcb.pix2561qrcodes.exemplo.com.br/v2/cobv/9d36b84fc70b478fb95c12729b90ca255204000053039865406150.005802BR5920LOJA EXEMPLO LTDA6008BLUMENAU62070503***63041D3D",
        "expiresAt": "2026-11-17T02:59:59Z",
        "endToEndId": "E1234567890123456789012345678901"
      },
      "card": null
    }
  ],
  "canceledAt": null,
  "createdAt": "2026-11-16T13:05:12.345Z",
  "updatedAt": "2026-11-16T14:10:00.000Z"
}

10. Ciclo de vida do status#

Status Significado Final?
pending 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).

Caminhos mais comuns:

Texto
Boleto / PIX:  awaiting_payment ──► paid
                      │
                      ├──► expired
                      └──► canceled

Cartão:        pending ──► paid ──► (partially_refunded) ──► refunded
                  │
                  └──► rejected

11. Webhooks#

Webhooks avisam o seu sistema quando o status de uma cobrança muda. Assim você não precisa ficar consultando.

11.1 Configuração#

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.

11.2 Eventos#

Evento Quando
charge.awaiting_payment Cobrança emitida e aguardando pagamento
charge.paid Pagamento confirmado
charge.partially_refunded Estorno parcial
charge.refunded Estorno total
charge.canceled Cobrança cancelada
charge.expired Cobrança vencida sem pagamento
charge.rejected Cobrança recusada
charge.disputed Contestação (chargeback) aberta

11.3 Requisição que o seu sistema recebe#

POST na sua URL com:

Cabeçalho Exemplo
Content-Type application/json
User-Agent Rapp-Checkout-Webhooks/1
X-Rapp-Event charge.paid
X-Rapp-Delivery whd_... (id da entrega; igual em todas as tentativas)
X-Rapp-Environment sandbox ou production
X-Rapp-Signature t=1763298001,v1=5f2c...

Corpo (evento charge.paid):

JSON
{
  "id": "evt_5e6f7a8b9c0d1e2f3a4b5c6d",
  "object": "event",
  "type": "charge.paid",
  "environment": "sandbox",
  "createdAt": "2026-11-16T13:20:01.010Z",
  "data": {
    "id": "chg_7f3a9c2e1b4d5a6f8e9c0b1a",
    "object": "charge",
    "environment": "sandbox",
    "method": "boleto",
    "status": "paid",
    "amount": 150.00,
    "currency": "BRL",
    "installments": 1,
    "description": "Mensalidade novembro",
    "externalReference": "pedido-123",
    "dueDate": "2026-11-30",
    "split": {
      "payoutRuleId": "55"
    },
    "cardToken": null,
    "transactions": [
      {
        "id": "5001",
        "object": "transaction",
        "status": "paid",
        "amount": 150.00,
        "paidAmount": 150.00,
        "refundedAmount": 0,
        "installmentNumber": 1,
        "dueDate": "2026-11-30",
        "billedAt": "2026-11-16T13:05:12Z",
        "paidAt": "2026-11-16T13:20:00Z",
        "failureReason": null,
        "boleto": {
          "digitableLine": "34191.79001 01043.510047 91020.150008 1 12340000015000",
          "barcode": "34191123400000150001790010435100479102015000",
          "pdfUrl": "https://sandbox-api.rcheckout.com.br/v1/charges/chg_7f3a9c2e1b4d5a6f8e9c0b1a/transactions/5001/boleto.pdf",
          "pixCopyPaste": null
        },
        "pix": null,
        "card": null
      }
    ],
    "canceledAt": null,
    "createdAt": "2026-11-16T13:05:12.345Z",
    "updatedAt": "2026-11-16T13:20:01.002Z"
  }
}

data é a cobrança completa, no mesmo formato de GET /v1/charges/{id}.

11.4 Validando a assinatura#

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_....

  1. Leia o corpo bruto exatamente como chegou (antes de converter para JSON).
  2. Separe t e v1 do cabeçalho.
  3. Calcule HMAC-SHA256(segredo, t + "." + corpoBruto) em hexadecimal.
  4. Compare com v1 usando comparação em tempo constante.
  5. Recuse se t tiver mais de 5 minutos de diferença do seu relógio (evita reenvio de mensagens antigas).

Node.js

JavaScript
import { createHmac, timingSafeEqual } from 'node:crypto';

const TOLERANCIA_SEGUNDOS = 300;

export function assinaturaRappValida(corpoBruto, cabecalhoAssinatura, segredo, agoraSegundos = Math.floor(Date.now() / 1000)) {
  const partes = Object.fromEntries(
    String(cabecalhoAssinatura ?? '').split(',').map((parte) => parte.trim().split('=')),
  );
  const timestamp = Number(partes.t);
  if (!Number.isInteger(timestamp) || !partes.v1) return false;
  if (Math.abs(agoraSegundos - timestamp) > TOLERANCIA_SEGUNDOS) return false;

  const esperada = createHmac('sha256', segredo).update(`${timestamp}.${corpoBruto}`, 'utf8').digest('hex');
  const recebida = Buffer.from(partes.v1, 'utf8');
  const calculada = Buffer.from(esperada, 'utf8');
  return recebida.length === calculada.length && timingSafeEqual(recebida, calculada);
}

Exemplo com Express (repare em express.raw, que mantém o corpo bruto):

JavaScript
import express from 'express';
import { assinaturaRappValida } from './assinatura-rapp.mjs';

const app = express();
app.post('/webhooks/rapp', express.raw({ type: 'application/json' }), (req, res) => {
  const corpoBruto = req.body.toString('utf8');
  if (!assinaturaRappValida(corpoBruto, req.get('X-Rapp-Signature'), process.env.RAPP_WEBHOOK_SECRET)) {
    return res.status(401).end();
  }
  const evento = JSON.parse(corpoBruto);
  // Registre evento.id para não processar o mesmo evento duas vezes.
  // Atualize o pedido com evento.data.status e responda rápido.
  res.status(204).end();
});

PHP

PHP
<?php
function assinaturaRappValida(string $corpoBruto, ?string $cabecalhoAssinatura, string $segredo, ?int $agora = null): bool
{
    $agora = $agora ?? time();
    $partes = [];
    foreach (explode(',', (string) $cabecalhoAssinatura) as $parte) {
        [$chave, $valor] = array_pad(explode('=', trim($parte), 2), 2, '');
        $partes[$chave] = $valor;
    }
    if (!isset($partes['t'], $partes['v1']) || !ctype_digit($partes['t'])) {
        return false;
    }
    $timestamp = (int) $partes['t'];
    if (abs($agora - $timestamp) > 300) {
        return false;
    }
    $esperada = hash_hmac('sha256', $timestamp . '.' . $corpoBruto, $segredo);
    return hash_equals($esperada, $partes['v1']);
}

// Uso:
$corpoBruto = file_get_contents('php://input');
$assinatura = $_SERVER['HTTP_X_RAPP_SIGNATURE'] ?? null;
if (!assinaturaRappValida($corpoBruto, $assinatura, getenv('RAPP_WEBHOOK_SECRET'))) {
    http_response_code(401);
    exit;
}
$evento = json_decode($corpoBruto, true);
// Registre $evento['id'] para não processar o mesmo evento duas vezes.
http_response_code(204);

11.5 Entregas, reenvios e boas práticas#

  • Responda com qualquer status 2xx em até 10 segundos. Processe o que for demorado depois (fila).
  • Sem 2xx (erro, timeout ou redirecionamento), a Rapp reenvia após 1 min, 5 min, 15 min, 1 h e 6 h. Depois de 6 tentativas, a entrega é dada como falha.
  • O mesmo evento pode chegar mais de uma vez: use id (evt_...) para ignorar repetições.
  • A ordem de chegada não é garantida: compare data.updatedAt antes de sobrescrever um status mais novo.
  • Em caso de dúvida, consulte GET /v1/charges/{id}: ela é a fonte da verdade.

12. Roteiro de testes no sandbox#

  1. Confira o ambiente: GET /v1/environment deve devolver "environment": "sandbox" e os escopos esperados.
  2. Teste os erros de autenticação: chame sem Authorization (espere 401 unauthorized) e com uma chave inventada.
  3. Crie um boleto (seção 9.2) com um externalReference do seu sistema. Guarde o id.
  4. 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.
  5. 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).
  6. Configure o webhook com a Rapp e confirme que a sua URL valida a assinatura (seção 11.4).
  7. 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".
  8. Crie um PIX (seção 9.4), mostre o QR Code a partir de qrCodeText e simule o pagamento.
  9. Crie um boleto híbrido (seção 9.3) e confira boleto.pixCopyPaste.
  10. Liste com filtros e paginação (seção 9.7).
  11. Cancelamento: cancele um boleto não pago e confira o webhook charge.canceled.
  12. 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.
  13. Cartão: crie com card, guarde o cardToken e crie outra cobrança com ele.
  14. Teste o limite: trate 429 respeitando Retry-After.
  15. 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.

13. Checklist para ir para produção#

  • 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.

14. Suporte#

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)).

Ambiente

GET /v1/environment

Consultar o ambiente e o que a chave pode fazer#

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 = await fetch('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);
PHP
<?php

$ch = curl_init('https://sandbox-api.rcheckout.com.br/v1/environment');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('RAPP_API_KEY'),
    ],
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$data = json_decode($response, true);
var_dump($status, $data);
Python
import os

import requests  # pip install requests

response = requests.request(
    "GET",
    "https://sandbox-api.rcheckout.com.br/v1/environment",
    headers={
        "Authorization": f"Bearer {os.environ['RAPP_API_KEY']}",
    },
    timeout=30,
)

print(response.status_code, response.headers.get("X-Rapp-Environment"), response.json())
Resposta 200 · Sandbox
{
  "object": "environment",
  "environment": "sandbox",
  "livemode": false,
  "apiVersion": "v1",
  "features": {
    "cardCharges": true,
    "cancelCharges": true,
    "refundCharges": true,
    "simulatePayment": true
  },
  "apiKey": {
    "scopes": [
      "charges:read",
      "charges:write"
    ],
    "rateLimitPerMinute": 120
  }
}

Cobranças

POST /v1/charges/boleto

Criar cobrança por boleto#

Boleto registrado no processador de pagamentos. Com pixEnabled: true, o boleto também traz um PIX copia-e-cola (boleto híbrido).

Parâmetros

NomeTipo e regras
Idempotency-Key obrigató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)

CampoTipo e descrição
amount obrigató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
Seu identificador do pedido
máx. 64 caracteres
payer obrigatório Payer
payer.name obrigatório string
máx. 120 caracteres
payer.email obrigatório string
máx. 254 caracteres
payer.document obrigatório string
CPF (11 dígitos) ou CNPJ (14 dígitos)
payer.phone string
Com DDD
payer.address obrigatório Address
payer.address.street obrigatório string
máx. 120 caracteres
payer.address.number obrigatório string
máx. 20 caracteres
payer.address.complement string
máx. 120 caracteres
payer.address.district obrigatório string
máx. 80 caracteres
payer.address.city obrigatório string
máx. 80 caracteres
payer.address.state obrigatório string
Sigla da UF
2 caracteres
payer.address.zipCode obrigatório string
CEP com 8 dígitos (pontuação opcional)
dueDate string (date)
Vencimento (hoje ou depois
pixEnabled boolean
Boleto híbrido com PIX copia-e-cola
padrão: false
Outro corpo de exemplo: Boleto com PIX (híbrido)
JSON
{
  "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"
    }
  }
}

Respostas

  • 201 Cobrança criada.
    Cabeçalhos: X-Rapp-Environment, Idempotent-Replayed
  • 400 Requisição inválida.
    Campo inválido
    {
      "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"
      }
    }
cURL
curl -X POST "https://sandbox-api.rcheckout.com.br/v1/charges/boleto" \
  -H "Authorization: Bearer $RAPP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-123-tentativa-1" \
  -d @- <<'JSON'
{
  "amount": 150,
  "dueDate": "2026-11-30",
  "description": "Mensalidade novembro",
  "externalReference": "pedido-123",
  "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"
    }
  }
}
JSON
Node.js
// Node.js 18 ou superior (fetch nativo). Rode no seu servidor, nunca no navegador.
const response = await fetch('https://sandbox-api.rcheckout.com.br/v1/charges/boleto', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.RAPP_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'pedido-123-tentativa-1',
  },
  body: JSON.stringify({
    "amount": 150,
    "dueDate": "2026-11-30",
    "description": "Mensalidade novembro",
    "externalReference": "pedido-123",
    "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"
      }
    }
  }),
});

const data = await response.json();
console.log(response.status, response.headers.get('x-rapp-environment'), data);
PHP
<?php

$body = [
    'amount' => 150,
    'dueDate' => '2026-11-30',
    'description' => 'Mensalidade novembro',
    'externalReference' => 'pedido-123',
    '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',
        ],
    ],
];

$ch = curl_init('https://sandbox-api.rcheckout.com.br/v1/charges/boleto');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('RAPP_API_KEY'),
        'Content-Type: application/json',
        'Idempotency-Key: pedido-123-tentativa-1',
    ],
    CURLOPT_POSTFIELDS => json_encode($body),
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$data = json_decode($response, true);
var_dump($status, $data);
Python
import os

import requests  # pip install requests

response = requests.request(
    "POST",
    "https://sandbox-api.rcheckout.com.br/v1/charges/boleto",
    headers={
        "Authorization": f"Bearer {os.environ['RAPP_API_KEY']}",
        "Idempotency-Key": "pedido-123-tentativa-1",
    },
    json={
        "amount": 150,
        "dueDate": "2026-11-30",
        "description": "Mensalidade novembro",
        "externalReference": "pedido-123",
        "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",
            },
        },
    },
    timeout=30,
)

print(response.status_code, response.headers.get("X-Rapp-Environment"), response.json())
Resposta 201 · Boleto criado
{
  "id": "chg_7f3a9c2e1b4d5a6f8e9c0b1a",
  "object": "charge",
  "environment": "sandbox",
  "method": "boleto",
  "status": "awaiting_payment",
  "amount": 150,
  "currency": "BRL",
  "installments": 1,
  "description": "Mensalidade novembro",
  "externalReference": "pedido-123",
  "dueDate": "2026-11-30",
  "split": {
    "payoutRuleId": "55"
  },
  "cardToken": null,
  "transactions": [
    {
      "id": "5001",
      "object": "transaction",
      "status": "awaiting_payment",
      "amount": 150,
      "paidAmount": 0,
      "refundedAmount": 0,
      "installmentNumber": 1,
      "dueDate": "2026-11-30",
      "billedAt": "2026-11-16T13:05:12Z",
      "paidAt": null,
      "failureReason": null,
      "boleto": {
        "digitableLine": "34191.79001 01043.510047 91020.150008 1 12340000015000",
        "barcode": "34191123400000150001790010435100479102015000",
        "pdfUrl": "https://sandbox-api.rcheckout.com.br/v1/charges/chg_7f3a9c2e1b4d5a6f8e9c0b1a/transactions/5001/boleto.pdf",
        "pixCopyPaste": null
      },
      "pix": null,
      "card": null
    }
  ],
  "canceledAt": null,
  "createdAt": "2026-11-16T13:05:12.345Z",
  "updatedAt": "2026-11-16T13:05:12.345Z"
}
POST /v1/charges/pix

Criar cobrança PIX#

Parâmetros

NomeTipo e regras
Idempotency-Key obrigató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)

CampoTipo e descrição
amount obrigató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
payer obrigatório Payer
payer.name obrigatório string
máx. 120 caracteres
payer.email obrigatório string
máx. 254 caracteres
payer.document obrigatório string
CPF (11 dígitos) ou CNPJ (14 dígitos)
payer.phone string
Com DDD
payer.address obrigatório Address
payer.address.street obrigatório string
máx. 120 caracteres
payer.address.number obrigatório string
máx. 20 caracteres
payer.address.complement string
máx. 120 caracteres
payer.address.district obrigatório string
máx. 80 caracteres
payer.address.city obrigatório string
máx. 80 caracteres
payer.address.state obrigatório string
Sigla da UF
2 caracteres
payer.address.zipCode obrigatório string
CEP com 8 dígitos (pontuação opcional)
dueDate string (date)

Respostas

  • 201 Cobrança criada.
    Cabeçalhos: X-Rapp-Environment, Idempotent-Replayed
  • 400 Requisição inválida.
    Campo inválido
    {
      "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"
      }
    }
cURL
curl -X POST "https://sandbox-api.rcheckout.com.br/v1/charges/pix" \
  -H "Authorization: Bearer $RAPP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-123-tentativa-1" \
  -d @- <<'JSON'
{
  "amount": 150,
  "description": "Pedido 125",
  "externalReference": "pedido-125",
  "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"
    }
  }
}
JSON
Node.js
// Node.js 18 ou superior (fetch nativo). Rode no seu servidor, nunca no navegador.
const response = await fetch('https://sandbox-api.rcheckout.com.br/v1/charges/pix', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.RAPP_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'pedido-123-tentativa-1',
  },
  body: JSON.stringify({
    "amount": 150,
    "description": "Pedido 125",
    "externalReference": "pedido-125",
    "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"
      }
    }
  }),
});

const data = await response.json();
console.log(response.status, response.headers.get('x-rapp-environment'), data);
PHP
<?php

$body = [
    'amount' => 150,
    'description' => 'Pedido 125',
    'externalReference' => 'pedido-125',
    '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',
        ],
    ],
];

$ch = curl_init('https://sandbox-api.rcheckout.com.br/v1/charges/pix');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('RAPP_API_KEY'),
        'Content-Type: application/json',
        'Idempotency-Key: pedido-123-tentativa-1',
    ],
    CURLOPT_POSTFIELDS => json_encode($body),
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$data = json_decode($response, true);
var_dump($status, $data);
Python
import os

import requests  # pip install requests

response = requests.request(
    "POST",
    "https://sandbox-api.rcheckout.com.br/v1/charges/pix",
    headers={
        "Authorization": f"Bearer {os.environ['RAPP_API_KEY']}",
        "Idempotency-Key": "pedido-123-tentativa-1",
    },
    json={
        "amount": 150,
        "description": "Pedido 125",
        "externalReference": "pedido-125",
        "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",
            },
        },
    },
    timeout=30,
)

print(response.status_code, response.headers.get("X-Rapp-Environment"), response.json())
Resposta 201 · PIX criado
{
  "id": "chg_a1b2c3d4e5f60718293a4b5c",
  "object": "charge",
  "environment": "sandbox",
  "method": "pix",
  "status": "awaiting_payment",
  "amount": 150,
  "currency": "BRL",
  "installments": 1,
  "description": "Pedido 125",
  "externalReference": "pedido-125",
  "dueDate": "2026-11-16",
  "split": {
    "payoutRuleId": "55"
  },
  "cardToken": null,
  "transactions": [
    {
      "id": "6001",
      "object": "transaction",
      "status": "awaiting_payment",
      "amount": 150,
      "paidAmount": 0,
      "refundedAmount": 0,
      "installmentNumber": 1,
      "dueDate": "2026-11-16",
      "billedAt": "2026-11-16T13:05:12Z",
      "paidAt": null,
      "failureReason": null,
      "boleto": null,
      "pix": {
        "copyPaste": "00020101021226830014br.gov.bcb.pix2561qrcodes.exemplo.com.br/v2/cobv/9d36b84fc70b478fb95c12729b90ca255204000053039865406150.005802BR5920LOJA EXEMPLO LTDA6008BLUMENAU62070503***63041D3D",
        "qrCodeText": "00020101021226830014br.gov.bcb.pix2561qrcodes.exemplo.com.br/v2/cobv/9d36b84fc70b478fb95c12729b90ca255204000053039865406150.005802BR5920LOJA EXEMPLO LTDA6008BLUMENAU62070503***63041D3D",
        "expiresAt": "2026-11-17T02:59:59Z",
        "endToEndId": null
      },
      "card": null
    }
  ],
  "canceledAt": null,
  "createdAt": "2026-11-16T13:05:12.345Z",
  "updatedAt": "2026-11-16T13:05:12.345Z"
}
POST /v1/charges/card

Criar cobrança no cartão#

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

NomeTipo e regras
Idempotency-Key obrigató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)

CampoTipo e descrição
amount obrigató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)
máx. 64 caracteres
card object
card.number obrigatório string
13 a 19 dígitos
card.holderName obrigatório string
máx. 80 caracteres
card.expiryMonth obrigatório integer
mínimo 1 · máximo 12
card.expiryYear obrigatório integer
mínimo 2000 · máximo 2100
card.securityCode obrigatório string
3 ou 4 dígitos
payer Payer
payer.name obrigatório string
máx. 120 caracteres
payer.email obrigatório string
máx. 254 caracteres
payer.document obrigatório string
CPF (11 dígitos) ou CNPJ (14 dígitos)
payer.phone string
Com DDD
payer.address obrigatório Address
payer.address.street obrigatório string
máx. 120 caracteres
payer.address.number obrigatório string
máx. 20 caracteres
payer.address.complement string
máx. 120 caracteres
payer.address.district obrigatório string
máx. 80 caracteres
payer.address.city obrigatório string
máx. 80 caracteres
payer.address.state obrigatório string
Sigla da UF
2 caracteres
payer.address.zipCode obrigatório string
CEP com 8 dígitos (pontuação opcional)
installments integer
mínimo 1 · padrão: 1
antifraud obrigatório object
antifraud.sessionId obrigatório string (uuid)
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
items obrigatório array de object
pelo menos 1 item(ns)
items[].name obrigatório string
máx. 120 caracteres
items[].amount obrigató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.
items[].description string
items[].category string
máx. 80 caracteres
items[].reference string
máx. 64 caracteres
Outro corpo de exemplo: Cartão (cardToken salvo)
JSON
{
  "amount": 99,
  "installments": 1,
  "description": "Pedido 127",
  "externalReference": "pedido-127",
  "cardToken": "ctok_4d5e6f708192a3b4c5d6e7f8",
  "antifraud": {
    "sessionId": "7c9e6679-7425-40de-944b-e07fc1f90ae7"
  },
  "items": [
    {
      "name": "Mensalidade",
      "amount": 99
    }
  ]
}

Respostas

  • 201 Cobrança criada.
    Cabeçalhos: X-Rapp-Environment, Idempotent-Replayed
  • 400 Requisição inválida.
    Campo inválido
    {
      "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"
      }
    }
cURL
curl -X POST "https://sandbox-api.rcheckout.com.br/v1/charges/card" \
  -H "Authorization: Bearer $RAPP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-123-tentativa-1" \
  -d @- <<'JSON'
{
  "amount": 300,
  "installments": 3,
  "description": "Pedido 126",
  "externalReference": "pedido-126",
  "card": {
    "number": "4111111111111111",
    "holderName": "MARIA T SILVA",
    "expiryMonth": 12,
    "expiryYear": 2030,
    "securityCode": "123"
  },
  "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"
    }
  },
  "antifraud": {
    "sessionId": "3f1a0c2e-9b74-4d21-8a6e-0c5b7d4e91aa"
  },
  "shippingAmount": 0,
  "payerIp": "203.0.113.10",
  "items": [
    {
      "name": "Plano anual",
      "amount": 300,
      "reference": "SKU-001"
    }
  ]
}
JSON
Node.js
// Node.js 18 ou superior (fetch nativo). Rode no seu servidor, nunca no navegador.
const response = await fetch('https://sandbox-api.rcheckout.com.br/v1/charges/card', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.RAPP_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'pedido-123-tentativa-1',
  },
  body: JSON.stringify({
    "amount": 300,
    "installments": 3,
    "description": "Pedido 126",
    "externalReference": "pedido-126",
    "card": {
      "number": "4111111111111111",
      "holderName": "MARIA T SILVA",
      "expiryMonth": 12,
      "expiryYear": 2030,
      "securityCode": "123"
    },
    "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"
      }
    },
    "antifraud": {
      "sessionId": "3f1a0c2e-9b74-4d21-8a6e-0c5b7d4e91aa"
    },
    "shippingAmount": 0,
    "payerIp": "203.0.113.10",
    "items": [
      {
        "name": "Plano anual",
        "amount": 300,
        "reference": "SKU-001"
      }
    ]
  }),
});

const data = await response.json();
console.log(response.status, response.headers.get('x-rapp-environment'), data);
PHP
<?php

$body = [
    'amount' => 300,
    'installments' => 3,
    'description' => 'Pedido 126',
    'externalReference' => 'pedido-126',
    'card' => [
        'number' => '4111111111111111',
        'holderName' => 'MARIA T SILVA',
        'expiryMonth' => 12,
        'expiryYear' => 2030,
        'securityCode' => '123',
    ],
    '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',
        ],
    ],
    'antifraud' => [
        'sessionId' => '3f1a0c2e-9b74-4d21-8a6e-0c5b7d4e91aa',
    ],
    'shippingAmount' => 0,
    'payerIp' => '203.0.113.10',
    'items' => [
        [
            'name' => 'Plano anual',
            'amount' => 300,
            'reference' => 'SKU-001',
        ],
    ],
];

$ch = curl_init('https://sandbox-api.rcheckout.com.br/v1/charges/card');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('RAPP_API_KEY'),
        'Content-Type: application/json',
        'Idempotency-Key: pedido-123-tentativa-1',
    ],
    CURLOPT_POSTFIELDS => json_encode($body),
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$data = json_decode($response, true);
var_dump($status, $data);
Python
import os

import requests  # pip install requests

response = requests.request(
    "POST",
    "https://sandbox-api.rcheckout.com.br/v1/charges/card",
    headers={
        "Authorization": f"Bearer {os.environ['RAPP_API_KEY']}",
        "Idempotency-Key": "pedido-123-tentativa-1",
    },
    json={
        "amount": 300,
        "installments": 3,
        "description": "Pedido 126",
        "externalReference": "pedido-126",
        "card": {
            "number": "4111111111111111",
            "holderName": "MARIA T SILVA",
            "expiryMonth": 12,
            "expiryYear": 2030,
            "securityCode": "123",
        },
        "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",
            },
        },
        "antifraud": {
            "sessionId": "3f1a0c2e-9b74-4d21-8a6e-0c5b7d4e91aa",
        },
        "shippingAmount": 0,
        "payerIp": "203.0.113.10",
        "items": [
            {
                "name": "Plano anual",
                "amount": 300,
                "reference": "SKU-001",
            },
        ],
    },
    timeout=30,
)

print(response.status_code, response.headers.get("X-Rapp-Environment"), response.json())
Resposta 201 · Cartão aprovado
{
  "id": "chg_9e8d7c6b5a4f3e2d1c0b9a88",
  "object": "charge",
  "environment": "sandbox",
  "method": "card",
  "status": "paid",
  "amount": 300,
  "currency": "BRL",
  "installments": 3,
  "description": "Pedido 126",
  "externalReference": "pedido-126",
  "dueDate": null,
  "split": {
    "payoutRuleId": "55"
  },
  "cardToken": "ctok_4d5e6f708192a3b4c5d6e7f8",
  "transactions": [
    {
      "id": "7001",
      "object": "transaction",
      "status": "paid",
      "amount": 300,
      "paidAmount": 300,
      "refundedAmount": 0,
      "installmentNumber": 3,
      "dueDate": null,
      "billedAt": "2026-11-16T13:05:12Z",
      "paidAt": "2026-11-16T13:05:14Z",
      "failureReason": null,
      "boleto": null,
      "pix": null,
      "card": {
        "brand": "VISA",
        "lastFourDigits": "1111",
        "authorizationCode": "A1B2C3"
      }
    }
  ],
  "canceledAt": null,
  "createdAt": "2026-11-16T13:05:12.345Z",
  "updatedAt": "2026-11-16T13:05:12.345Z"
}
GET /v1/charges

Listar as cobranças do cliente#

Mais recentes primeiro. Lê o último estado conhecido (atualizado por webhook e pela consulta individual).

Parâmetros

NomeTipo e regras
method
no query
string
valores: boleto, pix, card
status
no query
string
valores: pending, awaiting_payment, paid, partially_refunded, refunded, canceled, expired, rejected
createdFrom
no query
string (date)
Criadas a partir de (AAAA-MM-DD)
createdTo
no query
string (date)
Criadas até (AAAA-MM-DD)
externalReference
no query
string
page
no query
integer
mínimo 1 · padrão: 1
pageSize
no query
integer
mínimo 1 · máximo 100 · padrão: 20

Respostas

  • 200 Página de cobranças.
    Cabeçalhos: X-Rapp-Environment
  • 400 Requisição inválida.
    Campo inválido
    {
      "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 = await fetch('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);
PHP
<?php

$ch = curl_init('https://sandbox-api.rcheckout.com.br/v1/charges?page=1&pageSize=20');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('RAPP_API_KEY'),
    ],
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$data = json_decode($response, true);
var_dump($status, $data);
Python
import os

import requests  # pip install requests

response = requests.request(
    "GET",
    "https://sandbox-api.rcheckout.com.br/v1/charges?page=1&pageSize=20",
    headers={
        "Authorization": f"Bearer {os.environ['RAPP_API_KEY']}",
    },
    timeout=30,
)

print(response.status_code, response.headers.get("X-Rapp-Environment"), response.json())
Resposta 200 · Página 1 de 2
{
  "data": [
    {
      "id": "chg_a1b2c3d4e5f60718293a4b5c",
      "object": "charge",
      "environment": "sandbox",
      "method": "pix",
      "status": "awaiting_payment",
      "amount": 150,
      "currency": "BRL",
      "installments": 1,
      "description": "Pedido 125",
      "externalReference": "pedido-125",
      "dueDate": "2026-11-16",
      "split": {
        "payoutRuleId": "55"
      },
      "cardToken": null,
      "transactions": [
        {
          "id": "6001",
          "object": "transaction",
          "status": "awaiting_payment",
          "amount": 150,
          "paidAmount": 0,
          "refundedAmount": 0,
          "installmentNumber": 1,
          "dueDate": "2026-11-16",
          "billedAt": "2026-11-16T13:05:12Z",
          "paidAt": null,
          "failureReason": null,
          "boleto": null,
          "pix": {
            "copyPaste": "00020101021226830014br.gov.bcb.pix2561qrcodes.exemplo.com.br/v2/cobv/9d36b84fc70b478fb95c12729b90ca255204000053039865406150.005802BR5920LOJA EXEMPLO LTDA6008BLUMENAU62070503***63041D3D",
            "qrCodeText": "00020101021226830014br.gov.bcb.pix2561qrcodes.exemplo.com.br/v2/cobv/9d36b84fc70b478fb95c12729b90ca255204000053039865406150.005802BR5920LOJA EXEMPLO LTDA6008BLUMENAU62070503***63041D3D",
            "expiresAt": "2026-11-17T02:59:59Z",
            "endToEndId": null
          },
          "card": null
        }
      ],
      "canceledAt": null,
      "createdAt": "2026-11-16T13:05:12.345Z",
      "updatedAt": "2026-11-16T13:05:12.345Z"
    },
    {
      "id": "chg_7f3a9c2e1b4d5a6f8e9c0b1a",
      "object": "charge",
      "environment": "sandbox",
      "method": "boleto",
      "status": "awaiting_payment",
      "amount": 150,
      "currency": "BRL",
      "installments": 1,
      "description": "Mensalidade novembro",
      "externalReference": "pedido-123",
      "dueDate": "2026-11-30",
      "split": {
        "payoutRuleId": "55"
      },
      "cardToken": null,
      "transactions": [
        {
          "id": "5001",
          "object": "transaction",
          "status": "awaiting_payment",
          "amount": 150,
          "paidAmount": 0,
          "refundedAmount": 0,
          "installmentNumber": 1,
          "dueDate": "2026-11-30",
          "billedAt": "2026-11-16T13:05:12Z",
          "paidAt": null,
          "failureReason": null,
          "boleto": {
            "digitableLine": "34191.79001 01043.510047 91020.150008 1 12340000015000",
            "barcode": "34191123400000150001790010435100479102015000",
            "pdfUrl": "https://sandbox-api.rcheckout.com.br/v1/charges/chg_7f3a9c2e1b4d5a6f8e9c0b1a/transactions/5001/boleto.pdf",
            "pixCopyPaste": null
          },
          "pix": null,
          "card": null
        }
      ],
      "canceledAt": null,
      "createdAt": "2026-11-16T13:05:12.345Z",
      "updatedAt": "2026-11-16T13:05:12.345Z"
    }
  ],
  "pagination": {
    "page": 1,
    "pageSize": 2,
    "total": 3,
    "totalPages": 2
  }
}
GET /v1/charges/{id}

Consultar uma cobrança#

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

NomeTipo e regras
id obrigató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 = await fetch('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);
PHP
<?php

$ch = curl_init('https://sandbox-api.rcheckout.com.br/v1/charges/chg_7f3a9c2e1b4d5a6f8e9c0b1a');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('RAPP_API_KEY'),
    ],
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$data = json_decode($response, true);
var_dump($status, $data);
Python
import os

import requests  # pip install requests

response = requests.request(
    "GET",
    "https://sandbox-api.rcheckout.com.br/v1/charges/chg_7f3a9c2e1b4d5a6f8e9c0b1a",
    headers={
        "Authorization": f"Bearer {os.environ['RAPP_API_KEY']}",
    },
    timeout=30,
)

print(response.status_code, response.headers.get("X-Rapp-Environment"), response.json())
Resposta 200 · Boleto pago
{
  "id": "chg_7f3a9c2e1b4d5a6f8e9c0b1a",
  "object": "charge",
  "environment": "sandbox",
  "method": "boleto",
  "status": "paid",
  "amount": 150,
  "currency": "BRL",
  "installments": 1,
  "description": "Mensalidade novembro",
  "externalReference": "pedido-123",
  "dueDate": "2026-11-30",
  "split": {
    "payoutRuleId": "55"
  },
  "cardToken": null,
  "transactions": [
    {
      "id": "5001",
      "object": "transaction",
      "status": "paid",
      "amount": 150,
      "paidAmount": 150,
      "refundedAmount": 0,
      "installmentNumber": 1,
      "dueDate": "2026-11-30",
      "billedAt": "2026-11-16T13:05:12Z",
      "paidAt": "2026-11-16T13:20:00Z",
      "failureReason": null,
      "boleto": {
        "digitableLine": "34191.79001 01043.510047 91020.150008 1 12340000015000",
        "barcode": "34191123400000150001790010435100479102015000",
        "pdfUrl": "https://sandbox-api.rcheckout.com.br/v1/charges/chg_7f3a9c2e1b4d5a6f8e9c0b1a/transactions/5001/boleto.pdf",
        "pixCopyPaste": null
      },
      "pix": null,
      "card": null
    }
  ],
  "canceledAt": null,
  "createdAt": "2026-11-16T13:05:12.345Z",
  "updatedAt": "2026-11-16T13:20:01.002Z"
}
GET /v1/charges/{id}/transactions/{transactionId}/boleto.pdf

Baixar o PDF do boleto#

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

NomeTipo e regras
id obrigatório
no caminho
string
ex.: chg_7f3a9c2e1b4d5a6f8e9c0b1a
transactionId obrigató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 = await fetch('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);
PHP
<?php

$ch = curl_init('https://sandbox-api.rcheckout.com.br/v1/charges/chg_7f3a9c2e1b4d5a6f8e9c0b1a/transactions/5001/boleto.pdf');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('RAPP_API_KEY'),
    ],
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$data = json_decode($response, true);
var_dump($status, $data);
Python
import os

import requests  # pip install requests

response = requests.request(
    "GET",
    "https://sandbox-api.rcheckout.com.br/v1/charges/chg_7f3a9c2e1b4d5a6f8e9c0b1a/transactions/5001/boleto.pdf",
    headers={
        "Authorization": f"Bearer {os.environ['RAPP_API_KEY']}",
    },
    timeout=30,
)

print(response.status_code, response.headers.get("X-Rapp-Environment"), response.json())
POST /v1/charges/{id}/cancel

Cancelar cobrança ainda não paga#

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

NomeTipo e regras
id obrigatório
no caminho
string
ex.: chg_7f3a9c2e1b4d5a6f8e9c0b1a
Idempotency-Key obrigató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

Respostas

  • 200 Cobrança cancelada.
    Cabeçalhos: X-Rapp-Environment, Idempotent-Replayed
  • 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"
      }
    }
cURL
curl -X POST "https://sandbox-api.rcheckout.com.br/v1/charges/chg_7f3a9c2e1b4d5a6f8e9c0b1a/cancel" \
  -H "Authorization: Bearer $RAPP_API_KEY" \
  -H "Idempotency-Key: pedido-123-tentativa-1"
Node.js
// Node.js 18 ou superior (fetch nativo). Rode no seu servidor, nunca no navegador.
const response = await fetch('https://sandbox-api.rcheckout.com.br/v1/charges/chg_7f3a9c2e1b4d5a6f8e9c0b1a/cancel', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.RAPP_API_KEY}`,
    'Idempotency-Key': 'pedido-123-tentativa-1',
  },
});

const data = await response.json();
console.log(response.status, response.headers.get('x-rapp-environment'), data);
PHP
<?php

$ch = curl_init('https://sandbox-api.rcheckout.com.br/v1/charges/chg_7f3a9c2e1b4d5a6f8e9c0b1a/cancel');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('RAPP_API_KEY'),
        'Idempotency-Key: pedido-123-tentativa-1',
    ],
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$data = json_decode($response, true);
var_dump($status, $data);
Python
import os

import requests  # pip install requests

response = requests.request(
    "POST",
    "https://sandbox-api.rcheckout.com.br/v1/charges/chg_7f3a9c2e1b4d5a6f8e9c0b1a/cancel",
    headers={
        "Authorization": f"Bearer {os.environ['RAPP_API_KEY']}",
        "Idempotency-Key": "pedido-123-tentativa-1",
    },
    timeout=30,
)

print(response.status_code, response.headers.get("X-Rapp-Environment"), response.json())
Resposta 200 · Boleto cancelado
{
  "id": "chg_7f3a9c2e1b4d5a6f8e9c0b1a",
  "object": "charge",
  "environment": "sandbox",
  "method": "boleto",
  "status": "canceled",
  "amount": 150,
  "currency": "BRL",
  "installments": 1,
  "description": "Mensalidade novembro",
  "externalReference": "pedido-123",
  "dueDate": "2026-11-30",
  "split": {
    "payoutRuleId": "55"
  },
  "cardToken": null,
  "transactions": [
    {
      "id": "5001",
      "object": "transaction",
      "status": "canceled",
      "amount": 150,
      "paidAmount": 0,
      "refundedAmount": 0,
      "installmentNumber": 1,
      "dueDate": "2026-11-30",
      "billedAt": "2026-11-16T13:05:12Z",
      "paidAt": null,
      "failureReason": null,
      "boleto": {
        "digitableLine": "34191.79001 01043.510047 91020.150008 1 12340000015000",
        "barcode": "34191123400000150001790010435100479102015000",
        "pdfUrl": "https://sandbox-api.rcheckout.com.br/v1/charges/chg_7f3a9c2e1b4d5a6f8e9c0b1a/transactions/5001/boleto.pdf",
        "pixCopyPaste": null
      },
      "pix": null,
      "card": null
    }
  ],
  "canceledAt": "2026-11-16T14:00:00.000Z",
  "createdAt": "2026-11-16T13:05:12.345Z",
  "updatedAt": "2026-11-16T14:00:00.000Z"
}
POST /v1/charges/{id}/refund

Estornar cobrança paga (cartão ou Pix)#

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

NomeTipo e regras
id obrigatório
no caminho
string
ex.: chg_7f3a9c2e1b4d5a6f8e9c0b1a
Idempotency-Key obrigató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)

CampoTipo 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
Outro corpo de exemplo: Estorno parcial
JSON
{
  "amount": 50,
  "reason": "REQUESTED_BY_CUSTOMER"
}

Respostas

  • 200 Cobrança estornada (total ou parcial).
    Cabeçalhos: X-Rapp-Environment, Idempotent-Replayed
  • 400 Requisição inválida.
    Campo inválido
    {
      "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"
      }
    }
cURL
curl -X POST "https://sandbox-api.rcheckout.com.br/v1/charges/chg_7f3a9c2e1b4d5a6f8e9c0b1a/refund" \
  -H "Authorization: Bearer $RAPP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-123-tentativa-1" \
  -d @- <<'JSON'
{
  "reason": "REQUESTED_BY_CUSTOMER"
}
JSON
Node.js
// Node.js 18 ou superior (fetch nativo). Rode no seu servidor, nunca no navegador.
const response = await fetch('https://sandbox-api.rcheckout.com.br/v1/charges/chg_7f3a9c2e1b4d5a6f8e9c0b1a/refund', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.RAPP_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'pedido-123-tentativa-1',
  },
  body: JSON.stringify({
    "reason": "REQUESTED_BY_CUSTOMER"
  }),
});

const data = await response.json();
console.log(response.status, response.headers.get('x-rapp-environment'), data);
PHP
<?php

$body = [
    'reason' => 'REQUESTED_BY_CUSTOMER',
];

$ch = curl_init('https://sandbox-api.rcheckout.com.br/v1/charges/chg_7f3a9c2e1b4d5a6f8e9c0b1a/refund');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('RAPP_API_KEY'),
        'Content-Type: application/json',
        'Idempotency-Key: pedido-123-tentativa-1',
    ],
    CURLOPT_POSTFIELDS => json_encode($body),
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$data = json_decode($response, true);
var_dump($status, $data);
Python
import os

import requests  # pip install requests

response = requests.request(
    "POST",
    "https://sandbox-api.rcheckout.com.br/v1/charges/chg_7f3a9c2e1b4d5a6f8e9c0b1a/refund",
    headers={
        "Authorization": f"Bearer {os.environ['RAPP_API_KEY']}",
        "Idempotency-Key": "pedido-123-tentativa-1",
    },
    json={
        "reason": "REQUESTED_BY_CUSTOMER",
    },
    timeout=30,
)

print(response.status_code, response.headers.get("X-Rapp-Environment"), response.json())
Resposta 200 · PIX estornado por completo
{
  "id": "chg_a1b2c3d4e5f60718293a4b5c",
  "object": "charge",
  "environment": "sandbox",
  "method": "pix",
  "status": "refunded",
  "amount": 150,
  "currency": "BRL",
  "installments": 1,
  "description": "Pedido 125",
  "externalReference": "pedido-125",
  "dueDate": "2026-11-16",
  "split": {
    "payoutRuleId": "55"
  },
  "cardToken": null,
  "transactions": [
    {
      "id": "6001",
      "object": "transaction",
      "status": "refunded",
      "amount": 150,
      "paidAmount": 150,
      "refundedAmount": 150,
      "installmentNumber": 1,
      "dueDate": "2026-11-16",
      "billedAt": "2026-11-16T13:05:12Z",
      "paidAt": "2026-11-16T13:20:00Z",
      "failureReason": null,
      "boleto": null,
      "pix": {
        "copyPaste": "00020101021226830014br.gov.bcb.pix2561qrcodes.exemplo.com.br/v2/cobv/9d36b84fc70b478fb95c12729b90ca255204000053039865406150.005802BR5920LOJA EXEMPLO LTDA6008BLUMENAU62070503***63041D3D",
        "qrCodeText": "00020101021226830014br.gov.bcb.pix2561qrcodes.exemplo.com.br/v2/cobv/9d36b84fc70b478fb95c12729b90ca255204000053039865406150.005802BR5920LOJA EXEMPLO LTDA6008BLUMENAU62070503***63041D3D",
        "expiresAt": "2026-11-17T02:59:59Z",
        "endToEndId": "E1234567890123456789012345678901"
      },
      "card": null
    }
  ],
  "canceledAt": null,
  "createdAt": "2026-11-16T13:05:12.345Z",
  "updatedAt": "2026-11-16T14:10:00.000Z"
}

Sandbox

POST /v1/sandbox/charges/{id}/simulate-paymentsó sandbox

Simular pagamento (só sandbox)#

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

NomeTipo e regras
id obrigatório
no caminho
string
ex.: chg_7f3a9c2e1b4d5a6f8e9c0b1a
Idempotency-Key obrigató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

Respostas

  • 200 Cobrança paga (simulação).
    Cabeçalhos: X-Rapp-Environment, Idempotent-Replayed
  • 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"
      }
    }
cURL
curl -X POST "https://sandbox-api.rcheckout.com.br/v1/sandbox/charges/chg_7f3a9c2e1b4d5a6f8e9c0b1a/simulate-payment" \
  -H "Authorization: Bearer $RAPP_API_KEY" \
  -H "Idempotency-Key: pedido-123-tentativa-1"
Node.js
// Node.js 18 ou superior (fetch nativo). Rode no seu servidor, nunca no navegador.
const response = await fetch('https://sandbox-api.rcheckout.com.br/v1/sandbox/charges/chg_7f3a9c2e1b4d5a6f8e9c0b1a/simulate-payment', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.RAPP_API_KEY}`,
    'Idempotency-Key': 'pedido-123-tentativa-1',
  },
});

const data = await response.json();
console.log(response.status, response.headers.get('x-rapp-environment'), data);
PHP
<?php

$ch = curl_init('https://sandbox-api.rcheckout.com.br/v1/sandbox/charges/chg_7f3a9c2e1b4d5a6f8e9c0b1a/simulate-payment');
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('RAPP_API_KEY'),
        'Idempotency-Key: pedido-123-tentativa-1',
    ],
]);

$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$data = json_decode($response, true);
var_dump($status, $data);
Python
import os

import requests  # pip install requests

response = requests.request(
    "POST",
    "https://sandbox-api.rcheckout.com.br/v1/sandbox/charges/chg_7f3a9c2e1b4d5a6f8e9c0b1a/simulate-payment",
    headers={
        "Authorization": f"Bearer {os.environ['RAPP_API_KEY']}",
        "Idempotency-Key": "pedido-123-tentativa-1",
    },
    timeout=30,
)

print(response.status_code, response.headers.get("X-Rapp-Environment"), response.json())
Resposta 200 · Boleto pago
{
  "id": "chg_7f3a9c2e1b4d5a6f8e9c0b1a",
  "object": "charge",
  "environment": "sandbox",
  "method": "boleto",
  "status": "paid",
  "amount": 150,
  "currency": "BRL",
  "installments": 1,
  "description": "Mensalidade novembro",
  "externalReference": "pedido-123",
  "dueDate": "2026-11-30",
  "split": {
    "payoutRuleId": "55"
  },
  "cardToken": null,
  "transactions": [
    {
      "id": "5001",
      "object": "transaction",
      "status": "paid",
      "amount": 150,
      "paidAmount": 150,
      "refundedAmount": 0,
      "installmentNumber": 1,
      "dueDate": "2026-11-30",
      "billedAt": "2026-11-16T13:05:12Z",
      "paidAt": "2026-11-16T13:20:00Z",
      "failureReason": null,
      "boleto": {
        "digitableLine": "34191.79001 01043.510047 91020.150008 1 12340000015000",
        "barcode": "34191123400000150001790010435100479102015000",
        "pdfUrl": "https://sandbox-api.rcheckout.com.br/v1/charges/chg_7f3a9c2e1b4d5a6f8e9c0b1a/transactions/5001/boleto.pdf",
        "pixCopyPaste": null
      },
      "pix": null,
      "card": null
    }
  ],
  "canceledAt": null,
  "createdAt": "2026-11-16T13:05:12.345Z",
  "updatedAt": "2026-11-16T13:20:01.002Z"
}

Objetos da API#

Formato de cada objeto que a API envia e recebe, como está no contrato.

ValidationReason#

required invalid_type invalid_format unexpected_field out_of_range invalid_value

PaymentMethod#

boleto pix card

ChargeStatus#

pending awaiting_payment paid partially_refunded refunded canceled expired rejected

Address#

CampoTipo e descrição
street obrigatório string
máx. 120 caracteres
number obrigatório string
máx. 20 caracteres
complement string
máx. 120 caracteres
district obrigatório string
máx. 80 caracteres
city obrigatório string
máx. 80 caracteres
state obrigatório string
Sigla da UF
2 caracteres
zipCode obrigatório string
CEP com 8 dígitos (pontuação opcional)

Payer#

CampoTipo e descrição
name obrigatório string
máx. 120 caracteres
email obrigatório string
máx. 254 caracteres
document obrigatório string
CPF (11 dígitos) ou CNPJ (14 dígitos)
phone string
Com DDD
address obrigatório Address

BoletoChargeRequest#

CampoTipo e descrição
amount obrigató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
Seu identificador do pedido
máx. 64 caracteres
payer obrigatório Payer
dueDate string (date)
Vencimento (hoje ou depois
pixEnabled boolean
Boleto híbrido com PIX copia-e-cola
padrão: false

PixChargeRequest#

CampoTipo e descrição
amount obrigató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
payer obrigatório Payer
dueDate string (date)

CardChargeRequest#

CampoTipo e descrição
amount obrigató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)
máx. 64 caracteres
card object
payer Payer
installments integer
mínimo 1 · padrão: 1
antifraud obrigatório object
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
items obrigatório array de object
pelo menos 1 item(ns)

RefundRequest#

CampoTipo 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

Boleto#

CampoTipo e descrição
digitableLine obrigatório string pode ser null
Linha digitável
barcode obrigatório string pode ser null
Código de barras (44 dígitos)
pdfUrl obrigatório string pode ser null
URL autenticada da Rapp para baixar o PDF do boleto (GET
pixCopyPaste obrigatório string pode ser null
PIX copia-e-cola do boleto híbrido

Pix#

CampoTipo e descrição
copyPaste obrigatório string pode ser null
Código copia-e-cola
qrCodeText obrigatório string pode ser null
Texto para gerar o QR Code
expiresAt obrigatório string (date-time) pode ser null
endToEndId obrigatório string pode ser null
Identificador E2E do pagamento (quando pago)

Card#

CampoTipo e descrição
brand obrigatório string pode ser null
lastFourDigits obrigatório string pode ser null
authorizationCode obrigatório string pode ser null

Transaction#

CampoTipo e descrição
id obrigatório string
object obrigatório string
valores: transaction
status obrigatório string
valores: pending, awaiting_payment, paid, partially_refunded, refunded, canceled, expired, rejected
amount obrigatório number pode ser null
Valor em reais (BRL) com no máximo 2 casas decimais, ou null.
paidAmount obrigatório number pode ser null
Valor em reais (BRL) com no máximo 2 casas decimais, ou null.
refundedAmount obrigatório number pode ser null
Valor em reais (BRL) com no máximo 2 casas decimais, ou null.
installmentNumber obrigatório integer pode ser null
dueDate obrigatório string (date) pode ser null
billedAt obrigatório string (date-time) pode ser null
paidAt obrigatório string (date-time) pode ser null
failureReason obrigatório string pode ser null
boleto obrigatório Boleto pode ser null
pix obrigatório Pix pode ser null
card obrigatório Card pode ser null

Charge#

CampoTipo e descrição
id obrigatório string
object obrigatório string
valores: charge
environment obrigatório string
valores: sandbox, production
method obrigatório string
valores: boleto, pix, card
status obrigatório string
valores: pending, awaiting_payment, paid, partially_refunded, refunded, canceled, expired, rejected
amount obrigató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.
currency obrigatório string
valores: BRL
installments obrigatório integer
description obrigatório string pode ser null
externalReference obrigatório string pode ser null
dueDate obrigatório string (date) pode ser null
split obrigatório object pode ser null
cardToken obrigatório string pode ser null
Token ctok_ para reusar o mesmo cartão (baseado no payment profile da cobrança anterior)
transactions obrigatório array de Transaction
canceledAt obrigatório string (date-time) pode ser null
createdAt obrigatório string (date-time)
updatedAt obrigatório string (date-time)

ChargeList#

CampoTipo e descrição
data obrigatório array de Charge
pagination obrigatório object

Environment#

CampoTipo e descrição
object obrigatório string
valores: environment
environment obrigatório string
valores: sandbox, production
livemode obrigatório boolean
true em produção
apiVersion obrigatório string
valores: v1
features obrigatório object
apiKey obrigatório object

WebhookEvent#

Corpo enviado ao webhook do cliente.

CampoTipo e descrição
id obrigatório string
Id do evento (evt_...)
object obrigatório string
valores: event
type obrigatório string
valores: charge.awaiting_payment, charge.paid, charge.partially_refunded, charge.refunded, charge.canceled, charge.expired, charge.rejected, charge.disputed
environment obrigatório string
valores: sandbox, production
createdAt obrigatório string (date-time)
data obrigatório Charge

Error#

CampoTipo e descrição
error obrigatório object

Perguntas frequentes#

O sandbox movimenta dinheiro de verdade?

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.

Versão e contrato#

Versão do contrato1.1.0 (versão atual)
Versão da APIv1 (prefixo de todas as rotas)
Contrato OpenAPI 3/openapi.yaml · /openapi.json (importe no Postman, Insomnia ou num gerador de cliente)
PostmanBaixar coleção Postman · Baixar ambiente do Postman (gerados deste contrato)