Stored Credentials

Card on File (CoF) allows merchants to use a customer’s stored card credentials for future payments.
By identifying each transaction according to card-network rules, CoF improves authorization rates, ensures compliance, and enables subscription cycles, installments, and merchant-initiated charges.

ℹ️

Card on File availability varies by country and acquirer.
Please check with your Bamboo account manager before enabling CoF.

How Card on File works

Bamboo uses four parameters to classify and process Card on File transactions.
Together, they define who initiated the payment, whether the credential is being stored or reused, the business purpose, and the lifecycle reference required by card networks.

These four parameters are:

• Transaction Type - Who initiated the transaction (CIT or MIT)
• Usage - Whether the credential is being stored (FIRST) or reused (STORED)
• Reason - Why the credential is being stored or reused
• NetworkTransactionId - Identifier linking the transaction to the stored-credential agreement

Transaction Type

Identifies who initiates the transaction at the time of authorization.
This field is required for all Card on File operations.

Usage

Indicates whether the credential is being stored for the first time or reused in a later transaction.
This parameter defines the position of the payment within the stored-credential lifecycle.

Reason

The Reason field describes the business purpose behind storing or using the credential.
This ensures that the stored-credential lifecycle is correctly classified by card networks.

💡

The Reason must remain consistent throughout the entire lifecycle.
For example, a SUBSCRIPTION-FIRST must continue as SUBSCRIPTION-STORED in both CIT and MIT transactions.

NetworkTransactionId

The NetworkTransactionId is a unique identifier returned by the acquirer or card network in the FIRST transaction. It establishes the stored-credential agreement and must be:

• Persisted securely by the merchant
• Sent in every MIT transaction
• Used in any STORED transaction that continues the same lifecycle (e.g., subscription renewal)
• Passed exactly as received. No transformations or truncation

⚠️

Missing or incorrect NetworkTransactionId is one of the main causes of declines in MIT transactions.

CardOnFile Object

The CardOnFile object is used to classify any payment that stores or reuses a card credential.
All fields inside this object help card networks understand who initiated the transaction, why it exists, and how it connects to the stored-credential lifecycle.

Request Parameters

Note:
NetworkTransactionId is mandatory for MIT transactions and any STORED continuation of the same lifecycle.

Example — CIT + FIRST

{
  "TrxToken": "OT__MQewRP5OBUm5mk1SSoYupf9kLgEAAAAAAA",
  "UniqueID": "CIT-FIRST-001",
  "TargetCountryISO": "BR",
  "Currency": "BRL",
  "Capture": true,
  "Amount": 25000,
  "Order": "ORDER-001",
  "Installments": 1,
  "Description": "Subscription initial payment",
  "CardOnFile": {
    "TransactionType": "CIT",
    "Usage": "FIRST",
    "Reason": "SUBSCRIPTION"
  }
}

Example — CIT + STORED

{
  "TrxToken": "OT__MQewRP5OBUm5mk1SSoYupf9kLgEAAAAAAA",
  "UniqueID": "CIT-STORED-001",
  "TargetCountryISO": "BR",
  "Currency": "BRL",
  "Capture": true,
  "Amount": 25000,
  "Order": "ORDER-002",
  "Description": "Customer one-click payment",
  "CardOnFile": {
    "TransactionType": "CIT",
    "Usage": "STORED",
    "Reason": "SUBSCRIPTION",
    "NetworkTransactionId": "48b09c83-64da-4061-ba3d-7027d93b475e"
  }
}

Example — MIT + STORED

{
  "TrxToken": "OT__MQewRP5OBUm5mk1SSoYupf9kLgEAAAAAAA",
  "UniqueID": "MIT-STORED-001",
  "TargetCountryISO": "BR",
  "Currency": "BRL",
  "Capture": true,
  "Amount": 25000,
  "Order": "ORDER-003",
  "Description": "Subscription renewal",
  "CardOnFile": {
    "TransactionType": "MIT",
    "Usage": "STORED",
    "Reason": "SUBSCRIPTION",
    "NetworkTransactionId": "48b09c83-64da-4061-ba3d-7027d93b475e"
  }
}

Response Parameters

The response returned for a Card on File transaction follows the same structure as Create Purchase.

Only one additional field is included when the request uses Usage: FIRST or any other transaction that establishes a stored-credential agreement

Note:
All other fields in the response (e.g., TransactionId, Status, PaymentMethod) are identical to the standard Create Purchase response.

Response Example

{
  "TransactionId": "241583148629060736",
  "Result": "COMPLETED",
  "Status": "APPROVED",
  "ErrorCode": null,
  "ErrorDescription": null,
  "Created": "2025-10-28T15:25:11.090",
  "AuthorizationDate": "2025-10-28T15:25:11.760",
  "AuthorizationCode": "603832",
  "Amount": 5000,
  "Currency": "UYU",
  "Installments": 1,
  "TaxableAmount": null,
  "Tip": 0,
  "Url": "https://api.dev.bamboopayment.com/v3/api/transaction/241583148629060736",
  "MetadataOut": {
    "AuthorizationCode": "603832",
    "OperationId": "498631",
    "TransactionNumber": "498631"
  },
  "Action": null,
  "PaymentMethod": {
    "Brand": "MasterCard",
    "CardOwner": "Juan Perez",
    "Bin": "550272",
    "IssuerBank": "UNITED OVERSEAS BANK (MALAYSIA) BERHAD",
    "Type": "CreditCard",
    "Expiration": "203008",
    "Last4": "0000"
  },
  "CardOnFile": {
    "NetworkTransactionId": "48b09c83-64da-4061-ba3d-7027d93b475e"
  }
}

Next Steps