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. 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 no confirm da checkout session e no confirm do payment intent, sempre com status 422, 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`	`pending`	`null`	`null`	`null`

Na charge aprovada, payment_error é null. Nos casos processing e pending, 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 primeira cobrança e podem ser salvos normalmente. O resultado especial aparece somente quando o mesmo cartão é cobrado de novo como cartão salvo — por exemplo, em uma oferta posterior de um funil.

Cartão	Primeira cobrança	Cobrança 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. 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; payment_error.network_decline_code só aparece quando o cenário de teste fornece evidência bruta confiável de rede.

Cartão	Resultado/status	`payment_error.category`	`payment_error.code`	Mensagem esperada
`4000000000009995`	`requires_payment_method`	`issuer_declined`	`insufficient_funds`	The card has insufficient funds to complete the purchase.
`4000009000000011`	`requires_payment_method`	`issuer_declined`	`do_not_honor`	The issuer declined the transaction without a specific reason.
`4000000000000002`	`requires_payment_method`	`issuer_declined`	`generic_decline`	The card was declined.
`4000009000000029`	`requires_payment_method`	`issuer_declined`	`call_issuer`	The card was declined. The cardholder must contact the issuer.
`4000009000000037`	`requires_payment_method`	`issuer_declined`	`card_velocity_exceeded`	The card exceeded its balance, credit, or transaction limit.
`4000009000000045`	`requires_payment_method`	`issuer_declined`	`invalid_amount`	The transaction amount is not allowed for this card.
`4000009000000052`	`requires_payment_method`	`issuer_declined`	`invalid_account`	The account linked to the card is invalid or does not exist.
`4000009000000060`	`requires_payment_method`	`issuer_declined`	`transaction_not_permitted`	This type of transaction is not permitted for the cardholder.
`4000009000000078`	`requires_payment_method`	`issuer_declined`	`service_not_allowed`	This transaction is not permitted for the card.
`4000009000000086`	`requires_payment_method`	`issuer_declined`	`card_not_supported`	The card does not support this type of purchase.
`4000009000000094`	`requires_payment_method`	`issuer_declined`	`currency_not_supported`	The card does not support the transaction currency.
`4000009000000102`	`requires_payment_method`	`issuer_declined`	`card_not_activated`	The card has not been activated.
`4000009000000110`	`requires_payment_method`	`issuer_declined`	`authentication_required`	The transaction requires cardholder authentication.
`4000009000000441`	`requires_payment_method`	`processing_error`	`authentication_not_available`	Cardholder authentication is not available for this payment.
`4000009000000458`	`requires_payment_method`	`invalid`	`new_account_information_available`	Updated card or account information is required.
`4000009000000128`	`requires_payment_method`	`issuer_declined`	`reenter_transaction`	The issuer could not process the transaction. Try again.
`4000009000000136`	`requires_payment_method`	`issuer_declined`	`approve_with_id`	The payment could not be authorized.
`4000009000000144`	`requires_payment_method`	`issuer_declined`	`not_permitted`	The requested operation is not supported by the card.
`4000000000000069`	`requires_payment_method`	`invalid`	`expired_card`	The card has expired.
`4000000000000127`	`requires_payment_method`	`invalid`	`incorrect_cvc`	The card security code (CVC) is incorrect.
`4000009000000151`	`requires_payment_method`	`invalid`	`incorrect_number`	The card number is incorrect.
`4000009000000169`	`requires_payment_method`	`invalid`	`invalid_number`	The card number is invalid or the issuer does not exist.
`4000009000000177`	`requires_payment_method`	`invalid`	`incorrect_pin`	The card PIN is incorrect.
`4000009000000185`	`requires_payment_method`	`invalid`	`invalid_pin`	The card PIN is invalid.
`4000009000000193`	`requires_payment_method`	`invalid`	`pin_try_exceeded`	The allowable number of PIN tries was exceeded.
`4000009000000201`	`requires_payment_method`	`invalid`	`invalid_transaction`	The transaction is invalid.
`4000009000000219`	`requires_payment_method`	`invalid`	`no_payment_method`	No payment method available to charge.
`4000009000000227`	`requires_payment_method`	`invalid`	`card_unusable`	The saved card could not be used.
`4000009000000235`	`requires_payment_method`	`invalid`	`payment_method_mismatch`	The payment method does not belong to this customer.
`4000009000000466`	`requires_payment_method`	`invalid`	`invalid_cvc`	The card security code has an invalid format.
`4000009000000474`	`requires_payment_method`	`invalid`	`invalid_expiry_month`	The card expiration month has an invalid format.
`4000009000000482`	`requires_payment_method`	`invalid`	`invalid_expiry_year`	The card expiration year has an invalid format.
`4000009000000490`	`requires_payment_method`	`invalid`	`invalid_name`	The cardholder name is invalid.
`4000009000000508`	`requires_payment_method`	`invalid`	`invalid_request`	The payment request contains invalid data.
`4000009000000516`	`requires_payment_method`	`invalid`	`invalid_token`	The card token is invalid or expired.
`4000009000000243`	`requires_payment_method`	`blocked`	`lost_card`	The card was reported lost.
`4000009000000250`	`requires_payment_method`	`blocked`	`stolen_card`	The card was reported stolen.
`4000009000000268`	`requires_payment_method`	`blocked`	`pickup_card`	The card cannot be used (retain card).
`4000009000000276`	`requires_payment_method`	`blocked`	`restricted_card`	The card is restricted.
`4000009000000284`	`requires_payment_method`	`blocked`	`fraudulent`	The transaction was flagged as suspected fraud.
`4000009000000292`	`requires_payment_method`	`blocked`	`security_violation`	The transaction was declined for a security violation.
`4000009000000300`	`requires_payment_method`	`blocked`	`stop_payment_order`	A stop payment order applies to this card.
`4000009000000318`	`requires_payment_method`	`blocked`	`revocation_of_authorization`	Authorization for this card has been revoked.
`4000009000000326`	`requires_payment_method`	`blocked`	`revocation_of_all_authorizations`	All authorizations for this card have been revoked.
`4000009000000334`	`requires_payment_method`	`blocked`	`transaction_not_allowed`	The transaction is not allowed.
`4000009000000524`	`requires_payment_method`	`blocked`	`single_use_card`	This card cannot be reused for this payment.
`4000009000000342`	`requires_payment_method`	`processing_error`	`issuer_unavailable`	The card issuer could not be reached. Try again.
`4000009000000359`	`requires_payment_method`	`processing_error`	`routing_error`	The transaction could not be routed to the issuer.
`4000009000000367`	`requires_payment_method`	`processing_error`	`duplicate_transaction`	A duplicate transaction was detected.
`4000009000000375`	`requires_payment_method`	`processing_error`	`try_again_later`	The payment could not be processed. Try again later.
`4000009000000383`	`requires_payment_method`	`processing_error`	`connection_error`	Could not reach the payment provider. Please try again.
`4000009000000391`	`requires_payment_method`	`processing_error`	`customer_unavailable`	Customer could not be identified for the charge.
`4000000000000119`	`requires_payment_method`	`processing_error`	`processing_error`	An error occurred while processing the payment. Try again.
`4000009000000532`	`requires_payment_method`	`processing_error`	`merchant_not_approved`	The merchant account is not available for this payment.
`4000009000000540`	`requires_payment_method`	`processing_error`	`authorization_expired`	The authorization expired before capture.
`4000009000000557`	`requires_payment_method`	`processing_error`	`capture_method_not_supported`	The selected capture method is not supported.
`4000009000000565`	`requires_payment_method`	`processing_error`	`charge_already_captured`	The payment was already captured.
`4000009000000573`	`requires_payment_method`	`processing_error`	`charge_already_refunded`	The payment was already refunded.
`4000009000000581`	`requires_payment_method`	`processing_error`	`partial_refund_not_supported`	This payment does not support partial refunds.
`4000009000000599`	`requires_payment_method`	`processing_error`	`payment_intent_unexpected_state`	The operation is not allowed in the payment’s current state.
`4000009000000607`	`requires_payment_method`	`processing_error`	`refund_period_expired`	The refund window for this payment has expired.
`4000009000000615`	`requires_payment_method`	`processing_error`	`refund_state_mismatch`	The refund state could not be reconciled.
`4000009000000409`	`requires_payment_method`	`issuer_declined`	`testmode_decline`	A test card triggered a decline.
`4000009000000417`	`requires_payment_method`	`issuer_declined`	`payment_failed`	Payment failed.

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
`succeed_immediately@meusite.com`	`succeeded`	Nenhuma; o pagamento já nasce concluído.
`succeed_delayed@meusite.com`	`pending`	Muda para `succeeded` após cerca de 3 minutos.
`expire_immediately@meusite.com`	`requires_payment_method`	Nenhuma; o código já nasce vencido e o intent aceita outro.
`expire_delayed@meusite.com`	`pending`	Muda para `requires_payment_method` após cerca de 3 minutos.
`pending@meusite.com`	`pending`	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.

Boleto continua exigindo CPF/CNPJ e endereço válidos. Use esses campos para testar validação cadastral; 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 pending. 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 pending, 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 Ativação por API e vale para os dois caminhos de cadastro, o hospedado e o por API.

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

Objetos de sistema

Webhooks e eventos

SDKs

MCP

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

Simular PIX e boleto

Controles no checkout hospedado

Webhooks em test mode

Ativação de organizações 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

​Simular PIX e boleto

​Controles no checkout hospedado

​Webhooks em test mode

​Ativação de organizações 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

Simular PIX e boleto

Controles no checkout hospedado

Webhooks em test mode

Ativação de organizações no sandbox

Contas para saques no sandbox

Ir para produção