O sandbox da Chargefy usa o mesmo endpoint, os mesmos objetos e os mesmos webhooks da produção. A separação vem do ambiente da API key:
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 têm efeito financeiro real e ficam isolados dos dados de produção. Use chaves separadas para desenvolvimento, staging e produção.
Criar uma chave de teste
No dashboard, abra Settings → Chaves de API, clique em Nova chave e selecione o ambiente test. O token gerado começa com ch_test_.
curl https://api.chargefy.io/v1/customers \
-H "Authorization: Bearer {{API_KEY}}"
No dashboard, use o seletor Live / Test na navegação lateral para alternar
entre dados reais e dados de sandbox.
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 |
Falhas de cartão
| Cartão | Resultado/status | payment_error.category | payment_error.code | Mensagem esperada |
|---|
4000000000009995 | failed | issuer_declined | insufficient_funds | The card has insufficient funds to complete the purchase. |
4000009000000011 | failed | issuer_declined | do_not_honor | The issuer declined the transaction without a specific reason. |
4000000000000002 | failed | issuer_declined | generic_decline | The card was declined. |
4000009000000029 | failed | issuer_declined | call_issuer | The card was declined. The cardholder must contact the issuer. |
4000009000000037 | failed | issuer_declined | card_velocity_exceeded | The card exceeded its balance, credit, or transaction limit. |
4000009000000045 | failed | issuer_declined | invalid_amount | The transaction amount is not allowed for this card. |
4000009000000052 | failed | issuer_declined | invalid_account | The account linked to the card is invalid or does not exist. |
4000009000000060 | failed | issuer_declined | transaction_not_permitted | This type of transaction is not permitted for the cardholder. |
4000009000000078 | failed | issuer_declined | service_not_allowed | This transaction is not permitted for the card. |
4000009000000086 | failed | issuer_declined | card_not_supported | The card does not support this type of purchase. |
4000009000000094 | failed | issuer_declined | currency_not_supported | The card does not support the transaction currency. |
4000009000000102 | failed | issuer_declined | card_not_activated | The card has not been activated. |
4000009000000110 | failed | issuer_declined | authentication_required | The transaction requires cardholder authentication. |
4000009000000128 | failed | issuer_declined | reenter_transaction | The issuer could not process the transaction. Try again. |
4000009000000136 | failed | issuer_declined | approve_with_id | The payment could not be authorized. |
4000009000000144 | failed | issuer_declined | not_permitted | The requested operation is not supported by the card. |
4000000000000069 | failed | invalid | expired_card | The card has expired. |
4000000000000127 | failed | invalid | incorrect_cvc | The card security code (CVC) is incorrect. |
4000009000000151 | failed | invalid | incorrect_number | The card number is incorrect. |
4000009000000169 | failed | invalid | invalid_number | The card number is invalid or the issuer does not exist. |
4000009000000177 | failed | invalid | incorrect_pin | The card PIN is incorrect. |
4000009000000185 | failed | invalid | invalid_pin | The card PIN is invalid. |
4000009000000193 | failed | invalid | pin_try_exceeded | The allowable number of PIN tries was exceeded. |
4000009000000201 | failed | invalid | invalid_transaction | The transaction is invalid. |
4000009000000219 | failed | invalid | no_payment_method | No payment method available to charge. |
4000009000000227 | failed | invalid | card_unusable | The saved card could not be used. |
4000009000000235 | failed | invalid | payment_method_mismatch | The payment method does not belong to this customer. |
4000009000000243 | failed | blocked | lost_card | The card was reported lost. |
4000009000000250 | failed | blocked | stolen_card | The card was reported stolen. |
4000009000000268 | failed | blocked | pickup_card | The card cannot be used (retain card). |
4000009000000276 | failed | blocked | restricted_card | The card is restricted. |
4000009000000284 | failed | blocked | fraudulent | The transaction was flagged as suspected fraud. |
4000009000000292 | failed | blocked | security_violation | The transaction was declined for a security violation. |
4000009000000300 | failed | blocked | stop_payment_order | A stop payment order applies to this card. |
4000009000000318 | failed | blocked | revocation_of_authorization | Authorization for this card has been revoked. |
4000009000000326 | failed | blocked | revocation_of_all_authorizations | All authorizations for this card have been revoked. |
4000009000000334 | failed | blocked | transaction_not_allowed | The transaction is not allowed. |
4000009000000342 | failed | processing_error | issuer_unavailable | The card issuer could not be reached. Try again. |
4000009000000359 | failed | processing_error | routing_error | The transaction could not be routed to the issuer. |
4000009000000367 | failed | processing_error | duplicate_transaction | A duplicate transaction was detected. |
4000009000000375 | failed | processing_error | try_again_later | The payment could not be processed. Try again later. |
4000009000000383 | failed | processing_error | connection_error | Could not reach the payment provider. Please try again. |
4000009000000391 | failed | processing_error | customer_unavailable | Customer could not be identified for the charge. |
4000000000000119 | failed | processing_error | processing_error | An error occurred while processing the payment. Try again. |
4000009000000409 | failed | issuer_declined | testmode_decline | A test card triggered a decline. |
4000009000000417 | failed | issuer_declined | payment_failed | Payment failed. |
Simular cenários pela API
Em test mode, você também pode forçar cenários enviando metadata.sandbox_scenario no recurso que gera a cobrança.
curl https://api.chargefy.io/v1/payment-intents \
-H "Authorization: Bearer {{API_KEY}}" \
-H "Content-Type: application/json" \
-d '{
"amount": 10990,
"currency": "brl",
"metadata": {
"sandbox_scenario": "generic_decline"
},
"payment_method_types": ["credit"]
}'
Cenários suportados
| Valor | Uso |
|---|
succeeded | Aprovação imediata. |
requires_capture | Autorização pendente de captura. |
processing | Processamento em andamento. |
pending | Pagamento pendente. |
Qualquer payment_error.code da tabela acima | Falha de cartão com o código público correspondente. |
api_error | Erro interno simulado. |
pix_succeeded | PIX aprovado. |
pix_failed | PIX falhou. |
pix_pending | PIX pendente. |
boleto_succeeded | Boleto pago. |
boleto_failed | Boleto falhou. |
boleto_pending | Boleto pendente. |
boleto_expired | Boleto expirado. |
Webhooks em test mode
Eventos criados com ch_test_... são entregues apenas para endpoints criados no ambiente de teste e carregam livemode: false.
Crie pelo menos um endpoint de webhook em test antes de validar integrações de sandbox.
Simular pagamentos assíncronos
PIX e boleto podem ficar pendentes após a confirmação. Em test mode, use test helpers para simular a liquidação posterior sem esperar uma compensação real.
curl -X POST "https://api.chargefy.io/v1/test-helpers/payment-intents/pi_123/succeed" \
-H "Authorization: Bearer {{API_KEY}}"
curl -X POST "https://api.chargefy.io/v1/test-helpers/checkout-sessions/cs_123/fail" \
-H "Authorization: Bearer {{API_KEY}}"
| Ação | Resultado |
|---|
succeed | Marca o payment intent como succeeded e emite os webhooks de sucesso. |
fail | Marca o payment intent como failed e emite os webhooks de falha. |
expire | Marca o payment intent como canceled por abandono e falha a charge. |
Test helpers só aceitam chaves ch_test_.... Chamadas em live mode retornam
erro testmode_required.
Limitação atual
Onboarding de organizações conectadas (/v1/onboarding-sessions) e contas bancárias (/v1/bank-accounts) ainda não são simulados no sandbox. Requisições com ch_test_... retornam erro sandbox_unsupported; use esses fluxos apenas quando estiver pronto para enviar um cadastro real. 
