Primeiros passos

Este guia leva voce da chave de API a primeira cobranca aprovada sem precisar credenciar nenhum adquirente. O conector simulado (minstrel_sandbox) responde como um adquirente real, inclusive nas recusas.

1. Pegue sua chave de API

No painel, em Configuracoes - Chaves de API, crie uma chave de sandbox. O segredo aparece uma unica vez: guarde-o num gerenciador de segredos.

mk_sandbox_a1b2c3d4_seu-segredo-aqui

O formato tem tres partes com funcoes distintas:

Como o ambiente vem da chave, e impossivel cobrar em producao por engano usando uma credencial de teste.

2. Cadastre um cliente

curl -X POST http://localhost:3333/v1/customers \
  -H "Authorization: Bearer $MINSTREL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "cliente-1234",
    "name": "Maria Oliveira",
    "email": "maria.oliveira@exemplo.com.br",
    "documentType": "cpf",
    "document": "123.456.789-09"
  }'

O campo externalId e o seu identificador do cliente. Ele torna o cadastro idempotente: reenviar o mesmo cliente devolve o registro existente em vez de criar duplicata. Use sempre - vai te poupar numa importacao de base.

3. Crie um pagamento

curl -X POST http://localhost:3333/v1/payments \
  -H "Authorization: Bearer $MINSTREL_API_KEY" \
  -H "Idempotency-Key: idem_$(date +%s)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 14990,
    "currency": "BRL",
    "customerId": "cus_...",
    "card": { "token": "tok_sandbox_teste", "isNetworkToken": false },
    "captureMethod": "automatic",
    "softDescriptor": "MINHALOJA"
  }'

Dois detalhes importantes:

O valor e em centavos. 14990 e R$ 149,90. Nunca enviamos nem aceitamos valores com ponto decimal: ponto flutuante em dinheiro produz erro de um centavo, e um centavo errado em conciliacao e um incidente.

O header Idempotency-Key nao e opcional na pratica. Se a resposta se perder por timeout e o seu codigo repetir a chamada sem ele, o portador e cobrado duas vezes. Com ele, a repeticao devolve a resposta original.

4. Simule recusas

O conector simulado reage ao valor do pagamento, o que permite testar cada caminho sem configuracao:

Tambem da para pedir uma recusa especifica pelo metadata, em qualquer valor:

{
  "amount": 5000,
  "metadata": { "simulate_decline_code": "54" }
}

As outras chaves sao simulate_merchant_advice_code (ex.: "21"), simulate_timeout: true e simulate_requires_action: true.

Compare 10051 (reversivel) com 10041 (irreversivel): a primeira pode ser retentada no tempo certo; a segunda para na hora, sem nova tentativa. Essa diferenca e o nucleo do produto, e esta explicada em Retentativa e codigos de recusa.

5. Dados de cartao nao passam por aqui

Se voce enviar numero de cartao ou CVV, a API responde 422 antes de qualquer validacao, log ou gravacao:

{
  "error": {
    "type": "invalid_request_error",
    "code": "raw_card_data_rejected",
    "message": "Dados sensiveis de cartao nao sao aceitos. Tokenize o cartao primeiro e envie apenas o token em payment_method.",
    "param": "card.number",
    "meta": { "offendingPaths": ["card.number", "card.cvv"] }
  }
}

Observe que o erro lista apenas os caminhos dos campos, nunca os valores - caso contrario o proprio erro vazaria o dado para os seus logs.

A checagem tambem pega numero de cartao colado em campo de texto livre, como description ou metadata. E a forma mais comum de vazamento acidental.

Para receber o cartao na sua propria pagina sem que o numero passe pelos seus servidores nem pelo Minstrel, use o checkout transparente: o navegador envia o cartao direto ao adquirente e o Minstrel recebe so o token.

Proximos passos

• Checkout transparente - receba o cartao na sua pagina com o @minstrel/js
• Retentativa e codigos de recusa - como decidimos quando retentar
• Webhooks - receba eventos com assinatura verificada
• Referencia da API - todos os endpoints, campos e exemplos