Cartão Cobrança no cartão

Como criar uma cobrança no cartão de crédito.

1. Tokenize o cartão

A tokenização acontece no checkout do provedor (ex. Pagar.me). O resultado é um payment_token (Pagar.me) que você usa na cobrança.

2. Autentique com 3DS (opcional)

São três passos. Pule esta seção se a cobrança não usar 3DS: sem o bloco threeDS, o pedido sai sem autenticação, como sempre.

2.1 Gere o token efêmero (MPI Pagar.me/Stone)

Chame POST /v1/3ds/pagarme/token do seu backend com a API key do tenant. A PayGrid resolve a conta indicada em providerAccountLogicalId (o logicalId da sua conta Pagar.me em GET /v1/providers/accounts) e chama o serviço de 3DS da Pagar.me/Stone. A secret key da conta nunca sai do servidor da PayGrid; você recebe apenas o token efêmero.

curl -X POST https://api.paygrid.tech/v1/3ds/pagarme/token \
  -H "X-Api-Key: sk_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "providerAccountLogicalId": "merchant-primary",
    "amount": 59900,
    "currency": "BRL"
  }'

{
  "token": "tds_abc123...",
  "expiresAt": "2026-10-22T13:30:00Z",
  "environment": "production"
}

Esse token é de uso único e diferente do token do cartão (tok_...): ele autentica a transação 3DS, não o cartão. Entregue-o ao SDK no cliente para rodar o desafio.

2.2 Envie o resultado na cobrança

Terminado o desafio, o SDK devolve o resultado da autenticação. Envie-o no campo threeDS ao criar a cobrança — a PayGrid valida apenas a forma do objeto (campos obrigatórios de cada MPI), grava o resultado para auditoria e uso único e repassa ao gateway. Quem decide se o portador autenticou é o emissor, não a PayGrid.

"threeDS": {
  "mpi": "pagarme",
  "transactionId": "tds_abc123..."
}

Para um autenticador externo (MPI third_party), o desafio é do seu provedor e a PayGrid só recebe os artefatos:

"threeDS": {
  "mpi": "third_party",
  "eci": "05",
  "cavv": "AAAB...",
  "dsTransactionId": "7f3c...",
  "version": "2.2.0"
}

O 3DS não muda a resposta da criação da cobrança: o desfecho chega como approved ou declined pelo webhook ou pela consulta. Se o gateway devolver o pagamento como action_required, o evento payment.action_required sinaliza que o portador ainda precisa agir.

Consultar a autenticação depois

GET /v1/transactions/{id} e GET /v1/payments/{id} devolvem o bloco threeDS com o resultado da autenticação daquela cobrança. O cavv nunca volta.

"threeDS": {
  "mpi": "pagarme",
  "authenticationId": "tds_server_trans_id_do_sdk",
  "eci": "05",
  "version": "2.2.0",
  "authenticatedAt": "2026-10-26T15:04:05Z"
}

authenticationId é o transactionId para pagarme e o dsTransactionId para third_party. O eci depende da bandeira: em Visa, Elo e Amex, 05 = autenticada, 06 = tentativa e 07 = sem autenticação; em Mastercard, 02, 01 e 00, na mesma ordem. Sem 3DS, o bloco não aparece — e também não aparece nas cobranças criadas antes de 26/10/2026.

3. Crie a cobrança

curl -X POST https://api.paygrid.tech/v1/transactions \
  -H "X-Api-Key: sk_sua_chave" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: pedido-5001" \
  -d '{
    "workflowId": "22222222-2222-2222-2222-222222222222",
    "paymentMethod": "card",
    "amount": 59900,
    "currency": "BRL",
    "token": "tok_abc123...",
    "installments": 3,
    "reference": "pedido-5001",
    "customer": {
      "name": "João da Silva",
      "email": "joao@exemplo.com",
      "document": "12345678900",
      "phone": "+5511999999999",
      "address": {
        "line1": "Rua Exemplo, 100",
        "zipCode": "01001000",
        "city": "São Paulo",
        "state": "SP",
        "country": "BR"
      }
    }
  }'

4. Resultado

A resposta (202) traz transactionId, trackingId e status: "accepted": a cobrança foi enfileirada. O desfecho do cartão sai em seguida — approved ou declined — sem esperar o pagador, diferente do Pix, que fica pending até ser pago.

5. Reconsulte / Webhook

Consulte GET /v1/transactions/{transactionId} ou configure webhooks para ser notificado.

6. Detalhe do pagamento

GET /v1/payments/{paymentId} traz o que o provedor informou sobre o cartão cobrado:

{
  "paymentId": "5183e61a-...",
  "status": "approved",
  "cardBrand": "visa",
  "cardLastFour": "1234",
  "providerDetails": {
    "feeAmount": 1797,
    "hasFee": true,
    "feeState": "disponivel"
  }
}

7. Taxa do provedor

O Paygrid busca a taxa automaticamente quando a cobrança é aprovada ou estornada. O provedor nem sempre a publica na hora, então feeState diz em que pé ela está: