Payment Instruments

A payment instrument is a saved payment method — typically a card — kept on file for a customer so you can charge it again without re-collecting card data. Instruments are the backbone of repeat purchases, one-click checkout, and merchant-initiated charges such as subscription renewals.

Tokeflow stores only a non-sensitive reference and metadata for each instrument (pi_…, brand, last 4, expiry). The card itself is encrypted at collection time and is never handled by your servers.

How instruments come to exist

You never create a payment instrument by sending raw card numbers to the API. Instead, a card is enrolled client-side through the Bridge SDK using a zero-dollar setup verification — a transaction with charge_type: "setup_verification". The provider verifies the card is valid (and, where applicable, runs 3DS) without capturing money. On success, Tokeflow persists a reusable payment instrument and returns its pi_… id.

:::tip Secure card collection Tokeflow's secure fields run inside isolated, cross-origin iframes. Card data is encrypted in the browser and never touches your servers, so a payment instrument is the only card reference your backend ever sees. :::

How instruments are used

Once an instrument exists, reference it by id wherever a saved card can be charged:

• Saved-card charges — pass payment_instrument_id to POST /api/v1/transactions to charge the stored card. No card data is re-collected.
• Subscriptions — set or change the card a subscription bills against via change-payment-instrument. Future renewals run as merchant-initiated charges against the new instrument.

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

The payment instrument object

Status values

Example object

{
  "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

All instrument endpoints are merchant-scoped and live under a merchant path.

• Merchant key — the merchant is inferred from the key; supply your merchant id in the path.
• Organization key — pass the target merchant id in the path; the org key must have access to that merchant.

Required scopes: instruments:read for reads, instruments:write for mutations.

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

List a merchant's payment instruments. Supports pagination and filtering.

Auth: Organization key (scoped to the merchant) or Merchant key.

Query parameters

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"

Response 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}

Update an instrument's status. The status is the only mutable field.

Auth: Organization key (scoped to the merchant) or Merchant key.

Body

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" }'

Response 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}

Revoke an instrument. After revocation it can no longer be charged. Active subscriptions billing against it must be moved to another instrument first.

Auth: Organization key (scoped to the merchant) or Merchant key.

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

Response 204 No Content

HTTP/1.1 204 No Content

Errors

Failures use the standard error envelope.

{
  "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"
  }
}

Related

• Bridge SDK overview — collect and enroll cards client-side.
• Transactions — charge a saved instrument.
• Subscriptions — bill recurring charges against an instrument.
• Customers — the owner of each instrument.
• Authentication — keys, scopes, and merchant resolution.