Sandbox

O sandbox é a produção com dinheiro de mentira: os mesmos endpoints, os mesmos objetos, os mesmos webhooks. O que separa os dois mundos é só a API key usada na chamada:

ch_live_... cria e consulta dados de produção (livemode: true).
ch_test_... cria e consulta dados de teste (livemode: false).

Dados de teste não movimentam dinheiro e ficam isolados dos dados de produção, com uma exceção: as organizações e o plano de taxas delas são os mesmos nos dois modos (veja Plano de taxas no sandbox). Use chaves separadas para desenvolvimento, staging e produção.

Disponível desde o primeiro minuto

O sandbox funciona de ponta a ponta antes mesmo da ativação da conta. Enquanto o cadastro está em análise, você já cria produtos, payment links, checkout sessions e payment intents de teste, paga com os cartões e e-mails determinísticos desta página e recebe os webhooks correspondentes — a integração inteira pode ficar pronta em paralelo à aprovação. A ativação só é exigida para receber pagamento real. Antes dela, o ambiente live aceita criar recursos normalmente (clientes, links, sessões), e o comprador consegue navegar o checkout até o fim — mas a confirmação do pagamento é recusada com um erro estável, sem cobrar nada:

{
  "error": {
    "code": "organization_not_activated",
    "message": "Organization is not ready to accept payments",
    "type": "invalid_request_error"
  }
}

Trate esse code como “conta ainda em ativação”: ele aparece ao confirmar uma checkout session hospedada e no confirm do payment intent, sempre com status 409, e desaparece quando a ativação é aprovada.

Criar uma chave de teste

No dashboard, abra Developers → Chaves de API, clique em Nova chave e selecione o ambiente test. O token gerado começa com ch_test_ e já funciona com a conta recém-criada.

curl https://api.chargefy.io/v1/customers \
  -H "Authorization: Bearer {{API_KEY}}"

No dashboard, o menu Minha conta alterna entre os ambientes live e sandbox a qualquer momento. Contas que ainda não ativaram começam no sandbox por padrão — mas a troca é sempre livre.

Simular cartões

Em checkouts hospedados, no Chargefy.js, na página de pagamento de fatura e nos formulários de atualização de cartão, use estes números em test mode. Use qualquer CVC de três dígitos e uma validade futura. Cartão desconhecido em test mode aprova por padrão.

Sucesso e status

Cartão	Resultado/status	`payment_error.category`	`payment_error.code`	Mensagem esperada
`4242424242424242`	`succeeded`	`null`	`null`	`null`
`4000000000003220`	`requires_capture`	`null`	`null`	`null`
`4000009000000425`	`processing`	`null`	`null`	`null`
`4000009000000433`	`processing`	`null`	`null`	`null`

Na charge aprovada, payment_error é null. Nos dois casos processing, ainda não há desfecho — não trate a ausência de erro como aprovação; aguarde o webhook.

Cartões salvos e reutilização

Os cartões abaixo aprovam a cobrança feita no checkout hospedado, inclusive a primeira cobrança de uma assinatura, que já guarda o cartão. O resultado especial aparece quando o cartão salvo é cobrado de novo fora do checkout: a renovação da assinatura, a oferta seguinte de um funil, o pagamento de fatura com cartão salvo e o confirm de um payment intent com payment_method salvo.

Cartão	Cobrança no checkout	Cobrança seguinte com o cartão salvo
`4000009000000623`	`succeeded`	`requires_payment_method`, com `payment_error.code` igual a `single_use_card`.
`4000009000000631`	`succeeded`	`processing`; aguarde o webhook e não inicie outra tentativa enquanto o resultado for incerto.

Use esses números para validar uma compra aprovada seguida de contingência ou processamento assíncrono no reúso. Em live mode, eles são tratados como números comuns e não escolhem o resultado do pagamento.

Falhas simuladas via cartão

Uma recusa encerra a tentativa, não o intent: o Payment Intent volta a requires_payment_method com o motivo em last_payment_error, e o mesmo intent aceita uma nova confirmação — use estes cartões para testar o fluxo de recusa seguida de retentativa. Pela API, o confirm recusado responde 402 com o mesmo code e o intent dentro de error.payment_intent. O sandbox também oferece cartões para erros que, em produção, podem nascer em outras etapas — como captura, tokenização ou reembolso. Nesses casos, o cartão serve para testar o contrato público, a mensagem e a saída segura da interface; ele não pretende reproduzir a etapa operacional que originou o erro real. O código Chargefy estável fica em payment_error.code, com a orientação em payment_error.advice_code. No sandbox não há rede por trás da recusa: payment_error.network_decline_code e payment_error.network_advice_code vêm sempre null. Em todos os cenários abaixo, a tentativa falha e o Payment Intent volta para requires_payment_method.

`issuer_declined` — recusa do emissor

Todos estes cartões retornam payment_error.category: "issuer_declined".

Cartão	`payment_error.code`	Mensagem esperada
`4000000000009995`	`insufficient_funds`	The card has insufficient funds to complete the purchase.
`4000009000000011`	`do_not_honor`	The issuer declined the transaction without a specific reason.
`4000000000000002`	`generic_decline`	The card was declined.
`4000009000000029`	`call_issuer`	The card was declined. The cardholder must contact the issuer.
`4000009000000037`	`card_velocity_exceeded`	The card exceeded its balance, credit, or transaction limit.
`4000009000000045`	`invalid_amount`	The transaction amount is not allowed for this card.
`4000009000000052`	`invalid_account`	The account linked to the card is invalid or does not exist.
`4000009000000060`	`transaction_not_permitted`	This type of transaction is not permitted for the cardholder.
`4000009000000078`	`service_not_allowed`	This transaction is not permitted for the card.
`4000009000000086`	`card_not_supported`	The card does not support this type of purchase.
`4000009000000094`	`currency_not_supported`	The card does not support the transaction currency.
`4000009000000102`	`card_not_activated`	The card has not been activated.
`4000009000000110`	`authentication_required`	The transaction requires cardholder authentication.
`4000009000000128`	`reenter_transaction`	The issuer could not process the transaction. Try again.
`4000009000000136`	`approve_with_id`	The payment could not be authorized.
`4000009000000144`	`not_permitted`	The requested operation is not supported by the card.
`4000009000000409`	`testmode_decline`	A test card triggered a decline.
`4000009000000417`	`payment_failed`	Payment failed.

`invalid` — dados ou método inválidos

Todos estes cartões retornam payment_error.category: "invalid".

Cartão	`payment_error.code`	Mensagem esperada
`4000009000000458`	`new_account_information_available`	Updated card or account information is required.
`4000000000000069`	`expired_card`	The card has expired.
`4000000000000127`	`incorrect_cvc`	The card security code (CVC) is incorrect.
`4000009000000151`	`incorrect_number`	The card number is incorrect.
`4000009000000169`	`invalid_number`	The card number is invalid or the issuer does not exist.
`4000009000000177`	`incorrect_pin`	The card PIN is incorrect.
`4000009000000185`	`invalid_pin`	The card PIN is invalid.
`4000009000000193`	`pin_try_exceeded`	The allowable number of PIN tries was exceeded.
`4000009000000201`	`invalid_transaction`	The transaction is invalid.
`4000009000000219`	`no_payment_method`	No payment method available to charge.
`4000009000000227`	`card_unusable`	The saved card could not be used.
`4000009000000235`	`payment_method_mismatch`	The payment method does not belong to this customer.
`4000009000000466`	`invalid_cvc`	The card security code has an invalid format.
`4000009000000474`	`invalid_expiry_month`	The card expiration month has an invalid format.
`4000009000000482`	`invalid_expiry_year`	The card expiration year has an invalid format.
`4000009000000490`	`invalid_name`	The cardholder name is invalid.
`4000009000000508`	`invalid_request`	The payment request contains invalid data.
`4000009000000516`	`invalid_token`	The card token is invalid or expired.

`blocked` — cartão ou transação bloqueada

Todos estes cartões retornam payment_error.category: "blocked".

Cartão	`payment_error.code`	Mensagem esperada
`4000009000000243`	`lost_card`	The card was reported lost.
`4000009000000250`	`stolen_card`	The card was reported stolen.
`4000009000000268`	`pickup_card`	The card cannot be used (retain card).
`4000009000000276`	`restricted_card`	The card is restricted.
`4000009000000284`	`fraudulent`	The transaction was flagged as suspected fraud.
`4000009000000292`	`security_violation`	The transaction was declined for a security violation.
`4000009000000300`	`stop_payment_order`	A stop payment order applies to this card.
`4000009000000318`	`revocation_of_authorization`	Authorization for this card has been revoked.
`4000009000000326`	`revocation_of_all_authorizations`	All authorizations for this card have been revoked.
`4000009000000334`	`transaction_not_allowed`	The transaction is not allowed.
`4000009000000524`	`single_use_card`	This card cannot be reused for this payment.

`processing_error` — falha de processamento

Todos estes cartões retornam payment_error.category: "processing_error".

Cartão	`payment_error.code`	Mensagem esperada
`4000009000000441`	`authentication_not_available`	Cardholder authentication is not available for this payment.
`4000009000000342`	`issuer_unavailable`	The card issuer could not be reached. Try again.
`4000009000000359`	`routing_error`	The transaction could not be routed to the issuer.
`4000009000000367`	`duplicate_transaction`	A duplicate transaction was detected.
`4000009000000375`	`try_again_later`	The payment could not be processed. Try again later.
`4000009000000383`	`connection_error`	Could not reach the payment provider. Please try again.
`4000009000000391`	`customer_unavailable`	Customer could not be identified for the charge.
`4000000000000119`	`processing_error`	An error occurred while processing the payment. Try again.
`4000009000000532`	`merchant_not_approved`	The merchant account is not available for this payment.
`4000009000000540`	`authorization_expired`	The authorization expired before capture.
`4000009000000557`	`capture_method_not_supported`	The selected capture method is not supported.
`4000009000000565`	`charge_already_captured`	The payment was already captured.
`4000009000000573`	`charge_already_refunded`	The payment was already refunded.
`4000009000000581`	`partial_refund_not_supported`	This payment does not support partial refunds.
`4000009000000599`	`payment_intent_unexpected_state`	The operation is not allowed in the payment’s current state.
`4000009000000607`	`refund_period_expired`	The refund window for this payment has expired.
`4000009000000615`	`refund_state_mismatch`	The refund state could not be reconciled.

Parcelamento no sandbox

Test mode parcela exatamente como produção. O teto, os juros e a decomposição do valor são calculados pela Chargefy antes de a cobrança sair, então o resultado não depende do ambiente: o mesmo count sobre o mesmo valor devolve o mesmo total em ch_test_... e em ch_live_.... Não há cartão de parcelamento nem nada para ligar. Qualquer cartão de sucesso desta página aceita de 1 a 12 parcelas, e os cartões de recusa recusam independentemente do número escolhido. O contrato completo — onde enviar installments, o que cada campo significa e como exibir as parcelas — está em Checkout white-label.

O teto de parcelas

O máximo ofertável é o menor entre três limites:

Limite	Como funciona
Máximo do cartão	12 parcelas, sempre.
Máximo da organização	O teto configurado no checkout da organização, quando houver.
Valor mínimo por parcela	Cada parcela precisa valer pelo menos R$ 7,00.

O terceiro limite é o que costuma surpreender: ele desce o teto conforme o valor da venda, sem nenhuma configuração envolvida.

Valor da venda	Máximo de parcelas
R$ 6,99	1x
R$ 14,00	2x
R$ 25,00	3x
R$ 83,99	11x
R$ 84,00	12x

A regra vale igual nos dois ambientes, e um teto de organização mais baixo sempre prevalece: com o teto em 6, uma venda de R$ 200,00 continua em 6x.

Conferir as parcelas antes de cobrar

POST /v1/payment-previews funciona com chave de teste e devolve as mesmas opções da produção, com livemode: false. É o jeito de ver o teto efetivo de um valor sem tentar uma cobrança:

curl -X POST "https://api.chargefy.io/v1/payment-previews" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2500,
    "payment_method_types": ["credit_card"]
  }'

{
  "object": "payment_preview",
  "amount": 2500,
  "currency": "brl",
  "has_surcharge": false,
  "livemode": false,
  "payment_methods": {
    "credit_card": {
      "installments": {
        "max_count": 3,
        "options": [
          {
            "amount": 2500,
            "count": 1,
            "eligible": true,
            "installment_interest_amount": 0,
            "interest_payer": "buyer",
            "minimum_amount": 700,
            "per_installment_amount": 2500,
            "surcharge_amount": 0
          },
          {
            "amount": 2575,
            "count": 2,
            "eligible": true,
            "installment_interest_amount": 75,
            "interest_payer": "buyer",
            "minimum_amount": 1475,
            "per_installment_amount": 1288,
            "surcharge_amount": 0
          },
          {
            "amount": 2601,
            "count": 3,
            "eligible": true,
            "installment_interest_amount": 101,
            "interest_payer": "buyer",
            "minimum_amount": 2201,
            "per_installment_amount": 867,
            "surcharge_amount": 0
          }
        ]
      }
    }
  }
}

max_count: 3 numa venda de R

25,00 é o mínimo por parcela agindo: a quarta parcela sairia por R

6,50.

Quem paga os juros

interest_payer vale no sandbox como em produção, nas duas formas. Com buyer, o juro entra no total do comprador. Com organization, o comprador parcela o valor à vista e o mesmo juro é descontado do líquido da organização — e essa dedução é calculada e gravada no sandbox também, então a cobrança de teste já mostra o líquido correto de uma venda parcelada com juros por conta da loja.

O que o sandbox não simula

Duas coisas do parcelamento ficam de fora, e é melhor saber antes de procurá-las:

Não existe cenário de falha específico de parcelamento. Nenhum cartão desta página força uma recusa por número de parcelas. Pedir mais parcelas do que a venda permite não chega a virar cobrança: a validação devolve 400 antes disso, com a mesma mensagem nos dois ambientes.
Nenhuma parcela liquida. A venda parcelada gera os lançamentos de transaction — um por parcela, com bruto, taxas e líquido —, mas em test mode eles ficam em status: "pending" com settled_at: null para sempre. Conciliação de repasse e data efetiva de liquidação só podem ser testadas em produção.

Erros

Situação	Resposta
`count` fora de 1 a 12, ou não inteiro	`400` em `payment_method_options.credit_card.installments.count`: `installments must be an integer between 1 and 12`.
`count` acima do teto da venda	`400` no mesmo `param`: `installments.count cannot exceed 3 for this amount` — o número é o teto daquela venda.
`installments` enviado no corpo do confirm	`400`. Defina as parcelas no create ou no update do payment intent.

Simular Pix e boleto

Em test mode, o e-mail do cliente determina o resultado de Pix e boleto. Use o mesmo valor em customer_email no Checkout ou no customer associado ao payment_intent.

E-mail	Estado inicial	Transição automática
`[email protected]`	`succeeded`	Nenhuma; o pagamento já nasce concluído.
`[email protected]`	`requires_action`	Muda para `succeeded` após cerca de 3 minutos.
`[email protected]`	`requires_payment_method`	Nenhuma; o código já nasce vencido e o intent aceita outro.
`[email protected]`	`requires_action`	Muda para `requires_payment_method` após cerca de 3 minutos.
`[email protected]`	`requires_action`	Nenhuma transição automática de teste.

O local-part precisa ser exatamente um dos valores acima; o domínio pode ser qualquer domínio válido. Em live mode esses endereços são tratados como e-mails comuns e não alteram o pagamento.

Sempre que o checkout coletar documento — inclusive em Pix e boleto — o CPF/CNPJ precisa ter dígitos verificadores válidos também no sandbox. Você pode usar o CPF fictício 529.982.247-25; use o e-mail para escolher o resultado financeiro.

Nos cenários delayed, a confirmação retorna o código Pix ou o boleto com o payment_intent em requires_action. A transição posterior passa pelo mesmo processamento financeiro e emite os mesmos webhooks de um pagamento real.

Controles no checkout hospedado

O checkout hospedado exibe uma barra amarela no topo quando livemode é false. Depois que um Pix ou boleto entra em requires_action, a própria barra mostra dois controles:

Simular pagamento entrega o evento de sucesso e leva o checkout a payment_status: "paid".
Simular expiração entrega o evento de expiração do código — o intent volta a requires_payment_method — e mantém o checkout unpaid.

Esses controles são uma conveniência visual para testes manuais. Para testes automatizados e integrações via API, use os e-mails determinísticos da tabela acima. Os dois caminhos usam o mesmo processamento e produzem os mesmos webhooks.

Webhooks em test mode

Eventos criados com ch_test_... carregam livemode: false e são entregues apenas para endpoints de webhook criados no ambiente de teste — endpoints e secrets são separados por ambiente. Crie pelo menos um endpoint em test antes de validar a integração: os pagamentos simulados desta página emitem exatamente os mesmos eventos dos pagamentos reais.

Ativação de organizações no sandbox

Este recurso só está disponível para Chargefy for Platforms.

O cadastro de organizações filhas roda ponta a ponta com ch_test_..., com desfecho determinístico escolhido pelo CPF/CNPJ da organização: aprovado, reprovado com correção, reprovado sem autoatendimento ou em análise. A tabela está em Ativar organização por API e vale para os dois caminhos de cadastro, o hospedado e o por API.

Plano de taxas no sandbox

A organização filha e o plano de taxas dela são os mesmos em teste e em produção, e o plano define o preço das vendas reais. Por isso fee_plan em criar e atualizar organização só é aceito com ch_live_.... Com ch_test_..., omita o campo: enviá-lo, mesmo null ou "default", retorna 400 com code: "livemode_mismatch".

Contas para saques no sandbox

Há dois caminhos, com comportamentos diferentes:

Dentro da ativação (hospedada ou por API): a conta para saques é exigida e simulada normalmente com ch_test_.... O objeto payout_account volta preenchido na organização — ele prova o contrato e o fluxo, mas nenhuma conta bancária real é validada e nenhum repasse acontece.
Recurso independente (/v1/payout-accounts): criar, listar e desconectar contas fora da ativação ainda não é simulado. Requisições com ch_test_... retornam 409 com code: "sandbox_unsupported"; use esse recurso apenas em produção.

Ir para produção

Sandbox e produção usam o mesmo código — só a chave muda. Dados de teste não migram: recrie produto, preço e link com a chave ch_live_... quando a conta estiver ativa. O passo a passo completo, incluindo webhooks e checklist final, está em Testar no sandbox e no Checklist de go-live.

Fundamentos da API

MCP

Objetos de sistema

Webhooks e eventos

SDKs

Disponível desde o primeiro minuto

Criar uma chave de teste

Simular cartões

Sucesso e status

Cartões salvos e reutilização

Falhas simuladas via cartão

`issuer_declined` — recusa do emissor

`invalid` — dados ou método inválidos

`blocked` — cartão ou transação bloqueada

`processing_error` — falha de processamento

Parcelamento no sandbox

O teto de parcelas

Conferir as parcelas antes de cobrar

Quem paga os juros

O que o sandbox não simula

Erros

Simular Pix e boleto

Controles no checkout hospedado

Webhooks em test mode

Ativação de organizações no sandbox

Plano de taxas no sandbox

Contas para saques no sandbox

Ir para produção

​Disponível desde o primeiro minuto

​Criar uma chave de teste

​Simular cartões

​Sucesso e status

​Cartões salvos e reutilização

​Falhas simuladas via cartão

​issuer_declined — recusa do emissor

​invalid — dados ou método inválidos

​blocked — cartão ou transação bloqueada

​processing_error — falha de processamento

​Parcelamento no sandbox

​O teto de parcelas

​Conferir as parcelas antes de cobrar

​Quem paga os juros

​O que o sandbox não simula

​Erros

​Simular Pix e boleto

​Controles no checkout hospedado

​Webhooks em test mode

​Ativação de organizações no sandbox

​Plano de taxas no sandbox

​Contas para saques no sandbox

​Ir para produção

Disponível desde o primeiro minuto

Criar uma chave de teste

Simular cartões

Sucesso e status

Cartões salvos e reutilização

Falhas simuladas via cartão

`issuer_declined` — recusa do emissor

`invalid` — dados ou método inválidos

`blocked` — cartão ou transação bloqueada

`processing_error` — falha de processamento

Parcelamento no sandbox

O teto de parcelas

Conferir as parcelas antes de cobrar

Quem paga os juros

O que o sandbox não simula

Erros

Simular Pix e boleto

Controles no checkout hospedado

Webhooks em test mode

Ativação de organizações no sandbox

Plano de taxas no sandbox

Contas para saques no sandbox

Ir para produção