> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chargefy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox

> Use test mode para desenvolver integrações, validar webhooks e simular falhas sem efeito financeiro real.

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

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

<Tip>
  No dashboard, use o seletor **Live / Test** na navegação lateral para alternar
  entre dados reais e dados de sandbox.
</Tip>

## Simular cartões

Em checkouts hospedados, no [Chargefy.js](/features/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.

```bash theme={}
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.

```bash theme={}
curl -X POST "https://api.chargefy.io/v1/test-helpers/payment-intents/pi_123/succeed" \
  -H "Authorization: Bearer {{API_KEY}}"
```

Você também pode usar o ID da checkout session quando a cobrança nasceu no Checkout:

```bash theme={}
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.   |

<Tip>
  Test helpers só aceitam chaves `ch_test_...`. Chamadas em live mode retornam
  erro `testmode_required`.
</Tip>

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