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 upsells, 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. The card is always collected by the Bridge SDK in the browser, and the ciphertext it returns must be minted for enrollment — purpose: 'instrument_enrollment' (standalone) or saveCard: true (inside a checkout session). See Tokenization → Options. From there, an instrument is created in one of three ways:

The POST /merchants/:merchant_id/payment-instruments endpoint below stores an enrollment ciphertext directly, without a verification or a charge. An instrument created that way exists, but holds no provider credential until one successful cardholder-present charge or card verification runs through it — so it cannot be charged with credential_on_file yet.

:::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:

• One-click charges — pass payment_instrument_id with credential_on_file: true to POST /api/v1/transactions. The charge uses the provider credential kept at enrollment — no card data, no CVV. See Stored-credential charges.
• Saved card with a re-typed CVV — pass payment_instrument_id together with a fresh card_ciphertext_id for the same card, when you want a cardholder-present charge (3DS possible).
• 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",
  "credential_on_file": true,
  "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.

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

Stores a tokenized instrument against a customer. Enrollment is deduplicated: re-sending a token that already resolves to a stored instrument returns the existing one with deduplicated: true and a 200 instead of creating a duplicate.

Path parameters

Request fields

Example request

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

Example response — 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

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

• One-click upsells & downsells — save a card while charging, then charge it with one click.
• 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.