Processing a Sale

Overview

Processing a SALE transaction authorizes funds on the card and flags the transaction to be captured for settlement at the next settlement time.

As previously mentioned, to generate the PayConex™ token needed to process your transactions, use the Checkout Component with the PCI-compliant environment provided by Bluefin. For more details, see PayConex™ and ShieldConex®.

After tokenizing card holder data, we are set to make a simple CNP sale transaction.

📘
Did you know?
You can request a transactionId value prior to processing a transaction by simply initializing a transaction. This option can help with mitigating communication errors and other potential complications. For more information, see our guide Initializing a Transaction.

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

{
  "bfTokenReference": "PAYCONEX_TOKEN",
  "posProfile": "ECOMMERCE",
  "amounts": {
    "total": "5",
    "currency": "USD"
  }
}

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

Transaction Processing: Token Retrieval

With savePaymentOption set to true, it is important to note that, in response, the token gets vaulted so that we can use it to reissue transactions. For example, if a developer wants to save a customer's payment details to charge their card later (for recurring billing or delayed charges), they can use the same token to reference the original payment information and process subsequent transactions without needing the card details again.

Also see Customer and Merchant Initiated Transactions and Storing a Card on File.

For example, if we set savePaymentOption to true, the CIT sale/store/authorization transaction response includes bfTokenReference and shieldConexToken. Otherwise, they are stripped out.

🚧
Transaction Metadata
Both bfTokenReference and shieldConexToken are stripped out from the transaction metadata at all times for security purposes.

{
  "transactionId": "000000062826",
  "status": "CAPTURED",
  "timestamp": "2025-07-30T17:06:34.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": "8cf78267-fbfd-48c5-988e-2c658b5408d8",
        "correlationId": "0f4ab608-9160-49a1-85ca-05d717282593",
        "timestamp": "2025-07-30T12:06:31-05:00"
      }
    ],
    "networkTransactionId": "015211389866947G049"
  },
  "amounts": {
    "currency": "USD",
    "approved": "4.00",
    "requested": "4.00",
    "balance": "4.00"
  },
  "auth": {
    "code": "OK4334",
    "processorMessage": "APPROVED",
    "message": "APPROVED",
    "networkName": "VISA",
    "avsResponseCode": "Y"
  },
  "card": {
    "name": "Alice",
    "last4": "1111",
    "expiry": "1225",
    "brand": "VISA"
  },
  "binData": {
    "program": "UNKNOWN"
  },
  "transactionType": "SALE",
  "entryMode": "KEYED",
  "bfTokenReference": "bft_4063...",
  "refundObject": {
    "refundBalance": "4.00"
  },
  "shieldConexToken": {
    "bfid": "djI6MT...",
    "cardNumber": "5850459886792406",
    "cardExpiration": "9527"
  }
}

From this point on, even if we process another transaction with the same PayConex token, the bfTokenReference and shieldConexToken are not included since it is then an MIT transaction.

📘
A note on Storing and Reissuing Transactions
Visa now mandates that transactions specify if they were customer or merchant initiated when storing or reissuing. As our back-end processors add additional parameters in order to comply with Visa's mandate, so does our gateway. See the guide on Customer and Merchant Initiated Transactions Guide for more information and see Customer and Merchant Initiated Transactions for detailed request parameters.

More Complex Sale Transaction

{
  "rules": {
    "allowPartial": true,
    "allowDuplicate": true
  },
  "bfTokenReference": "PAYCONEX_TOKEN",
  "posProfile": "ECOMMERCE",
  "amounts": {
    "total": "5",
    "currency": "USD"
  },
  "customer": {
    "name": "Alice",
    "billingAddress": {
      "address1": "address1",
      "address2": "address2",
      "city": "Kansas City",
      "state": "MO",
      "zip": "90210",
      "country": "USA",
      "company": "Acme Inc."
    }
  },
  "shippingAddress": {
    "address1": "address1",
    "address2": "address2",
    "city": "Kansas City",
    "state": "MO",
    "zip": "90210",
    "country": "USA",
    "company": "Acme Inc.",
    "recipient": "Alice Smith"
  },
  "level2": {
    "merchantReference": "121231",
    "orderId": "1234567",
    "tax": "0.05",
    "zip": "90210"
  },
  "level3": {
    "summaryCommodityCode": "8012",
    "shipFromZip": "12345"
  },
  "items": [
    {
      "commodityCode": "09.02.10",
      "description": "High-resolution camera module",
      "productCode": "ABC123",
      "quantity": "112.4595",
      "unitOfMeasure": "units",
      "unitCost": "12.50"
    }
  ],
  "billPayment": {
    "type": "SINGLE"
  },
  "credentialOnFile": {
    "transactionInitiator": "CUSTOMER",
    "storedCredentialIndicator": "INITIAL",
    "scheduleIndicator": "UNSCHEDULED"
  },
  "trace": {
    "customId": "asdf123",
    "cashier": "A920:0820617507",
    "sourceIp": "192.168.2.202",
    "clientIp": "100.33.36.118",
    "gpsLocation": {
      "latitude": "",
      "longitude": ""
    },
    "source": "PayConex V4",
    "timestamp": "2023-10-24T13:32:08.603Z",
    "tags": [
      "ACX42342"
    ]
  }
}

📘
Note
In the case of personal information such as customer and shippingAddress, these get re-tokenized and overwritten as they can be included in the PayConex™ token generated via the Checkout Component or vaulted via reissuing payment.

`billPayment`

The data specified in this property goes to the Payment Processor and then, on to the card issuers, reducing the interchange rate or fees when used correctly. This field can be used in combination with the Customer/Merchant Initiated credentialOnFile.

Parameter	Type	Description
`type`	`string`	The type of bill payment includes `["SINGLE", "DEFERRED", "RECURRING", "INSTALLMENT"]`. Recurring and installment are frequently used for MITs where a recurrence is indefinite, and an installment has a set number of payments to be fulfilled.
`recurring`	`object`	This data is only applicable when the type is `"RECURRING"`. See below.
`installment`	`object`	This data is only applicable when the type is `"INSTALLMENT"`. See below.

`recurring`

Parameter	Type	Description	Example
`recurringReference`	`string`	A reference used to identify the source of the recurring payment.	`"12345678910"`
`recurringPaymentNumber`	`integer`	The number of the recurring payment in the series.	`1`

`installment`

Parameter	Type	Description	Example
`installmentCount`	`integer`	The total number of installments to be paid.	`10`
`installmentNumber`	`integer`	The current installment number (cannot exceed the installment count).	`3`

`rules`

Parameter	Type	Description
`allowPartial`	`bool`	Enables partial authorizations on a per-transaction basis. For this to work, the `Allow API Override` option must be checked in the PayConex™ Portal. This must also be configured internally by Bluefin as part of your account setup. See Allow API Override. This method allows customers to avoid declines and capture only a portion of the amount available on their card at the time of the transaction. The merchant can still process the payment for the available amount and potentially follow up for the remaining balance later as a whole new transaction. The charge amount that remains can be determined by `auth.message` `PARTIALLY APPROVED` and the merchant can get `amounts.approved` to see the remaining amount to charge to complete the payment with, most likely, a different card.
`allowDuplicate`	`bool`	Enables duplicate transactions by overriding the account settings. This setting is particularly useful in environments where transactions are processed in bulk or where certain transactions are expected to appear more than once for valid reasons. Duplicate transactions are typically intentional or acceptable for business purposes.
`disableCVVCheck`	`bool`	Whether the CVV decline rules should be skipped. This option is directed towards the Payment Processor regarding the CVV decline rules. For example, see PayPal AVS and CVV Rules. Some of the use cases with this option set to `true` include: - Recurring or Subscription Payments: Where for subsequent payments, skipping CVV validation can be necessary. - CNP transactions: When a token representing the card is used, the CVV may not be required because the card details were validated during token creation. - High-Trust Customers: Merchants may bypass CVV checks for trusted customers to reduce friction and improve user experience. - Prepaid Cards or Gift Cards: Some card types may not include a CVV or are used in environments where CVV validation is impractical.
`disableAVSCheck`	`bool`	Whether the AVS decline rules should be skipped. AVS verifies the billing address provided in the transaction against the address on file with the issuing bank. This option is directed towards the Payment Processor regarding the AVS decline rules. For example, see PayPal AVS and CVV Rules. Some of the use cases with this option set to `true` include: - Digital Goods or Services: For low-value, low-risk transactions where shipping isn't involved, address validation may be deemed unnecessary. - International Transactions: AVS checks can fail for foreign cardholders due to differences in address formats or lack of AVS support by certain issuers. - Mobile or Point-of-Sale Payments: In-person transactions (e.g., via NFC or chip readers) often rely on CVM rather than AVS, making address validation redundant. See PayConex™ V4 CVM. - Expedited Checkouts: Skipping AVS may be part of a "streamlined checkout" process where minimal customer input is required.

Allow API Override

📘
Also see
For more on credentialOnFile and other parameters, see:

Customer and Merchant Initiated Transactions

Getting Transaction Metadata

Point of Sale Profiles

API Reference Sale Transaction

Processing a Sale

Overview

📘
Did you know?

Transaction Processing: Token Retrieval

🚧
Transaction Metadata

📘
A note on Storing and Reissuing Transactions

More Complex Sale Transaction

📘
Note

`billPayment`

`recurring`

`installment`

`rules`

Allow API Override

📘
Also see

Overview

📘Did you know?

Transaction Processing: Token Retrieval

🚧Transaction Metadata

📘A note on Storing and Reissuing Transactions

More Complex Sale Transaction

📘Note

billPayment

recurring

installment

rules

Allow API Override

📘Also see

📘
Did you know?

🚧
Transaction Metadata

📘
A note on Storing and Reissuing Transactions

📘
Note

`billPayment`

`recurring`

`installment`

`rules`

📘
Also see