Skip to main content
Online Payments

Stored payments

Cardholder-initiated stored payments are transactions in which a cardholder, who has stored their credentials with a merchant, takes an action to initiate a purchase, but elects to use the card on file rather than entering a new card number.

The key distinction between recurring and cardholder-initiated stored payments is what triggers the transaction. If the cardholder actively does something to initiate the transaction, such as place an order or log into a portal to pay a bill, it is considered a cardholder-initiated stored payment. Conversely, a recurring payment occurs automatically without the cardholder taking any action to initiate the payment.

Note

For more information on how cardholder-initiated transactions (CIT) and merchant-initiated transactions (MIT) work, refer to Cardholder vs Merchant-initiated transactions.

How stored payments work

  1. Cardholder credentials are stored on the initial transaction by including the below two fields and values in the payment request:
    1. initiatorType set to CARDHOLDER 
    2. accountOnFile set to TO_BE_STORED
  2. Subsequent payments then need to include the below two fields to use the stored payment credentials:
    1. initiatorType set to CARDHOLDER 
    2. accountOnFile set to STORED

Initial stored payment request

The following example shows an initial stored payment request:

HTTP method: POST
Endpoint: /payments

Json
{
  "captureMethod": "NOW",
  "amount": 100,
  "currency": "USD",
  "merchantOrderNumber": "1778672674",
  "merchant": {
    "merchantSoftware": {
      "companyName": "Von and Sons",
      "productName": "Shoes",
      "version": "2.0"
    }
  },
  "paymentMethodType": {
    "card": {
      "accountNumberType": "PAN",
      "accountNumber": "4055018101463717",
      "expiry": {
        "month": 5,
        "year": 2027
      },
      "cvv": "411"
    }
  },
  "accountHolder": {
    "fullName": "Blanca Kovacek-Borer",
    "billingAddress": {
      "line1": "608 Liberty Street",
      "city": "Oraborough",
      "state": "BT",
      "postalCode": "33626"
    }
  },
  "initiatorType": "CARDHOLDER",
  "accountOnFile": "TO_BE_STORED"
}

Response:

Json
{
  "transactionId": "c49dd94e-a9fc-45ec-9f27-5156c6a7a28b",
  "requestId": "4a34e9f7-c1b9-49fe-8a0b-6568b035cc54",
  "transactionState": "CLOSED",
  "responseStatus": "SUCCESS",
  "responseCode": "APPROVED",
  "responseMessage": "Transaction approved by Issuer",
  "paymentMethodType": {
    "card": {
      "accountNumberType": "PAN",
      "cardType": "VI",
      "cardTypeName": "VISA",
      "maskedAccountNumber": "4055018XXXXXX717",
      "networkResponse": {
        "addressVerificationResult": "ADDRESS_POSTALCODE_MATCH",
        "addressVerificationResultCode": "I3",
        "cardVerificationResult": "NO_MATCH",
        "cardVerificationResultCode": "N",
        "networkTransactionId": "926336337220166",
        "paymentAccountReference": "urzLXh3O82PHliRFUCF4BVP1CbQPl",
        "tokenAssuranceScore": "13",
        "tokenStatus": "R",
        "networkResponseCode": "00",
        "addressVerificationResultDescription": "ZIP_MATCH_PLUS4_NOMATCH_LOCALE_MATCH"
      },
      "authentication": {
        "authenticationValueResponse": {
          "code": "2",
          "message": "CAVV passed verification-authentication"
        }
      },
      "paymentTokens": [
        {
          "tokenProvider": "SAFETECH",
          "tokenNumber": "4055018772008717",
          "responseStatus": "SUCCESS"
        }
      ]
    }
  },
  "captureMethod": "NOW",
  "captureTime": "2026-05-22T18:09:13.051Z",
  "initiatorType": "CARDHOLDER",
  "accountOnFile": "TO_BE_STORED",
  "isVoid": false,
  "transactionDate": "2026-05-22T18:09:13.051Z",
  "approvalCode": "tst216",
  "hostMessage": "Approved",
  "isAmountFinal": true,
  "amount": 100,
  "currency": "USD",
  "remainingRefundableAmount": 100,
  "remainingAuthAmount": 0,
  "merchantOrderNumber": "1778672674",
  "hostReferenceId": "UchHMA3mD8H7cHd5XVEjVD",
  "merchant": {
    "merchantId": "998038398379",
    "merchantSoftware": {
      "companyName": "Von and Sons",
      "productName": "Shoes",
      "version": "2.0"
    },
    "merchantCategoryCode": "5969"
  },
  "paymentRequest": {
    "paymentRequestId": "c49dd94e-a9fc-45ec-9f27-5156c6a7a28b",
    "paymentRequestStatus": "CLOSED",
    "authorizations": [
      {
        "authorizationId": "c49dd94e-a9fc-45ec-9f27-5156c6a7a28b",
        "amount": 100,
        "transactionStatusCode": "CAPTURED",
        "authorizationType": "INITIAL",
        "transactionTimestamp": "2026-05-22T18:09:13.051Z",
        "expirationTimestamp": "2026-05-29T18:09:13.051Z"
      }
    ],
    "captures": [
      {
        "captureId": "c49dd94e-a9fc-45ec-9f27-5156c6a7a28b",
        "amount": 100,
        "transactionStatusCode": "CLOSED",
        "captureRemainingRefundableAmount": 100,
        "referencedAuthorizationIdentifier": "c49dd94e-a9fc-45ec-9f27-5156c6a7a28b"
      }
    ]
  }
}

Subsequent stored payments requests

The following example shows a subsequent stored payment request:

HTTP method: POST
Endpoint: /payments

Json
{
  "captureMethod": "NOW",
  "amount": 100,
  "currency": "USD",
  "merchantOrderNumber": "1778681532",
  "merchant": {
    "merchantSoftware": {
      "companyName": "Von and Sons",
      "productName": "Shoes",
      "version": "2.0"
    }
  },
  "paymentMethodType": {
    "card": {
      "accountNumberType": "PAN",
      "accountNumber": "4055018101463717",
      "expiry": {
        "month": 5,
        "year": 2027
      },
      "cvv": "411"
    }
  },
  "accountHolder": {
    "fullName": "Blanca Kovacek-Borer",
    "billingAddress": {
      "line1": "608 Liberty Street",
      "city": "Oraborough",
      "state": "BT",
      "postalCode": "33626"
    }
  },
  "initiatorType": "CARDHOLDER",
  "accountOnFile": "STORED"
}

Response:

Json
{
  "transactionId": "b9f0a271-4e87-4b08-9d36-57aff33a4138",
  "requestId": "6388cf38-4737-425b-a2c1-f70e2bfe7fb0",
  "transactionState": "CLOSED",
  "responseStatus": "SUCCESS",
  "responseCode": "APPROVED",
  "responseMessage": "Transaction approved by Issuer",
  "paymentMethodType": {
    "card": {
      "accountNumberType": "PAN",
      "cardType": "VI",
      "cardTypeName": "VISA",
      "maskedAccountNumber": "4055018XXXXXX717",
      "networkResponse": {
        "addressVerificationResult": "ADDRESS_POSTALCODE_MATCH",
        "addressVerificationResultCode": "I3",
        "cardVerificationResult": "NO_MATCH",
        "cardVerificationResultCode": "N",
        "networkTransactionId": "016133692167678",
        "networkResponseCode": "00",
        "addressVerificationResultDescription": "ZIP_MATCH_PLUS4_NOMATCH_LOCALE_MATCH"
      },
      "authentication": {
        "authenticationValueResponse": {
          "code": "2",
          "message": "CAVV passed verification-authentication"
        }
      },
      "paymentTokens": [
        {
          "tokenProvider": "SAFETECH",
          "tokenNumber": "4055018667082717",
          "responseStatus": "SUCCESS"
        }
      ]
    }
  },
  "captureMethod": "NOW",
  "captureTime": "2026-05-22T18:15:04.231Z",
  "initiatorType": "CARDHOLDER",
  "accountOnFile": "STORED",
  "isVoid": false,
  "transactionDate": "2026-05-22T18:15:04.231Z",
  "approvalCode": "tst612",
  "hostMessage": "Approved",
  "isAmountFinal": true,
  "amount": 100,
  "currency": "USD",
  "remainingRefundableAmount": 100,
  "remainingAuthAmount": 0,
  "merchantOrderNumber": "1778681532",
  "hostReferenceId": "E4edRQRre5y41GZ5zGG0Px",
  "merchant": {
    "merchantId": "998038398379",
    "merchantSoftware": {
      "companyName": "Von and Sons",
      "productName": "Shoes",
      "version": "2.0"
    },
    "merchantCategoryCode": "5969"
  },
  "paymentRequest": {
    "paymentRequestId": "b9f0a271-4e87-4b08-9d36-57aff33a4138",
    "paymentRequestStatus": "CLOSED",
    "authorizations": [
      {
        "authorizationId": "b9f0a271-4e87-4b08-9d36-57aff33a4138",
        "amount": 100,
        "transactionStatusCode": "CAPTURED",
        "authorizationType": "INITIAL",
        "transactionTimestamp": "2026-05-22T18:15:04.231Z",
        "expirationTimestamp": "2026-05-29T18:15:04.231Z"
      }
    ],
    "captures": [
      {
        "captureId": "b9f0a271-4e87-4b08-9d36-57aff33a4138",
        "amount": 100,
        "transactionStatusCode": "CLOSED",
        "captureRemainingRefundableAmount": 100,
        "referencedAuthorizationIdentifier": "b9f0a271-4e87-4b08-9d36-57aff33a4138"
      }
    ]
  }
}

Authorize and capture a payment
Cardholder vs Merchant-initiated transactions
Recurring payments

Is this page helpful?