openapi: 3.0.3 info: title: Rapp Checkout — API pública de pagamentos version: 1.1.0 description: | API REST/JSON para criar e acompanhar cobranças por boleto, PIX e cartão. O guia completo, com fluxo de testes e checklist de produção, está em `docs/integracao.md`. - 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 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`. servers: - url: https://sandbox-api.rcheckout.com.br description: Sandbox (testes, sem dinheiro real). Só chaves rk_sandbox_. x-rapp-environment: sandbox - url: https://api-public.rcheckout.com.br description: Produção (cobranças reais). Só chaves rk_live_, liberadas pela Rapp depois dos testes no sandbox. x-rapp-environment: production security: - apiKey: [] tags: - name: Ambiente - name: Cobranças - name: Sandbox paths: /v1/environment: get: tags: [Ambiente] summary: Consultar o ambiente e o que a chave pode fazer description: Aceita qualquer chave válida (não exige escopo). Use para conferir a configuração antes de integrar. operationId: getEnvironment responses: '200': description: Ambiente atual. headers: X-Rapp-Environment: { $ref: '#/components/headers/X-Rapp-Environment' } content: application/json: schema: { $ref: '#/components/schemas/Environment' } examples: sandbox: { $ref: '#/components/examples/EnvironmentSandbox' } producao: { $ref: '#/components/examples/EnvironmentProduction' } '401': { $ref: '#/components/responses/Unauthorized' } '429': { $ref: '#/components/responses/RateLimited' } /v1/charges/boleto: post: tags: [Cobranças] summary: Criar cobrança por boleto description: 'Boleto registrado no processador de pagamentos. Com `pixEnabled: true`, o boleto também traz um PIX copia-e-cola (boleto híbrido).' operationId: createBoletoCharge parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: { $ref: '#/components/schemas/BoletoChargeRequest' } examples: boleto: { $ref: '#/components/examples/BoletoRequest' } boletoComPix: { $ref: '#/components/examples/BoletoWithPixRequest' } responses: '201': description: Cobrança criada. headers: X-Rapp-Environment: { $ref: '#/components/headers/X-Rapp-Environment' } Idempotent-Replayed: { $ref: '#/components/headers/Idempotent-Replayed' } content: application/json: schema: { $ref: '#/components/schemas/Charge' } examples: boleto: { $ref: '#/components/examples/BoletoCharge' } boletoComPix: { $ref: '#/components/examples/BoletoWithPixCharge' } '400': { $ref: '#/components/responses/ValidationError' } '401': { $ref: '#/components/responses/Unauthorized' } '403': { $ref: '#/components/responses/Forbidden' } '409': { $ref: '#/components/responses/Conflict' } '422': { $ref: '#/components/responses/Unprocessable' } '429': { $ref: '#/components/responses/RateLimited' } '502': { $ref: '#/components/responses/ProviderUnavailable' } /v1/charges/pix: post: tags: [Cobranças] summary: Criar cobrança PIX operationId: createPixCharge parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: { $ref: '#/components/schemas/PixChargeRequest' } examples: pix: { $ref: '#/components/examples/PixRequest' } responses: '201': description: Cobrança criada. headers: X-Rapp-Environment: { $ref: '#/components/headers/X-Rapp-Environment' } Idempotent-Replayed: { $ref: '#/components/headers/Idempotent-Replayed' } content: application/json: schema: { $ref: '#/components/schemas/Charge' } examples: pix: { $ref: '#/components/examples/PixCharge' } '400': { $ref: '#/components/responses/ValidationError' } '401': { $ref: '#/components/responses/Unauthorized' } '403': { $ref: '#/components/responses/Forbidden' } '409': { $ref: '#/components/responses/Conflict' } '422': { $ref: '#/components/responses/Unprocessable' } '429': { $ref: '#/components/responses/RateLimited' } '502': { $ref: '#/components/responses/ProviderUnavailable' } /v1/charges/card: post: tags: [Cobranças] summary: Criar cobrança no cartão description: | 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. operationId: createCardCharge parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: { $ref: '#/components/schemas/CardChargeRequest' } examples: cartao: { $ref: '#/components/examples/CardRequest' } cardToken: { $ref: '#/components/examples/CardTokenRequest' } responses: '201': description: Cobrança criada. headers: X-Rapp-Environment: { $ref: '#/components/headers/X-Rapp-Environment' } Idempotent-Replayed: { $ref: '#/components/headers/Idempotent-Replayed' } content: application/json: schema: { $ref: '#/components/schemas/Charge' } examples: cartao: { $ref: '#/components/examples/CardCharge' } '400': { $ref: '#/components/responses/ValidationError' } '401': { $ref: '#/components/responses/Unauthorized' } '403': { $ref: '#/components/responses/Forbidden' } '409': { $ref: '#/components/responses/Conflict' } '422': { $ref: '#/components/responses/Unprocessable' } '429': { $ref: '#/components/responses/RateLimited' } '502': { $ref: '#/components/responses/ProviderUnavailable' } /v1/charges: get: tags: [Cobranças] summary: Listar as cobranças do cliente description: Mais recentes primeiro. Lê o último estado conhecido (atualizado por webhook e pela consulta individual). operationId: listCharges parameters: - { name: method, in: query, schema: { $ref: '#/components/schemas/PaymentMethod' } } - { name: status, in: query, schema: { $ref: '#/components/schemas/ChargeStatus' } } - { name: createdFrom, in: query, description: 'Criadas a partir de (AAAA-MM-DD)', schema: { type: string, format: date } } - { name: createdTo, in: query, description: 'Criadas até (AAAA-MM-DD)', schema: { type: string, format: date } } - { name: externalReference, in: query, schema: { type: string } } - { name: page, in: query, schema: { type: integer, minimum: 1, default: 1 } } - { name: pageSize, in: query, schema: { type: integer, minimum: 1, maximum: 100, default: 20 } } responses: '200': description: Página de cobranças. headers: X-Rapp-Environment: { $ref: '#/components/headers/X-Rapp-Environment' } content: application/json: schema: { $ref: '#/components/schemas/ChargeList' } examples: pagina: { $ref: '#/components/examples/ChargeListPage' } '400': { $ref: '#/components/responses/ValidationError' } '401': { $ref: '#/components/responses/Unauthorized' } '403': { $ref: '#/components/responses/Forbidden' } '429': { $ref: '#/components/responses/RateLimited' } /v1/charges/{id}: get: tags: [Cobranças] summary: Consultar uma cobrança description: 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. operationId: getCharge parameters: - $ref: '#/components/parameters/ChargeId' responses: '200': description: Cobrança. headers: X-Rapp-Environment: { $ref: '#/components/headers/X-Rapp-Environment' } content: application/json: schema: { $ref: '#/components/schemas/Charge' } examples: paga: { $ref: '#/components/examples/PaidBoletoCharge' } '401': { $ref: '#/components/responses/Unauthorized' } '403': { $ref: '#/components/responses/Forbidden' } '404': { $ref: '#/components/responses/NotFound' } '429': { $ref: '#/components/responses/RateLimited' } /v1/charges/{id}/transactions/{transactionId}/boleto.pdf: get: tags: [Cobranças] summary: Baixar o PDF do boleto description: | 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. operationId: downloadBoletoPdf parameters: - $ref: '#/components/parameters/ChargeId' - $ref: '#/components/parameters/TransactionId' responses: '200': description: Arquivo PDF do boleto. headers: X-Rapp-Environment: { $ref: '#/components/headers/X-Rapp-Environment' } content: application/pdf: schema: { type: string, format: binary } '401': { $ref: '#/components/responses/Unauthorized' } '403': { $ref: '#/components/responses/Forbidden' } '404': { $ref: '#/components/responses/NotFound' } '429': { $ref: '#/components/responses/RateLimited' } /v1/charges/{id}/cancel: post: tags: [Cobranças] summary: Cancelar cobrança ainda não paga description: | 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. operationId: cancelCharge parameters: - $ref: '#/components/parameters/ChargeId' - $ref: '#/components/parameters/IdempotencyKey' responses: '200': description: Cobrança cancelada. headers: X-Rapp-Environment: { $ref: '#/components/headers/X-Rapp-Environment' } Idempotent-Replayed: { $ref: '#/components/headers/Idempotent-Replayed' } content: application/json: schema: { $ref: '#/components/schemas/Charge' } examples: cancelada: { $ref: '#/components/examples/CanceledCharge' } '401': { $ref: '#/components/responses/Unauthorized' } '403': { $ref: '#/components/responses/Forbidden' } '404': { $ref: '#/components/responses/NotFound' } '409': { $ref: '#/components/responses/Conflict' } '502': { $ref: '#/components/responses/ProviderUnavailable' } /v1/charges/{id}/refund: post: tags: [Cobranças] summary: Estornar cobrança paga (cartão ou Pix) description: | 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. operationId: refundCharge parameters: - $ref: '#/components/parameters/ChargeId' - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: false content: application/json: schema: { $ref: '#/components/schemas/RefundRequest' } examples: total: { $ref: '#/components/examples/RefundRequestTotal' } parcial: { $ref: '#/components/examples/RefundRequestPartial' } responses: '200': description: Cobrança estornada (total ou parcial). headers: X-Rapp-Environment: { $ref: '#/components/headers/X-Rapp-Environment' } Idempotent-Replayed: { $ref: '#/components/headers/Idempotent-Replayed' } content: application/json: schema: { $ref: '#/components/schemas/Charge' } examples: estornada: { $ref: '#/components/examples/RefundedPixCharge' } '400': { $ref: '#/components/responses/ValidationError' } '401': { $ref: '#/components/responses/Unauthorized' } '403': { $ref: '#/components/responses/Forbidden' } '404': { $ref: '#/components/responses/NotFound' } '409': { $ref: '#/components/responses/Conflict' } '422': { $ref: '#/components/responses/Unprocessable' } '502': { $ref: '#/components/responses/ProviderUnavailable' } /v1/sandbox/charges/{id}/simulate-payment: post: tags: [Sandbox] summary: Simular pagamento (só sandbox) description: 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. operationId: simulatePayment parameters: - $ref: '#/components/parameters/ChargeId' - $ref: '#/components/parameters/IdempotencyKey' responses: '200': description: Cobrança paga (simulação). headers: X-Rapp-Environment: { $ref: '#/components/headers/X-Rapp-Environment' } Idempotent-Replayed: { $ref: '#/components/headers/Idempotent-Replayed' } content: application/json: schema: { $ref: '#/components/schemas/Charge' } examples: paga: { $ref: '#/components/examples/PaidBoletoCharge' } '401': { $ref: '#/components/responses/Unauthorized' } '403': { $ref: '#/components/responses/Forbidden' } '404': { $ref: '#/components/responses/NotFound' } '409': { $ref: '#/components/responses/Conflict' } '422': { $ref: '#/components/responses/Unprocessable' } '502': { $ref: '#/components/responses/ProviderUnavailable' } components: securitySchemes: apiKey: type: http scheme: bearer description: 'Authorization: Bearer rk_sandbox_... (sandbox) ou rk_live_... (produção)' parameters: IdempotencyKey: name: Idempotency-Key in: header required: true description: 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. schema: { type: string, maxLength: 255, example: pedido-123-tentativa-1 } ChargeId: name: id in: path required: true schema: { type: string, example: chg_7f3a9c2e1b4d5a6f8e9c0b1a } TransactionId: name: transactionId in: path required: true schema: { type: string, example: "5001", pattern: "^[1-9][0-9]{0,19}$" } headers: X-Rapp-Environment: description: Ambiente que respondeu (sandbox ou production). schema: { type: string, enum: [sandbox, production] } Idempotent-Replayed: description: '"true" quando a resposta é a repetição de um POST anterior com a mesma Idempotency-Key.' schema: { type: string } responses: ValidationError: description: Requisição inválida. content: application/json: schema: { $ref: '#/components/schemas/Error' } examples: camposInvalidos: { $ref: '#/components/examples/ErrorValidation' } semIdempotencyKey: { $ref: '#/components/examples/ErrorIdempotencyKeyRequired' } Unauthorized: description: Chave ausente, inválida, revogada ou de outro ambiente. content: application/json: schema: { $ref: '#/components/schemas/Error' } examples: chaveInvalida: { $ref: '#/components/examples/ErrorUnauthorized' } outroAmbiente: { $ref: '#/components/examples/ErrorEnvironmentMismatch' } Forbidden: description: Chave válida, mas sem permissão para esta operação. content: application/json: schema: { $ref: '#/components/schemas/Error' } examples: semEscopo: { $ref: '#/components/examples/ErrorInsufficientScope' } NotFound: description: Cobrança não encontrada (ou de outro cliente), ou rota inexistente neste ambiente. content: application/json: schema: { $ref: '#/components/schemas/Error' } examples: naoEncontrada: { $ref: '#/components/examples/ErrorNotFound' } Conflict: description: Conflito de estado. content: application/json: schema: { $ref: '#/components/schemas/Error' } examples: emAndamento: { $ref: '#/components/examples/ErrorIdempotencyInProgress' } naoCancelavel: { $ref: '#/components/examples/ErrorChargeNotCancelable' } naoEstornavel: { $ref: '#/components/examples/ErrorChargeNotRefundable' } Unprocessable: description: Requisição entendida, mas recusada. content: application/json: schema: { $ref: '#/components/schemas/Error' } examples: chaveReutilizada: { $ref: '#/components/examples/ErrorIdempotencyKeyReused' } recusadaPeloProcessador: { $ref: '#/components/examples/ErrorProviderRejected' } saldoAReceberInsuficiente: { $ref: '#/components/examples/ErrorInsufficientReceivables' } estornoNaoSuportado: { $ref: '#/components/examples/ErrorRefundNotSupported' } RateLimited: description: Limite de requisições por minuto da chave excedido. Veja o cabeçalho Retry-After. headers: Retry-After: description: Segundos até a próxima janela. schema: { type: integer } content: application/json: schema: { $ref: '#/components/schemas/Error' } examples: limite: { $ref: '#/components/examples/ErrorRateLimited' } ProviderUnavailable: description: O processador não respondeu. Repita com a mesma Idempotency-Key. content: application/json: schema: { $ref: '#/components/schemas/Error' } examples: indisponivel: { $ref: '#/components/examples/ErrorProviderUnavailable' } schemas: Money: type: number exclusiveMinimum: 0 description: > 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. NonNegativeMoney: type: number minimum: 0 description: > Valor em reais (BRL) com no máximo 2 casas decimais, inclusive zero. Também aceita texto decimal ("0" ou "5.50"). NullableMoney: type: number nullable: true description: Valor em reais (BRL) com no máximo 2 casas decimais, ou null. ValidationReason: type: string enum: [required, invalid_type, invalid_format, unexpected_field, out_of_range, invalid_value] description: Motivo estável do validation_error (um por resposta). PaymentMethod: type: string enum: [boleto, pix, card] ChargeStatus: type: string enum: [pending, awaiting_payment, paid, partially_refunded, refunded, canceled, expired, rejected] Address: type: object required: [street, number, district, city, state, zipCode] properties: street: { type: string, maxLength: 120 } number: { type: string, maxLength: 20 } complement: { type: string, maxLength: 120 } district: { type: string, maxLength: 80 } city: { type: string, maxLength: 80 } state: { type: string, minLength: 2, maxLength: 2, description: Sigla da UF } zipCode: { type: string, description: CEP com 8 dígitos (pontuação opcional) } Payer: type: object required: [name, email, document, address] properties: name: { type: string, maxLength: 120 } email: { type: string, maxLength: 254 } document: { type: string, pattern: '^\\d{11}$|^\\d{14}$', description: CPF (11 dígitos) ou CNPJ (14 dígitos), apenas números, sem pontuação } phone: { type: string, pattern: '^\\d{10,13}$', description: Com DDD, apenas números (10 a 13 dígitos), sem pontuação } address: { $ref: '#/components/schemas/Address' } BoletoChargeRequest: type: object required: [amount, payer] properties: amount: { $ref: '#/components/schemas/Money' } description: { type: string, maxLength: 255 } externalReference: { type: string, maxLength: 64, description: Seu identificador do pedido } payer: { $ref: '#/components/schemas/Payer' } dueDate: { type: string, format: date, description: Vencimento (hoje ou depois, horário de Brasília). Sem data, vence amanhã. } pixEnabled: { type: boolean, default: false, description: Boleto híbrido com PIX copia-e-cola } PixChargeRequest: type: object required: [amount, payer] properties: amount: { $ref: '#/components/schemas/Money' } description: { type: string, maxLength: 255 } externalReference: { type: string, maxLength: 64 } payer: { $ref: '#/components/schemas/Payer' } dueDate: { type: string, format: date } CardChargeRequest: type: object required: [amount, antifraud, items] properties: amount: { $ref: '#/components/schemas/Money' } description: { type: string, maxLength: 255 } externalReference: { type: string, maxLength: 64 } cardToken: { type: string, maxLength: 64, description: Token ctok_ de cobrança anterior (não envie junto com card) } card: type: object required: [number, holderName, expiryMonth, expiryYear, securityCode] properties: number: { type: string, description: 13 a 19 dígitos } holderName: { type: string, maxLength: 80 } expiryMonth: { type: integer, minimum: 1, maximum: 12 } expiryYear: { type: integer, minimum: 2000, maximum: 2100 } securityCode: { type: string, description: 3 ou 4 dígitos } payer: { $ref: '#/components/schemas/Payer' } installments: { type: integer, minimum: 1, default: 1 } antifraud: type: object required: [sessionId] properties: sessionId: { type: string, format: uuid, maxLength: 128, description: UUID da sessão do fingerprint antifraude (SessionID da ClearSale; o processador exige UUID) } shippingAmount: { $ref: '#/components/schemas/NonNegativeMoney' } payerIp: { type: string, maxLength: 45 } items: type: array minItems: 1 items: type: object required: [name, amount] properties: name: { type: string, maxLength: 120 } amount: { $ref: '#/components/schemas/Money' } description: { type: string } category: { type: string, maxLength: 80 } reference: { type: string, maxLength: 64 } RefundRequest: type: object additionalProperties: false properties: amount: allOf: - $ref: '#/components/schemas/Money' description: Valor a estornar em reais. Sem este campo, estorna o saldo restante. reason: type: string enum: [DUPLICATE, FRAUDULENT, REQUESTED_BY_CUSTOMER, OTHER] default: REQUESTED_BY_CUSTOMER description: Motivo informativo do estorno. O padrão é REQUESTED_BY_CUSTOMER. Boleto: type: object nullable: true additionalProperties: false required: [digitableLine, barcode, pdfUrl, pixCopyPaste] properties: digitableLine: { type: string, nullable: true, description: Linha digitável } barcode: { type: string, nullable: true, description: Código de barras (44 dígitos) } pdfUrl: { type: string, nullable: true, description: URL autenticada da Rapp para baixar o PDF do boleto (GET, com a mesma chave de API) } pixCopyPaste: { type: string, nullable: true, description: PIX copia-e-cola do boleto híbrido } Pix: type: object nullable: true additionalProperties: false required: [copyPaste, qrCodeText, expiresAt, endToEndId] properties: copyPaste: { type: string, nullable: true, description: Código copia-e-cola } qrCodeText: { type: string, nullable: true, description: Texto para gerar o QR Code } expiresAt: { type: string, format: date-time, nullable: true } endToEndId: { type: string, nullable: true, description: Identificador E2E do pagamento (quando pago) } Card: type: object nullable: true additionalProperties: false required: [brand, lastFourDigits, authorizationCode] properties: brand: { type: string, nullable: true } lastFourDigits: { type: string, nullable: true } authorizationCode: { type: string, nullable: true } Transaction: type: object additionalProperties: false required: [id, object, status, amount, paidAmount, refundedAmount, installmentNumber, dueDate, billedAt, paidAt, failureReason, boleto, pix, card] properties: id: { type: string } object: { type: string, enum: [transaction] } status: { $ref: '#/components/schemas/ChargeStatus' } amount: { $ref: '#/components/schemas/NullableMoney' } paidAmount: { $ref: '#/components/schemas/NullableMoney' } refundedAmount: { $ref: '#/components/schemas/NullableMoney' } installmentNumber: { type: integer, nullable: true } dueDate: { type: string, format: date, nullable: true } billedAt: { type: string, format: date-time, nullable: true } paidAt: { type: string, format: date-time, nullable: true } failureReason: { type: string, nullable: true } boleto: { $ref: '#/components/schemas/Boleto' } pix: { $ref: '#/components/schemas/Pix' } card: { $ref: '#/components/schemas/Card' } Charge: type: object additionalProperties: false required: [id, object, environment, method, status, amount, currency, installments, description, externalReference, dueDate, split, cardToken, transactions, canceledAt, createdAt, updatedAt] properties: id: { type: string } object: { type: string, enum: [charge] } environment: { type: string, enum: [sandbox, production] } method: { $ref: '#/components/schemas/PaymentMethod' } status: { $ref: '#/components/schemas/ChargeStatus' } amount: { $ref: '#/components/schemas/Money' } currency: { type: string, enum: [BRL] } installments: { type: integer } description: { type: string, nullable: true } externalReference: { type: string, nullable: true } dueDate: { type: string, format: date, nullable: true } split: type: object nullable: true additionalProperties: false required: [payoutRuleId] properties: payoutRuleId: { type: string } cardToken: { type: string, nullable: true, description: Token ctok_ para reusar o mesmo cartão (baseado no payment profile da cobrança anterior) } transactions: type: array items: { $ref: '#/components/schemas/Transaction' } canceledAt: { type: string, format: date-time, nullable: true } createdAt: { type: string, format: date-time } updatedAt: { type: string, format: date-time } ChargeList: type: object additionalProperties: false required: [data, pagination] properties: data: type: array items: { $ref: '#/components/schemas/Charge' } pagination: type: object additionalProperties: false required: [page, pageSize, total, totalPages] properties: page: { type: integer } pageSize: { type: integer } total: { type: integer } totalPages: { type: integer } Environment: type: object additionalProperties: false required: [object, environment, livemode, apiVersion, features, apiKey] properties: object: { type: string, enum: [environment] } environment: { type: string, enum: [sandbox, production] } livemode: { type: boolean, description: true em produção } apiVersion: { type: string, enum: [v1] } features: type: object additionalProperties: false required: [cardCharges, cancelCharges, refundCharges, simulatePayment] properties: cardCharges: { type: boolean, description: Sempre true. Cobrança no cartão está disponível. } cancelCharges: { type: boolean, description: Sempre true. Cancelamento de cobrança em aberto está disponível. } refundCharges: { type: boolean, description: Sempre true. Estorno de cartão ou Pix pago está disponível. } simulatePayment: { type: boolean, description: true só no sandbox. } apiKey: type: object additionalProperties: false required: [scopes, rateLimitPerMinute] properties: scopes: type: array items: { type: string, enum: ['charges:read', 'charges:write'] } rateLimitPerMinute: { type: integer } WebhookEvent: type: object additionalProperties: false required: [id, object, type, environment, createdAt, data] description: Corpo enviado ao webhook do cliente. properties: id: { type: string, description: Id do evento (evt_...) } object: { type: string, enum: [event] } type: type: string enum: [charge.awaiting_payment, charge.paid, charge.partially_refunded, charge.refunded, charge.canceled, charge.expired, charge.rejected, charge.disputed] environment: { type: string, enum: [sandbox, production] } createdAt: { type: string, format: date-time } data: { $ref: '#/components/schemas/Charge' } Error: type: object additionalProperties: false required: [error] properties: error: type: object additionalProperties: false required: [code, message, requestId] properties: code: type: string description: Código estável para tratar por programa. enum: - validation_error - invalid_json - unsupported_media_type - payload_too_large - idempotency_key_required - unauthorized - environment_mismatch - insufficient_scope - ip_not_allowed - client_inactive - client_not_configured - sandbox_only - not_found - method_not_allowed - idempotency_in_progress - idempotency_outcome_unknown - charge_not_cancelable - charge_not_refundable - charge_not_payable - idempotency_key_reused - card_token_invalid - simulation_not_supported - refund_not_supported - cancel_not_confirmed - insufficient_receivables - provider_rejected - rate_limited - internal_error - provider_unavailable message: { type: string } field: type: string description: Caminho do campo inválido. Presente só em validation_error. reason: $ref: '#/components/schemas/ValidationReason' details: type: array description: Presente nos demais erros (ex. provider_rejected). Ausente em validation_error. items: type: object additionalProperties: false properties: field: { type: string } message: { type: string } providerField: { type: string, nullable: true } providerCode: { type: string, nullable: true } requestId: { type: string } examples: EnvironmentSandbox: summary: Sandbox value: 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 EnvironmentProduction: summary: Produção value: 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 BoletoRequest: summary: Boleto value: amount: 150.00 dueDate: 2026-11-30 description: Mensalidade novembro externalReference: pedido-123 payer: &a1 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 BoletoWithPixRequest: summary: Boleto com PIX (híbrido) value: amount: 150.00 dueDate: 2026-11-30 description: Mensalidade novembro externalReference: pedido-124 pixEnabled: true payer: *a1 PixRequest: summary: PIX value: amount: 150.00 description: Pedido 125 externalReference: pedido-125 payer: *a1 CardRequest: summary: Cartão (dados do cartão) value: 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: *a1 antifraud: sessionId: 3f1a0c2e-9b74-4d21-8a6e-0c5b7d4e91aa shippingAmount: 0 payerIp: 203.0.113.10 items: - name: Plano anual amount: 300.00 reference: SKU-001 CardTokenRequest: summary: Cartão (cardToken salvo) value: 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 BoletoCharge: summary: Boleto criado value: &a4 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: &a2 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 BoletoWithPixCharge: summary: Boleto híbrido criado value: 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 PixCharge: summary: PIX criado value: &a3 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 CardCharge: summary: Cartão aprovado value: 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 PaidBoletoCharge: summary: Boleto pago value: &a5 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: *a2 pix: null card: null canceledAt: null createdAt: 2026-11-16T13:05:12.345Z updatedAt: 2026-11-16T13:20:01.002Z CanceledCharge: summary: Boleto cancelado value: 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: *a2 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 RefundRequestTotal: summary: Estorno total (saldo restante) value: reason: REQUESTED_BY_CUSTOMER RefundRequestPartial: summary: Estorno parcial value: amount: 50.00 reason: REQUESTED_BY_CUSTOMER RefundedPixCharge: summary: PIX estornado por completo value: 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 ChargeListPage: summary: Página 1 de 2 value: data: - *a3 - *a4 pagination: page: 1 pageSize: 2 total: 3 totalPages: 2 WebhookChargePaid: summary: Evento charge.paid value: id: evt_5e6f7a8b9c0d1e2f3a4b5c6d object: event type: charge.paid environment: sandbox createdAt: 2026-11-16T13:20:01.010Z data: *a5 ErrorValidation: summary: Campo inválido value: 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 ErrorIdempotencyKeyRequired: summary: Sem Idempotency-Key value: 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 ErrorUnauthorized: summary: Chave inválida value: error: code: unauthorized message: Chave de API ausente ou inválida. details: [] requestId: req_3b9d0c7a1e2f4a5b ErrorEnvironmentMismatch: summary: Chave de outro ambiente value: 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 ErrorInsufficientScope: summary: Sem escopo value: error: code: insufficient_scope message: A chave não tem o escopo charges:write. details: [] requestId: req_3b9d0c7a1e2f4a5b ErrorNotFound: summary: Não encontrada value: error: code: not_found message: Cobrança não encontrada. details: [] requestId: req_3b9d0c7a1e2f4a5b ErrorIdempotencyInProgress: summary: Em andamento value: error: code: idempotency_in_progress message: Uma requisição com esta Idempotency-Key ainda está em andamento. details: [] requestId: req_3b9d0c7a1e2f4a5b ErrorChargeNotCancelable: summary: Não cancelável value: error: code: charge_not_cancelable message: Cobrança com status paid não pode ser cancelada. details: [] requestId: req_3b9d0c7a1e2f4a5b ErrorChargeNotRefundable: summary: Não estornável value: error: code: charge_not_refundable message: Cobrança com status awaiting_payment não pode ser estornada. details: [] requestId: req_3b9d0c7a1e2f4a5b ErrorRefundNotSupported: summary: Estorno não suportado value: 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 ErrorIdempotencyKeyReused: summary: Chave reutilizada value: error: code: idempotency_key_reused message: Esta Idempotency-Key já foi usada com outro corpo de requisição. details: [] requestId: req_3b9d0c7a1e2f4a5b ErrorInsufficientReceivables: summary: Saldo a receber insuficiente para o estorno value: error: code: insufficient_receivables message: O saldo a receber não cobre o valor do estorno. details: [] requestId: req_3b9d0c7a1e2f4a5b ErrorProviderRejected: summary: Recusada pelo processador value: 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 ErrorRateLimited: summary: Limite excedido value: error: code: rate_limited message: Limite de requisições da chave excedido. Tente novamente em instantes. details: [] requestId: req_3b9d0c7a1e2f4a5b ErrorProviderUnavailable: summary: Processador fora value: error: code: provider_unavailable message: O processador de pagamentos não respondeu. Tente novamente com a mesma Idempotency-Key. details: [] requestId: req_3b9d0c7a1e2f4a5b