Storing a Card on File

Overview

A STORE (card verification/COF) transaction allows a developer to send a request to the PayConex™ Gateway that stores the encrypted credit card or ACH account information for later use, without charging the customer. Similar to Customer and Merchant-Initiated Transactions, the store transaction communicates with the card issuers and the Processor that the customer has authorized a merchant to perform reissuing/recurring payments. Store transactions are considered to be CITs.

After obtaining the PayConex™ token from the Checkout Component, we can store the transaction and basically vault the token for reuse. This token can now be used for reissuing/recurring payments.

🚧
Note
To process a store transaction, the savePaymentOption property in the Checkout Component must be set to true. This can be accomplished by setting the iframe configuration or instance to either define "savePaymentOption": "required" or "savePaymentOption": "optional". If it is not enabled, the request will be rejected because a prior agreement between the customer and the merchant is required.
For example,
{
 "message": "Cannot store token when savePaymentOption is false",
 "errorCode": 40001,
 "errorType": "invalid_request",
 "traceId": "f260b180-75a5-4928-a30a-95df047e4dc4"
}

Sample Request

For example, we can vault the token with the following request in order to process a sale transaction without the token expiring.

POST /api/v4/accounts/{accountId}/payments/store

{
  "bfTokenReference": "PAYCONEX_TOKEN",
  "posProfile": "ECOMMERCE"
}

*Required Scopes: pcx:payments:*, pcx:payments:card_not_present:*, pcx:payments:card_not_present:store

Upon a successful request, the status of this transaction becomes "SAVED" indicating that the credit card PayConex™ token was stored.

🚧
Note
A PayConex™ token can be stored only once. Otherwise, we receive the following:
{
    "message": "Payment already stored",
    "errorCode": 40001,
    "errorType": "invalid_request",
    "traceId": "86d26a84-e4de-460c-a725-8a43ccb00675"
  }

Example Response

The store transaction returns both bfTokenReference and shieldConexToken so the merchant can decide which one to use for a subsequent MIT transaction. For the comprehensive section on this, see Customer and Merchant Initiated Transactions.

{
  "transactionId": "000000046266",
  "status": "SAVED",
  "timestamp": "2025-04-02T20:34:58.000000Z",
  "customer": {
    "name": "Alice",
    "billingAddress": {
      "address1": "address1",
      "address2": "address2",
      "city": "My City",
      "state": "MO",
      "zip": "90210",
      "country": "USA",
      "company": "Acme Inc."
    }
  },
  "shippingAddress": {
    "address1": "address1",
    "address2": "address2",
    "city": "My City",
    "state": "MO",
    "zip": "90210",
    "country": "USA",
    "company": "Acme Inc.",
    "recipient": "Alice Smith"
  },
  "auth": {
    "code": "OK9340",
    "processorMessage": "APPROVED",
    "message": "APPROVED",
    "networkName": "VISA",
    "avsResponseCode": "Y"
  },
  "card": {
    "name": "Alice",
    "last4": "1111",
    "expiry": "1225",
    "brand": "VISA"
  },
  "transactionType": "STORE",
  "entryMode": "KEYED",
  "bfTokenReference": "bft_abfddede2a0b43b789ae570955fd5e9a",
  "shieldConexToken": {
    "bfid": "djI6MTI...",
    "cardNumber": "5850459886792406",
    "cardExpiration": "9527"
  },
  "binData": {
    "program": "UNKNOWN"
  },
  "trace": {
    "history": [
      {
        "action": "transaction",
        "requestId": "1d050de5-3cd4-47e9-b024-5b849f8bdf93",
        "correlationId": "2d7773ff-35eb-46e3-aed6-e0dfb92db6c0",
        "timestamp": "2025-04-02T15:34:55-05:00"
      }
    ],
    "networkTransactionId": "015092827391937CN  "
  }
}

Optional Fields

📘
Note
You can overwrite some of the transaction metadata fields that are used in the recurring transaction while processing a store. These include description, customer, shippingAddress, trace. If needed, they can also be subsequently overwritten by processing Sale Transaction.

Parameter	Type	Description	Example
`transactionId`	`string`	Use a pre-fetched transaction identifier in case there is a communication error or similar during the ongoing transaction. This is a 12-digit numeric value padded with zeros. See Initializing a Transaction.	`"000000003807"`
`description`	`string`	Transaction description.	`"Food Purchase - #1"`
`customer`	`object`	Customer data including `name`, `email`, `phone` and `billingAddress`.	See Customer.
`posProfile`	`string`	The type of Point of Sale used for the transaction. See: Point of Sale Profiles.	`"ECOMMERCE"`
`shippingAddress`	`object`	Consists of a set of shipping fields such as `"address1`" and `"address2"`.	See Shipping Address.
`trace`	`object`	Trace data information of a transaction.	See Trace.
`bfTokenReference`	`string`	This field represents the PayConex™ Token. Securely tokenized `track2`, `track3` data, personal information, etc. For more, see PayConex™ Token.	`"bft_aab..."`
`shieldConexToken`	`object`	The auto-tokenized ShieldConex® token. To check out the use of this token, see PayConex™ Token vs ShieldConex® Token.	See ShieldConexToken.
`rules`	`object`	Transaction rules such as `allowPartial` and `allowDuplicate`. `allowPartial` enables partial authorizations on a per-transaction basis and `allowDuplicate` allows duplicate transactions by overriding the account settings. See Rules.	{ "allowPartial": true, "allowDuplicate": true, "disableCVVCheck": false, "disableAVSCheck": false }
`dynamicDescriptor`	`string`	Name of the dynamic descriptor used for the transaction.	`"001DynDesc"`

📘
Also see
For the more comprehensive reference on these, see API Reference.

Unlike capturing a transaction, where funds are collected against a single transaction entry, re-using this token initiates a completely new transaction. This new transaction generates its own transactionId and is independently recorded within the PayConex™ system.

Sale Example

For example, let's make a sale transaction using the bfTokenReference and compare the trace.history contents:

{
  "transactionId": "000000046066",
  "status": "CAPTURED",
  "timestamp": "2025-04-02T15:54:12.000000Z",
  "customer": {
    "name": "Alice",
    "billingAddress": {
      "address1": "address1",
      "address2": "address2",
      "city": "My City",
      "state": "MO",
      "zip": "90210",
      "country": "USA",
      "company": "Acme Inc."
    }
  },
  "shippingAddress": {
    "address1": "address1",
    "address2": "address2",
    "city": "My City",
    "state": "MO",
    "zip": "90210",
    "country": "USA",
    "company": "Acme Inc.",
    "recipient": "Alice Smith"
  },
  "trace": {
    "history": [
      {
        "action": "transaction",
        "requestId": "99f9527c-4cac-4eb5-8a7d-1c68ef95c409",
        "correlationId": "28401073-f667-48ce-94f2-870422667949",
        "timestamp": "2025-04-02T10:54:10-05:00"
      }
    ],
    "networkTransactionId": "015092915940715G239"
  },
  "amounts": {
    "currency": "USD",
    "approved": "10.01",
    "requested": "10.01",
    "balance": "10.01"
  },
  "auth": {
    "code": "OK2360",
    "processorMessage": "APPROVED",
    "message": "APPROVED",
    "networkName": "VISA",
    "avsResponseCode": "Y"
  },
  "card": {
    "name": "Alice",
    "last4": "1111",
    "expiry": "1225",
    "brand": "VISA"
  },
  "binData": {
    "program": "UNKNOWN"
  },
  "transactionType": "SALE",
  "entryMode": "KEYED",
  "refundObject": {
    "refundBalance": "10.01"
  },
  "shieldConexToken": {
    "bfid": "djI6MTI...",
    "cardNumber": "5850459886792406",
    "cardExpiration": "9527"
  }
}

Storing a Card on File

Overview

🚧
Note

Sample Request

🚧
Note

Example Response

Optional Fields

📘
Note

📘
Also see

Sale Example

Overview

🚧Note

Sample Request

🚧Note

Example Response

Optional Fields

📘Note

📘Also see

Sale Example

🚧
Note

🚧
Note

📘
Note

📘
Also see