Confirmar intenção (cobrar)

Transforma a intenção em transação.

Cartão: corpo { "token": "vtk_..." } (token devolvido pelo cofre). A resposta é 201 com a transação PAID (aprovado) ou FAILED (recusado pela adquirente ou pelo banco emissor). Recusa não é erro HTTP: a intenção fica CONFIRMED e a transação registra a recusa. Pra tentar de novo, crie outra intenção (o token é de uso único).
Pix / boleto: sem corpo. A transação nasce PENDING e a resposta traz paymentDetails com QR Code ou linha digitável.

Reenviar o confirm com a mesma Idempotency-Key devolve a mesma transação, sem cobrar duas vezes. Reenviar com outra chave numa intenção já confirmada → 409 INTENT_ALREADY_PROCESSED. Se a adquirente não responder → 502 PROVIDER_ERROR e a intenção vai pra FAILED.

Authorization

AuthorizationBearer <token>

Chave de API da sua empresa. Por enquanto a SwitchPay gera a chave e entrega à sua empresa; em breve será possível criar pelo painel.

In: header

Path Parameters

idstring

Id com prefixo, exatamente como a API devolveu.

Lengthlength <= 64

Header Parameters

Idempotency-Keystring

Chave de idempotência. Obrigatória nesta rota (cria ou movimenta dinheiro). Use o id do pedido do seu lado.

Lengthlength <= 255

Request Body

token?string

Token do cofre (vtk_ + texto opaco, ~1 400 caracteres). Obrigatório quando paymentMethod é CREDIT_CARD; ignorado nos demais.

Lengthlength <= 4100

Response Body

curl -X POST "https://api.sandbox.switchpay.app.br/v2/payment-intents/string/confirm" \
  -H "Idempotency-Key: string" \
  -H "Content-Type: application/json" \
  -d '{
    "token": "vtk_eyJhbGciOiJFQ0RILUVTIiwiZW5jIjoiQTI1NkdDTSIsImtpZCI6ImZpbi1lbmMtMjAyNi0xMCIsImN0eSI6IkpXVCJ9..0Ozx…(texto opaco, ~1 400 caracteres)"
  }'

curl -X POST "https://api.sandbox.switchpay.app.br/v2/payment-intents/string/confirm" \  -H "Idempotency-Key: string" \  -H "Content-Type: application/json" \  -d '{    "token": "vtk_eyJhbGciOiJFQ0RILUVTIiwiZW5jIjoiQTI1NkdDTSIsImtpZCI6ImZpbi1lbmMtMjAyNi0xMCIsImN0eSI6IkpXVCJ9..0Ozx…(texto opaco, ~1 400 caracteres)"  }'

{
  "id": "trx_6f1a2b3c-4d5e-4f60-8a7b-9c0d1e2f3a4b",
  "status": "PENDING",
  "paymentMethod": "PIX",
  "installments": 1,
  "amountCents": 15000,
  "feeCents": 149,
  "netAmountCents": 14851,
  "currency": "BRL",
  "sellerId": "cmp_8f2a1c3d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "sellerName": "Loja Exemplo",
  "paymentIntentId": "pi_7b2f9c1e-4d3a-4c6b-9e1f-2a3b4c5d6e7f",
  "referenceId": "pedido-8842",
  "description": "Pedido 8842 — Loja Exemplo",
  "buyer": {
    "name": "Maria Souza",
    "document": "12345678909",
    "email": "maria@exemplo.com",
    "phone": {
      "country": "55",
      "area": "11",
      "number": "987654321"
    }
  },
  "paymentDetails": {
    "pix": {
      "qrCode": "00020126580014br.gov.bcb.pix0136a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d5204000053039865406150.005802BR5913LOJA EXEMPLO6009SAO PAULO62070503***6304ABCD",
      "qrCodeImageBase64": "iVBORw0KGgoAAAANSUhEUgAA…",
      "expiresAt": "2026-10-06T17:00:00.000Z"
    }
  },
  "split": {
    "receivables": [
      {
        "recipientDocument": "11222333000181",
        "role": "CUSTOM_SPLIT_RECIPIENT",
        "installment": 1,
        "grossAmountCents": 1500,
        "feeCents": 0,
        "amountCents": 1500,
        "expectedOn": "2026-10-07",
        "status": "PENDING"
      },
      {
        "recipientDocument": "99888777000166",
        "role": "SELLER",
        "installment": 1,
        "grossAmountCents": 13500,
        "feeCents": 149,
        "amountCents": 13351,
        "expectedOn": "2026-10-07",
        "status": "PENDING"
      }
    ]
  },
  "metadata": {
    "orderId": "8842",
    "channel": "app"
  },
  "createdAt": "2026-10-06T14:01:10.000Z",
  "updatedAt": "2026-10-06T14:01:10.000Z"
}

{
  "code": "VALIDATION_ERROR",
  "message": "Há campos inválidos na requisição.",
  "details": [
    {
      "field": "token",
      "message": "deve começar com vtk_ e ter no máximo 4100 caracteres"
    }
  ]
}

{
  "code": "UNAUTHORIZED",
  "message": "Chave de API ausente, inválida ou de outro ambiente."
}

{
  "code": "FORBIDDEN",
  "message": "Sua chave não tem permissão para esta operação."
}

{
  "code": "NOT_FOUND",
  "message": "Recurso não encontrado."
}

{
  "code": "INTENT_ALREADY_PROCESSED",
  "message": "Esta intenção já foi confirmada, cancelada ou expirou."
}

{
  "code": "INTENT_EXPIRED",
  "message": "A intenção expirou. Crie outra."
}

{
  "code": "TOKEN_REQUIRED",
  "message": "Pagamento com cartão exige o token do cofre.",
  "details": [
    {
      "field": "token",
      "message": "obrigatório"
    }
  ]
}

{
  "code": "RATE_LIMITED",
  "message": "Limite de chamadas atingido. Aguarde e tente de novo."
}

{
  "code": "PROVIDER_ERROR",
  "message": "A adquirente não respondeu. Tente novamente mais tarde."
}

{
  "code": "SERVICE_UNAVAILABLE",
  "message": "Serviço de autorização indisponível. Tente novamente em instantes."
}

Confirmar intenção (cobrar)

Authorization

Path Parameters

Header Parameters

Request Body

Response Body

201

400

401

403

404

409

410

422

429

502

503

Pix aguardando pagamento

Boleto emitido

Cartão aprovado em 3x

Cartão recusado (não é erro HTTP)

Token com formato errado

Cabeçalho Idempotency-Key faltando

Example semChave

Example semPermissao

Example naoEncontrado

Example alreadyProcessed

Example idempotencyReused

Example idempotencyInProgress

Example expired

Example tokenRequired

Example tokenInvalid

Example limite

Example adquirente

Example indisponivel