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

PayIns

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.

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. By indicating the number of VCCs to be created, the sale remains in an open status until all expected cards have been created or the amount of the sale is consumed by the issued cards.

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 and that reflect your DBA name 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.

Statement Descriptors are not available for European clients. Including one may cause the sale to be declined.

Including Risk Data in Sale Request

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

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.

Card Tokenization

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

PayOuts

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 PayeeId 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 PayeeId in your Issue Card request allows our system to a) learn which PayeeId 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 IPO (Intelligent PayOuts) on this page.

PayIns and PayOuts

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 PayIns and PayOuts. 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 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.