Integration Best Practices

This page contains best practices to consider when integrating with our APIs.

Including Address Verification with Sales Request

Including Address information (“Address1” and “Zip”) in the Card. Customer object when processing an online sale optimizes the interchange expense. The card brands (Visa, Mastercard, Discover, and American Express) consider transactions that include this information to be less risky transactions and therefore don’t charge as high a fee as when the Address information is not included.

Including unique Order Numbers for Sales and Issue Card

Order Number in our system is the universal ID to search and a great way to tie Sales and Purchases. They even come through in the Chargeback Management System to allow chargebacks to be tied to the original sale. Without the Order Number, it becomes a bit of a challenge to match.

Even though this is an optional field in the API, it is highly encouraged to include.

Including Risk Data and Flight Data in Sale Request

In order to make the best use of our fraud monitoring solution, the more data that is submitted, the better and more accurate the results are. These are not required fields but highly recommended in order to best utilize our risk mitigation tool.

Setting the Correct Expected Payments in Sale Request

The Expected Payments property in the Sales API tells us how many VCCs you intend to create from the one sale. This is important to set correctly for a couple of reasons:

• You plan on creating more than one VCC. By indicating the number of VCCs to be created, you tell us to keep the sale open until all have been created.

• The daily funding calculations do not kick until either the total issued amount is equal to the sale amount OR the number of VCCs created is equal to the expected payments indicated. There will be times where you will create a VCC for less than the sale amount. By telling us you will only create one VCC we know that the sale is complete and we can go ahead and calculate your daily margin.

Setting the correct UsageLimit when issuing Virtual Credit Cards

The UsageLimit is a required parameter in the Issue Card request that controls how many times the VCC can be authorized. This is a critical parameter to pay attention to as it can result in unintended declines when the Supplier runs the VCC. Even though many times the VCC is considered a “one-time-use” card, many clients will simply default this value to 10 (even though the majority of the time they only expect one authorization). The reason for this is depending on the supplier accepting the VCC, they may split up the VCC payments and process multiple authorizations vs one large authorization. Many airlines for example split up the VCC authorizations based on the number of tickets purchased. If the Usage Limit is set to 1, the first transaction on the VCC will be approved, however, the subsequent attempts will result in a decline back to the Supplier.

Setting the VCC Expiration and Termination Dates

ConnexPay Virtual Cards have two dates applied to them. The first is the card expiration date. Think of this as the date annotated on the front of your physical credit cards; the one that a supplier sees when entering your credit card information to determine it's validity. The second is the card termination date. This date is the date that, in reality, determines when a card is no longer active.

Expiration dates are automatically added to virtual cards as the issue date plus 3 years. So if the card is issued on 5/1/22, the expiration date on the card defaults to 5/25).

For cards issued in USD, you do have the ability to provide an expiration date that will overwrite the three year default. The expiration date does not control the activation of the card, so typically the three year default is the best route to go.

For cards issued in other currencies, the default of issue date plus three years can not be overwritten.

Including SupplierId when issuing Virtual Credit Cards

We’ve built out a robust decisioning engine that can systematically determine what cards should be accepted and also what VCCs should be issued in order to maximize acceptance and rebates. Including a SupplerId in your Issue Card request allows our system to a) learn which SupplierId maps to what merchant and b) make better decisions on issuing in the future when creating a VCC for that same Supplier. You can find more details about IPR (Intelligent Purchases Routing) on this page.

Including unique Sequence Numbers for Sales and Issue Card

Unfortunately, in technology, there are occasional issues that prevent API responses from getting back to the requester for one reason or another. Or, times where the request doesn’t get sent from the requester.

Optimally you want the transaction to go through (or else you wouldn’t have sent it in the first place). So instead of having different API routes to check the status of whichever request you submitted or having offline processes that slow things down and create potentially undesired customer experiences, we suggest sending the same request back to us with the same SequenceNumber included in both requests. When we receive a request that is the same payload and specifically includes the same SequenceNumber, we will either:

• Return the same response as the original request if we’ve already seen this request (new Sale will NOT be processed and new VCC will NOT be issued since it was issued in the original request) or,

• Process the sale or issue a new VCC and respond with those Sale or VCC details as if we’ve never seen this request before

📘

Voiding/Cancelling Sales when IssueCard Fails
When a Sale (on a credit card) is processed but the IssueCard call fails, the IssueCard call should be attempted again (discussed in the SequenceNumber functionality section above). If the second IssueCall fails or is not attempted, the credit card should be voided if there are no plans to actually proceed with the transaction. Failing to void a customer’s credit card usually results in unhappy customers and sometimes ends in a time-consuming chargeback process.

Sending a useful Statement Descriptor in the Sale Request

The Statement Descriptor (“StatementDescription” in Sales API) is a dynamic field that you can pass in the Sale request and it’s the name that will appear on you customer’s cardholder statement. It’s important to send Statement Descriptors that are very descriptive so that the customer knows exactly what the transaction was for. Using vague Statement Descriptors can lead to increased chargebacks as customers may not realize what a transaction was for if not described properly.

American Express does not allow OptBlue clients to customize the statement descriptors.

Utilize Kount’s Device Collector for Better Risk Management

We highly suggest using Kount’s Device Collector on your site to collect more useful information about the cardholder. This additional data will give Kount better information to provide a more accurate decision on the risk of accepting a Sale. You can find more information here.

Other Considerations

Take a look at how you can issue a VCC for more than the sale amount with Tolerances.

You can supplement your data with ours by sending Addendum information tied to a specific VCC.

If there was a mistake and/or you need to add more money to the VCC, we offer the ability to Reload a VCC.

Utilize our card tokens instead of storing credit card information on your servers to reduce your PCI scope.