Our Payment Gateway provides a safe and low cost way to run your transactions in a card not present environment, while supporting multiple processors, credit card brands, card types and currencies. It also support all of PayCertify fraud prevention products out-of-the-box.

Authorization

To use the gateway APIs you will need an API Token, which can be requested to support or navigating on your gateway account to Users > Details > Api Token.

With that token, you’ll be able to access our API. You should send your key in every request to our API, in order to authenticate and identify yourself. For every request, you should pass the Authorization HTTP Header containing your token, prefixed by “Bearer “ string. Example below:

An authentication error message would return a message like the following:

{"error":{"status":401,"message":{"base":["Not authenticated"]}}}

Please note that the error messages use the same structure of an error node, with then a message node, and subsequently either base being a general error, unrelated to any field submitted, fatal being a system error, or a field name, for example, amount when the request message contains any errors under that field. All messages also contain an HTTP status following W3C recommendations, e.g. an unauthenticated request will return HTTP status 401.

We include the HTTP status on the JSON message, as well as on the headers of all JSON error responses.

You must replace YOUR_API_TOKEN with your personal API key.

Rate limiting

Please note that API requests are rate-limited for security purposes. By default, you are not allowed to submit more than 60 requests per minute. X-RateLimit-Limit and X-RateLimit-Remaining headers are always present on the API responses so you can better manage your requests and put together a timing strategy. If that limit is exceeded, the server will return HTTP Status 429 and data will not be submitted to the processor. Our recommendation is using an exponential backoff strategy to make sure you do not over exceed the limits as this may result in permanent blacklisting.

{"error":{"status":429,"message":{"base":["Too Many Attempts."]}}}

If you need a limit higher than 60req/min, please contact support@paycertify.com with reasoning for the upgrade.

Transactions

We need to explain here what is a transaction, what is an authorization, what is settlement, what are the events, what are the differences between industries, etc.

Before starting up with actual API documentation, there are a few concepts that must be understood. On credit card processing, there are two main concepts which are fundamental parts of how funds go from the customer’s credit card to the merchant’s bank. Those are:

Authorization which stands for performing a debit or credit on a credit card, on a blocking fashion, without actually deducting the funds from the cardholder’s card. That means the balance is just blocked and cannot be used.

Settlement which stands for a process that usually happens nightly, to get all the authorizations performed and group them in a batch of transactions, that are submitted to the processor for actually deducting the funds from the cardholder’s card.

In order to keep those two concepts completely manageable by the merchant, on PayCertify Gateway™ we have implemented a Transaction Event concept, which is an append-only log, that keeps the whole transaction lifecycle intact. There are five different types of events:

An auth which stands for an authorization debit, with no settlement;

A capture which stands for an actual debit, by promoting a transaction with an auth event to settlement;

sale requests are exactly the combination of auth and capture, meaning it authorizes and flags that event for settlement;

A void which is an authorization credit, that cancels partially or fully a previous auth event;

refund stands for an authorization credit, plus an actual credit since it sends that record for settlement. It should be run after a capture or sale.

Examples

Scenario #1
Let’s say you want to charge a customer card for $10.00 and deduct those funds immediately our of their account. Then, on the next day, after settlement, you want to refund $5.00 to that customer. To accomplish that, you’ll run a sale event for $10.00 (which would both authorize the amount and flag it for batch settlement later that day) and then, on the next day, you could run a refund event for $5.00, and on the day after those funds would be credited back to your customer.

Scenario #2
Let’s say you want to authorize a customer card for $500.00 for a hotel room. Eventually, whenever that customer does the checkout, you’ll just bill $400.00. In that case, you could run an auth request for $500.00. After that, you’ll run a capture for $400.00. Once the customer does the checkout, you can void the missing $100.00.

Now that you understand the basic concepts behind Transaction Events and Authorization / Settlement, let's get started!

Charge a Credit Card

POST https://gateway-api.paycertify.com/api/transactions/sale

Charging a credit card using PayCertify gateway is simple. In this case, we’re performing a straight capture, so it’s an authorization and also a settlement request. If you’re looking just to authorize a certain amount, and then charge later, see Authorize and Charge later

[1] if processor_id has not been provided, the gateway will pick the record flagged as “default”.
[2] card_cvv is not required when running transactions with Address Verification Service enabled. There are some processors such as “PP - Offshore” that requires this field to be present on all authorizations.

[1] if processor_id has not been provided, the gateway will pick the record flagged as “default”.
[2] card_cvv is not required when running transactions with Address Verification Service enabled. There are some processors such as “PP - Offshore” that requires this field to be present on all authorizations.

Voiding a Transaction

A void is only possible after a transaction has been created through auth request. Once that’s done, you should use the transaction ID response field to reference the transaction being voided. A void simply cancels a previously made authorization and releases the authorized balance on the customer’s card.

Passing 3D Secure Data

3D Secure is a method to shift fraud liability from the merchant’s sphere to the issuing bank or card brand sphere. That means whenever a 3D Secure protected transaction is provided to the processor and authorized, that transaction cannot become a dispute or a chargeback, as the card brand and the issuing bank previously approved it from happening. All this happens in real-time, in a variety of methods.

When running 3D Secure authenticated transactions you should pass the MPI/ACS response to the gateway. Possible outcomes for a 3D Secure transaction are:

attempted which is returned whenever a 3DS request has been attempted but not fully validated by the card brand or issuer;

failed is returned whenever the card brand or issuer denied the transaction from happening;

success is returned whenever the transaction has been successfully protected and liability has been shifted;

error means the processor, issuer or card brand systems returned an error with the provided data;

unavailable means that 3DS is not available for the provided card.

This should be done either during a auth or sale event. Besides passing all fields for these event types, you will also need to pass the fields described below. All this data is provided by your 3DS MPI, after running the Payment Authentication Response (PaRes).

Address Verification

Address Verification Service is one way to confirm customer identity and remove fraud, while decreasing interchange rates. By providing the customer’s full address, you add another layer of security and consequently fetch more data from the processors, while protecting you from fraud. Our address verification service returns five different statuses to identify the outcome of an AVS request attempt: exact_match, partial_match, no_match, error and unavailable.

exact_match is returned whenever the address matches the records. That usually means the address, city, state, country and postal code match;

partial_match is returned whenever the processor is able to match parts of the information provided;

no_match is returned whenever there aren’t records matching the data provided;

error means the processor or issuer systems returned an error with the provided data;

unavailable means that AVS is not available for the provided card.

AVS should be done either during a auth or sale event. Besides passing all fields for these event types, you will also need to pass the fields described below.

Airline & Travel Data

PayCertify Gateway™ has some built-in features for the Airline and Travel industries. Whenever submitting a transaction for those industries, you can pass additional information which will both populate on our Gateway’s user interface and also on the customer’s credit card statement, besides sending additional data to the processors which help on reconciliation, dispute, risk, fraud mitigation and chargeback representment processes. This data includes:

Passenger name and ticket details such as ticket number, issuing city, carrier and date;

Restricted ticket indicators (for tickets that cannot be refunded);

Leg information such as carrier code, service class, departure and destination airports and fares;

For each passenger you want to use the reporting capabilities, you should be submitting an object under the passenger_transport field. As for each leg, you should be submitting information under the passenger record, even if all passengers are doing the same itinerary.

Make sure that the processor_id being used for this feature has industry field as passenger_transport.

[1] The amount provided should match the sum of passenger_transport.*.legs.*.fare records.
[2] Whenever the issuing carrier is not available, use the carrier that has the majority of legs on this trip.
[3] Whenever the issuing city is not available, use the merchant’s headquarters city.
[4] The dates should be supplied on the first leg departure airport timezone.

For Airline & Travel, whenever running a capture, void or refund event, you need to reference which passenger you are authorizing / voiding / refunding. In order to do that, whenever running an auth you need to store the passenger IDs sent back on the auth or sale event. You can run any of these events for multiple passenger at a time, as long as you reference the proper amounts / passenger_id pairs.

Dynamic Descriptors

A dynamic descriptor is a string passed to the processor to be displayed on the customer’s card statement while overriding default information such as the merchant’s name, merchant phone, website or city. Our dynamic descriptor implementation uses a pipe element | to separate the name from the contact info (which may be the city, phone or website). So for example, a dynamic descriptor passed as MYBUSINESSINC|123-1231234 will be interpreted at processor level as name=MYBUSINESSINC and contact info=123-1231234.

Each processor has it's own constraints for showing up data, and sometimes this also varies by card issuer. If you are having display issues or would like help setting up this feature properly, contact us.

Using Tokenization

In order to use a Tokenized credit card for authorization and sale, you can use the Tokenization tool in order to use the tokenized card instead of the original credit card info given.

When using Tokenization, you should not send original credit card info as: `card_number`, `card_expiry_month` and `card_expiry_year`. If you are having display issues or would like help setting up this feature properly, contact us.

List all Transactions

GET https://gateway-api.paycertify.com/api/transactions

In order to list all the transactions that have been sent through the gateway, you can use this endpoint. Please note that for every new event that is sent under the same transaction, the transaction’s updated_at field is updated.

Filtering is enabled to this endpoint through query parameter search. So whenever searching for a field, make sure to submit it through the endpoint’s query parameters, for example: https://gateway-api.paycertify.com/api/transactions?search[first_name]=John&search[last_name]=Doe. Filter types are described below:

starts with which matches for records on a SQL LIKE fashion, e.g.: a string “PayC” will match “PayCertify”;

exact comparison which matches for records through exact comparison, case sensitive, e.g.: a string “Paycertify” will NOT match “PayCertify”;

date which matches for records through SQL date, and these fields should be provided on Y-m-d H:i:s format, e.g.: 2025-01-01 17:59:00

Also, this endpoint provides pagination to navigate through record sets. Pagination information can be found on meta response field. The pages always return 50 records at a time. While using reporting capabilities, make sure to monitor rate limits through X-RateLimit-Limit and X-RateLimit-Remaining response headers.

Processors

Processors are a group of variables that are demanded to be configured in order to communicate to the banks and card brand systems. Each processor demands different data to be filled, so the schema on processor creation varies accordingly to which processor your business is going to be using. In order to start using our gateway, you need to have at least one Processor record in place.

Processor changes may affect your system's uptime and the transactions performed in the meantime will be lost. Make sure to have our support team helping you with these changes.

List all processors

GET https://gateway-api.paycertify.com/api/processors

This endpoint lists all processors previously entered through the UI. Pagination is available to navigate through record sets. Pagination information can be found on meta response field. The pages always return 50 records at a time. While using reporting capabilities, make sure to monitor rate limits through X-RateLimit-Limit and X-RateLimit-Remaining response headers.

Tokenization

The idea is to swap payment card data with a randomized number in the same format with no intrinsic value of its own. The difference from encryption is that the original pattern is still “locked”. Encrypted values can be decrypted with the key, brute computing force, or through a hacked/stolen key. Tokens, by the other hand, have no mathematical relationship between the token and its original number, then it cannot be decrypted. De-tokenization can only be done by the PayCertify tokenization system.

Tokenize

POST https://gateway-api.paycertify.com/api/tokens/tokenize

This endpoint tokenizes a given credit card number. You will need to provide the card number you wish to store and then you will be able to retrieve the card number with the original number out of the token provided on the response.

Detokenize

POST https://gateway-api.paycertify.com/api/tokens/detokenize

This endpoint detokenizes a given credit card token. You will need to provide the token you wish to detokenize and as part of the response you’ll get the original number previously stored and it’s expiration month and year.

Third Party Plugins

PayCertify’s Payment Gateway has direct integration to the leading shopping carts / ecommerce frameworks in the market. We provide an easy to install option for teams that are looking for a simple, easy to use, click-install integration. Current options are listed below.

Using a different shopping cart or need help installing your shopping cart? Reach out to support@paycertify.com.

WooCommerce Plugin

The PayCertify plugin for WooCommerce allows you to accept payments directly on your store instead of being redirected to an externally hosted checkout page, which has been proven to lead to higher conversion rates.

Automatic Installation

Automatic installation is the easiest option as WordPress handles the file transfers itself and you don’t need to leave your web browser. To
do an automatic install, log in to your WordPress dashboard, navigate to the Plugins menu and click Add New.

The resulting installation screen will list the installation as successful.

Click Activate Plugin to activate it, or Return to Plugin Installer for further actions.

Manual Installation

The manual installation method involves downloading our plugin and uploading it to your web server via your favorite FTP application. There are a few cases when manually installing a WordPress Plugin is appropriate.

If you wish to control the placement and the process of installing a WordPress Plugin.

If your server does not permit automatic installation of a WordPress Plugin.

The WordPress Plugin is not in the WordPress Plugins Directory.

Installation of a WordPress Plugin manually requires FTP familiarity and the awareness that you may put your site at risk if you install a WordPress Plugin incompatible with the current version or from an unreliable source.

Backup your site completely before proceeding.

To install a WordPress Plugin manually:

Download your WordPress Plugin to your desktop.

If downloaded as a zip archive, extract the Plugin folder to your desktop.

Read through the “readme” file thoroughly to ensure you follow the installation instructions.

Updating

Automatic updates should work like a charm; as always though, ensure you backup your site just in case.

Setting Up

After installing your PayCertify WooCommerce Plugin, you need to add your credentials to it and set it up. To
setup the plugin, log in to your WordPress dashboard, navigate to the Plugins menu, click Installed Plugins, find the “PayCertify Gateway” plugin and click on Settings.

First of all, we need to enable the plugin. Check the “Enable PayCertify Gateway” box.

Title: is the name of the plugin that will be shown on your shop checkout page as a payment option. You can keep it as PayCertify Gateway or change it to what you want.

Description: is the information that customer will see during the checkout process.