When conducting a transactions it's a recommended best practice to include card or bank holders data in the request (also known as Billing Information). Providing Bill Information with every request has several benefits from lower interchange due to AVS to higher authorization (in particular when processors have their own internal fraud monitoring systems)

The Preczn Payments API seamlessly stores and maintains this information with every transaction.

What Billing Information Properties Are Stored

Preczn stores Billing Information that could be used in the future transactions to improve authorization and interchange.

Billing Information is a subset of values that are included in the Payments API request body. These values currently include:

• firstName
• lastName
• phone
• email
• billingAddress (including all child properties)

⚠️

Limitation for CRM Data

While Preczn stores Billing Information to help with transaction authorization and interchange, Preczn should not be considered a full CRM for all customer data. Shipping Information, Metadata, and other various customer information should be maintained within your application or a full featured CRM.

How To Store Billing Information

Because Billing Information is associated with a card or account holder, all Billing Information is ultimately stored with a Preczn Multi-Use Token.

Billing Information is stored anytime there is a successful API request transaction using or resulting in a Multi-Use Token.

Use Case Example

As an example, when using a Single Use Token returned from the Preczn PaymentFields, if the request includes the query parameter tokenize=true and includes any of the Billing Field properties, then those values will automatically be stored with the multi-use token.

To further illustrate, let's review an example request:

curl --request POST \
     --url 'https://api.preczn.com/v1/transactions?tokenize=true' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "type": "sale",
  "payment": {
    "token": "tkn_5kpqt630zh9kdrev2kxmdr66tr"
  },
  "billingAddress": {
    "postal": "10001"
  },
  "currency": "USD",
  "merchantId": "mid_2zyd88xrnr90xskmjmqpd0x1vj",
  "amount": 110,
  "firstName": "Bob",
  "lastName": "Johnson"
}
'

In this request, the following properties would be stored with the resulting mult-use token:

• firstName
• lastName
• billingAddress.postal

💡

Considering Decline and AVS Scenarios

Billing Information is stored regardless of the Approval state of the transaction.
This is because the information included in the request is assumed to be the most up-to-date information provided by the customer.

If an AVS check is not an exact or partial match, you may want to prompt the customer to review and update their information.

Similarly, declines can occur for various reasons, including fraud checks. You may choose to review the payment provider’s reason codes and, in certain instances, ask customers to review their information.

More details on updating Billing Information can be found in the How to Update Billing Information.

⚠️

Retroactive Storing of Billing Information

Please note that storing of Billing Information is only available as of {INSERT RELEASE DATE}.

If you have run transactions prior and wish to store the billing information, please contact Preczn store and we will discuss options for retrieving the data.

How To Use Billing Information with Subsequent Transactions

Billing Information is stored with multi-use tokens. When making a subsequent transaction with the same multi-use token, the Billing Information associated with the transaction will be used in the transaction (unless otherwise explicitly included in the request)

Using the prior transaction example, let's assume a subscription renew occurs. In this case, a subsequent sales transaction is made with the same multi-use token.

curl --request POST \
     --url 'https://api.preczn.com/v1/transactions?tokenize=true' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "type": "sale",
  "payment": {
    "token": "tkn_5kpqt630zh9kdrev2kxmdr66tr"
  },
  "currency": "USD",
  "merchantId": "mid_2zyd88xrnr90xskmjmqpd0x1vj",
  "amount": 110,
}
'

Even though the firstName, lastName, and billingAddress.postal where not included in the request, these values will be used in the transaction and included in the response.

{
  "amount": 110,
  "authorization": {
    "approvedAmount": 110,
    "avs": "M",
    "cvv": "U",
    "partial": false,
    "processorCode": "1",
    "processorMessage": "APPROVED",
    "processorTransactionId": "t1_txn_67d3329e4e95cd0bbb07de3",
    "status": "A"
  },
  "billingAddress": {
    "postal": "10001"
  },
  "firstName": "Bob",
  "id": "txn_test_2vtd3wzqg087895n6wgkqy67kp",
  "lastName": "Johnson",
  "payment": {
    "bin": "424242",
    "brand": "VISA",
    "expiration": "1124",
    "last4": "4242",
    "token": "tkn_5kpqt630zh9kdrev2kxmdr66tr",
    "type": "CREDIT"
  },
  "currency": "USD",
  "merchantId": "mid_2zyd88xrnr90xskmjmqpd0x1vj",
  "plan": {
    "id": "plan_test_1zkybszn8g8tvtwrambs64g620",
    "name": "Documents Plan"
  },
  "platformId": "7gtxx4ftsr958tgkjjay1jbhsw",
  "processor": {
    "id": "rpkwm89dr8br9zvqw4bwxgktz",
    "name": "Payrix"
  },
  "type": "sale"
}

Overwriting Existing Data

When a request includes billing information that already exists, Preczn prioritizes the request data during the transaction and ultimately updates the stored value.

As an example, let's assume the multi-use token has the following Billing Information:

Now, assume during the transaction that the customer decided to update their first name and add their phone number

When Preczn runs the transaction with the processor, we treat the information included in the request with priority. As a result, the information included in the request and stored in the updated Billing Information is

How to Access Billing Information

If you need to display existing billing information to your customer without processing a transaction, you can use the Preczn Get Token endpoint to retrieve the stored billing information properties.

The response will include all properties under the billing information object.

{
  "id": "tkn_5kpqt630zh9kdrev2kxmdr66tr",
  "merchantId": "mid_2zyd88xrnr90xskmjmqpd0x1vj",
  "type": "credit",
  "brand": "VISA",
  "bin": "432100",
  "last4": "0012",
  "firstName": "Bob",
  "lastName": "Johnson",
  "phone": "555-555-5555",
  "email": "[email protected]",
  "billingAddress": {
    "address": "123 Drive Way",
    "address2": "Unit 2",
    "city": "New York City",
    "region": "NY",
    "postal": "10001",
    "country": "USA"
  },
  "createdOn": "2024-04-21T23:16:45Z",
  "modifiedOn": "2024-04-21T23:16:45Z"
}

How To Update Billing Information

Billing information is updated exclusively through transaction requests. If an update to billing information is needed outside of a regular transaction, perform a verify transaction type request, including the new billing information in the request body.

This approach also provides the added benefit of verifying the customer’s AVS information in scenarios where the payment processor supports it.