> ## Documentation Index
> Fetch the complete documentation index at: https://docs.therius.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Início rápido do Therius: seu primeiro pagamento em 5 minutos
> Dispare um pagamento real de sandbox com a API do Therius em menos de cinco minutos — sem SDK, sem configuração de frontend. Só uma chave e um comando curl.
O sandbox do Therius é um ambiente de teste totalmente isolado — as requisições chegam a um stub de provedor de teste, nenhum dinheiro real se move e nenhuma rede de cartões está envolvida. Sua chave de sandbox começa com `prv_sandbox_...` e toda conta do Therius inclui uma por padrão. Tudo o que você construir aqui funciona de forma idêntica em produção; você só troca a chave e a URL base quando estiver pronto para entrar no ar.
O cabeçalho `Idempotency-Key` é obrigatório em produção. Refazer um timeout de rede sem ele pode cobrar um cliente duas vezes. Os exemplos abaixo o incluem para você criar o hábito desde o início.
## Etapas
Faça login no seu painel do Therius e copie a chave rotulada como **Sandbox Secret Key**. Ela se parece com `prv_sandbox_xxxxxxxxxxxx`.
Toda requisição para `https://api-sandbox.therius.io/v1` envia esta chave como `Authorization: Bearer prv_sandbox_...`. O prefixo da chave (`prv_sandbox_`) diz ao Therius para rotear a requisição para o ambiente de sandbox automaticamente — sem configuração adicional.
Cole o comando a seguir no seu terminal, substituindo `prv_sandbox_your_key_here` pela sua chave de sandbox real.
```bash theme={"dark"}
curl -X POST https://api-sandbox.therius.io/v1/payment/purchase \
-H "Authorization: Bearer prv_sandbox_your_key_here" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"merchantCode": "MERCHANT_001",
"orderCode": "QUICKSTART-001",
"amount": { "currency": "USD", "value": 1999, "exponent": 2 },
"card": {
"cardData": {
"cardNumber": "4111111111111111",
"cardholderName": "Ada Lovelace",
"expiryMonth": "12",
"expiryYear": "2030",
"cvv": "123"
}
}
}'
```
Alguns pontos sobre esta requisição:
* **Cartões de teste** — `4111111111111111` sempre resulta em uma aprovação de sandbox. Use `4000000000000002` para simular uma recusa.
* **`amount.value`** sempre em unidades menores. `1999` significa \$19.99 em USD. Para moedas sem casas decimais como JPY ou CLP, `1999` significa ¥1999.
* **`amount.exponent`** é o número de casas decimais: `2` para USD/EUR, `0` para JPY/CLP.
Uma resposta bem-sucedida se parece com isto:
```json theme={"dark"}
{
"id": "9f8b2c1e-4d5a-6b7c-8d9e-0f1a2b3c4d5e",
"status": "captured",
"paymentCode": "PAY-abc123xyz",
"orderCode": "QUICKSTART-001",
"amount": { "currency": "USD", "value": 1999, "exponent": 2 }
}
```
Guarde o `id` — é o identificador deste pagamento, usado como o segmento de caminho `{id}` para capturar, reembolsar e cancelar. (`paymentCode` é uma referência para consultas e conciliação.)
Recupere qualquer pagamento passando seu `id` (ou seu `paymentCode`) para `GET /payment/inquiry/{id}`.
```bash theme={"dark"}
curl https://api-sandbox.therius.io/v1/payment/inquiry/9f8b2c1e-4d5a-6b7c-8d9e-0f1a2b3c4d5e \
-H "Authorization: Bearer prv_sandbox_your_key_here"
```
A resposta retorna a mesma estrutura `PaymentResponse` da compra original, incluindo o `status` atual e todos os detalhes do valor.
Para salvar um cartão de um cliente recorrente, adicione `"tokenize": true` e um `shopper.id` à sua requisição de compra. O Therius armazena o cartão no cofre e retorna um token na resposta.
```json theme={"dark"}
{
"merchantCode": "MERCHANT_001",
"orderCode": "QUICKSTART-002",
"amount": { "currency": "USD", "value": 1999, "exponent": 2 },
"shopper": { "id": "shopper-42" },
"card": {
"cardData": {
"cardNumber": "4111111111111111",
"cardholderName": "Ada Lovelace",
"expiryMonth": "12",
"expiryYear": "2030",
"cvv": "123",
"tokenize": true
}
}
}
```
A resposta inclui um campo `token` (por exemplo, `vt_abc123`). Em requisições futuras para este cliente, passe `card.tokenData.token` no lugar de `card.cardData` — sem precisar do número do cartão.
```json theme={"dark"}
{
"card": {
"tokenData": {
"token": "vt_abc123"
}
}
}
```
Quando estiver pronto para aceitar pagamentos reais, faça duas mudanças:
1. Substitua `prv_sandbox_...` pela sua chave de produção `prv_production_...`.
2. Aponte suas requisições para `https://api.therius.io/v1` no lugar de `https://api-sandbox.therius.io/v1`.
Nenhuma outra mudança de código é necessária. O prefixo da chave seleciona o ambiente automaticamente.
Confirme que toda requisição que altera dados no seu código de produção envia um cabeçalho `Idempotency-Key` antes de entrar no ar.
## O que vem a seguir
Explore cada endpoint — compra, autorização, captura, reembolso, cancelamento, assinaturas e mais.
Incorpore um formulário de cartão seguro para PCI no seu frontend sem que dados de cartão sem criptografia passem pelo seu servidor.
Conecte adquirentes, processadores e provedores de pagamento alternativos à sua conta do Therius.
Receba eventos de pagamento e assinatura no seu servidor, com verificação de assinatura.
Cada cartão de teste de sandbox, motivo de recusa e cenário de 3D Secure em uma única tabela.