Instrumentos de Pagamento

Um instrumento de pagamento é um método de pagamento salvo — normalmente um cartão — mantido em arquivo para um cliente, para que você possa cobrá-lo novamente sem recoletar os dados do cartão. Os instrumentos são a espinha dorsal de compras repetidas, upsells em um clique e cobranças iniciadas pelo merchant, como renovações de assinatura.

A Tokeflow armazena apenas uma referência não sensível e metadados para cada instrumento (pi_…, bandeira, últimos 4 dígitos, validade). O próprio cartão é criptografado no momento da coleta e nunca é manipulado pelos seus servidores.

Como os instrumentos são criados

Você nunca cria um instrumento de pagamento enviando números de cartão brutos para a API. O cartão é sempre coletado pelo Bridge SDK no navegador, e o ciphertext que ele retorna precisa ter sido emitido para cadastro — purpose: 'instrument_enrollment' (standalone) ou saveCard: true (dentro de uma sessão de checkout). Veja Tokenização → Opções. A partir daí, um instrumento é criado de uma de três formas:

O endpoint POST /merchants/:merchant_id/payment-instruments abaixo armazena um ciphertext de cadastro diretamente, sem verificação nem cobrança. Um instrumento criado assim existe, mas não guarda credencial de provedor até que uma cobrança com o portador presente ou uma verificação de cartão bem-sucedida passe por ele — então ele ainda não pode ser cobrado com credential_on_file.

:::tip Coleta segura de cartão Os campos seguros da Tokeflow são executados dentro de iframes isolados e de origem cruzada. Os dados do cartão são criptografados no navegador e nunca chegam aos seus servidores, portanto um instrumento de pagamento é a única referência de cartão que seu backend chega a ver. :::

Como os instrumentos são usados

Depois que um instrumento existe, referencie-o pelo id em qualquer lugar em que um cartão salvo possa ser cobrado:

• Cobranças em um clique — passe payment_instrument_id com credential_on_file: true para POST /api/v1/transactions. A cobrança usa a credencial do provedor guardada no cadastro — sem dados de cartão, sem CVV. Veja Cobranças com credencial armazenada.
• Cartão salvo com CVV redigitado — passe payment_instrument_id junto com um card_ciphertext_id novo do mesmo cartão, quando quiser uma cobrança com o portador presente (3DS possível).
• Assinaturas — defina ou altere o cartão contra o qual uma assinatura é cobrada por meio de change-payment-instrument. As próximas renovações são executadas como cobranças iniciadas pelo merchant contra o novo instrumento.

{
  "payment_method": "credit_card",
  "charge_type": "payment",
  "country": "BR",
  "customer_id": "cust_john_01",
  "payment_instrument_id": "pi_a1b2c3",
  "credential_on_file": true,
  "amount": 15000,
  "currency": "BRL"
}

O objeto do instrumento de pagamento

Valores de status

Objeto de exemplo

{
  "id": "pi_a1b2c3",
  "merchant_id": "mrc_123",
  "customer_id": "cust_john_01",
  "instrument_type": "card",
  "card_brand": "visa",
  "card_type": "credit",
  "last4": "4242",
  "bin": "424242",
  "issuer_country": "BR",
  "exp_month": 12,
  "exp_year": 2028,
  "status": "active",
  "created_at": "2026-01-15T12:30:00.000Z"
}

Endpoints

Todos os endpoints de instrumentos têm escopo de merchant e ficam sob um caminho de merchant.

• Chave Merchant — o merchant é inferido a partir da chave; informe o id do seu merchant no caminho.
• Chave Organization — passe o id do merchant de destino no caminho; a chave da org precisa ter acesso a esse merchant.

Escopos necessários: instruments:read para leituras, instruments:write para mutações.

POST/api/v1/merchants/:merchant_id/payment-instruments

Armazena um instrumento tokenizado associado a um cliente. O cadastro é deduplicado: reenviar um token que já resolve para um instrumento armazenado retorna o instrumento existente com deduplicated: true e um 200, em vez de criar um duplicado.

Parâmetros de caminho

Campos da requisição

Exemplo de requisição

curl -X POST https://api.tokeflow.com/api/v1/merchants/mrc_8a3f12d9/payment-instruments \
  -H "Authorization: Bearer sk_live_mer_…" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_2f9a71d4",
    "card_ciphertext_id": "tok_8f3c2a1b9d4e",
    "metadata": {}
  }'

Exemplo de resposta — 200

{
  "id": "pi_123",
  "merchant_id": "mrc_123",
  "customer_id": "cust_john_01",
  "card_brand": "visa",
  "card_type": "credit",
  "instrument_type": "card",
  "last4": "4242",
  "bin": "424242",
  "issuer_country": "BR",
  "exp_month": 12,
  "exp_year": 2028,
  "status": "active",
  "deduplicated": false,
  "created_at": "2025-11-20T10:00:00Z"
}

GET/api/v1/merchants/{merchant_id}/payment-instruments

Lista os instrumentos de pagamento de um merchant. Suporta paginação e filtragem.

Autenticação: chave Organization (com escopo no merchant) ou chave Merchant.

Parâmetros de consulta

curl "https://api.tokeflow.com/api/v1/merchants/mrc_123/payment-instruments?customer_id=cust_john_01&status=active&limit=20" \
  -H "Authorization: Bearer sk_live_mer_xxx"

Resposta 200 OK

{
  "success": true,
  "data": [
    {
      "id": "pi_a1b2c3",
      "merchant_id": "mrc_123",
      "customer_id": "cust_john_01",
      "instrument_type": "card",
      "card_brand": "visa",
      "card_type": "credit",
      "last4": "4242",
      "bin": "424242",
      "issuer_country": "BR",
      "exp_month": 12,
      "exp_year": 2028,
      "status": "active",
      "created_at": "2026-01-15T12:30:00.000Z"
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 1,
      "total_pages": 1,
      "has_next": false,
      "has_prev": false
    }
  },
  "request_id": "req_8f3c2a",
  "timestamp": "2026-01-15T12:30:00.000Z"
}

PATCH/api/v1/merchants/{merchant_id}/payment-instruments/{payment_instrument_id}

Atualiza o status de um instrumento. O status é o único campo mutável.

Autenticação: chave Organization (com escopo no merchant) ou chave Merchant.

Corpo

curl -X PATCH \
  "https://api.tokeflow.com/api/v1/merchants/mrc_123/payment-instruments/pi_a1b2c3" \
  -H "Authorization: Bearer sk_live_mer_xxx" \
  -H "Content-Type: application/json" \
  -d '{ "status": "revoked" }'

Resposta 200 OK

{
  "success": true,
  "data": {
    "id": "pi_a1b2c3",
    "merchant_id": "mrc_123",
    "customer_id": "cust_john_01",
    "instrument_type": "card",
    "card_brand": "visa",
    "card_type": "credit",
    "last4": "4242",
    "bin": "424242",
    "issuer_country": "BR",
    "exp_month": 12,
    "exp_year": 2028,
    "status": "revoked",
    "created_at": "2026-01-15T12:30:00.000Z"
  },
  "request_id": "req_91ad04",
  "timestamp": "2026-01-15T12:31:00.000Z"
}

DELETE/api/v1/merchants/{merchant_id}/payment-instruments/{payment_instrument_id}

Revoga um instrumento. Após a revogação, ele não pode mais ser cobrado. Assinaturas ativas que cobram contra ele precisam ser movidas para outro instrumento primeiro.

Autenticação: chave Organization (com escopo no merchant) ou chave Merchant.

curl -X DELETE \
  "https://api.tokeflow.com/api/v1/merchants/mrc_123/payment-instruments/pi_a1b2c3" \
  -H "Authorization: Bearer sk_live_mer_xxx"

Resposta 204 No Content

HTTP/1.1 204 No Content

Erros

As falhas usam o envelope de erro padrão.

{
  "error": {
    "type": "not_found_error",
    "code": "PAYMENT_INSTRUMENT_NOT_FOUND",
    "message": "Payment instrument pi_a1b2c3 was not found for this merchant.",
    "details": {},
    "request_id": "req_8f3c2a",
    "timestamp": "2026-01-15T12:30:00.000Z"
  }
}

Relacionados

• Upsells e downsells em um clique — salve um cartão ao cobrar e depois cobre-o com um clique.
• Visão geral do Bridge SDK — colete e cadastre cartões no lado do cliente.
• Transações — cobre um instrumento salvo.
• Assinaturas — cobre encargos recorrentes contra um instrumento.
• Clientes — o proprietário de cada instrumento.
• Autenticação — chaves, escopos e resolução de merchant.