Gateway


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:

curl -H 'Authorization: Bearer YOUR_API_TOKEN' https://gateway-api.paycertify.com/api/transactions

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.

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."
            ]
        }
    }
}

Test Card Numbers

In order to help customers with the integration process with our API, the following list contains card numbers that can be used for testing purposes.

Credit Card Brand PAN EXP CVV
Visa 4012000098765439 12/20 999
MasterCard 5499740000000057 12/20 998
AMEX 371449635392376 12/20 997
Discover 6011000993026909 12/20 966
Diners 3055155515160018 12/20 996
JCB 3530142019945859 12/20 996
Important - Relevant Information for Skrill

For tests purposes in Skrill you should use any valid date in the future (formatted as MM/YY) as EXP, a random number as CVV and any of the card numbers in the following list:

Credit Card Brand PAN
MasterCard for Skrill 5438311234567890
Visa for Skrill 4000001234567890
Amex for Skrill 371234500012340

APPROVAL/DECLINES

  • every single transaction with valid test cards should approve
  • whenever amount is greater than 999999.99, decline
  • if CVV doesn’t match the above test cards, decline

AVS

  • whenever enabled and street_address_1 = 59 North Santa Cruz Av and state = CA and zip = 95030, full avs match
  • whenever enabled and street_address_1 = anything and state = CA and zip = 95030, partial match
  • enabled and anything else no match

    Card 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.

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

Parameter Type Length Presence Description Example
processor_id uuid 36 Optional[1] The Processor record ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
amount number 0.01-9999999 Required Total transaction amount 3.56
card_number string 8-19 Required The credit card to charge 411111111111111
card_expiry_month string 2 Required The expiration month with two positions 12
card_expiry_year string 4 Required The expiration year with four positions 2025
card_cvv string 3-4 Conditional[2] 3 or 4 digit card verification code 123
merchant_transaction_id string 1-255 Required A merchant assigned identifier (your transaction ID) my-order-id-0001
first_name string 1-255 Optional Customer’s first name John
last_name string 1-255 Optional Customer’s last name Doe
email string 1-255 Optional Customer’s email support@paycertify.com
mobile_phone string 11-15 Optional Customer’s phone in E.164 format +11231231234
street_address_1 string 1-255 Optional Billing address first line (street address) 59 N Santa Cruz Avenue
street_address_2 string 1-255 Optional Billing address second line (suite, apt, etc) Suite M
city string 1-255 Optional Billing address city Los Gatos
state string 2 Optional Billing address state abbreviation, ISO 3166-2 format. CA
country string 2 Optional Billing address country abbreviation, ISO 3166-1 alpha-2 format. US
zip string 5 Optional Billing address 5-digit postal code 95030
shipping_street_address_1 string 1-255 Optional Shipping address first line (street address) 59 N Santa Cruz Avenue
shipping_street_address_2 string 1-255 Optional Shipping address second line (suite, apt, etc) Suite M
shipping_city string 1-255 Optional Shipping address city Los Gatos
shipping_state string 2 Optional Shipping address state abbreviation, ISO 3166-2 format. CA
shipping_country string 2 Optional Shipping address country abbreviation, in ISO 3166-1 alpha-2 format. US
shipping_zip string 5 Optional Shipping address 5-digit postal code 95030
ip_address string 12 Required Customer’s IP address 192.168.108.105

[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.

Parameter Type Length Description Example
transaction.id uuid 36 This transaction’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.merchant_id uuid 36 The user’s merchant ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.user_id uuid 36 The user’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.processor_id uuid 36 The processor’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.merchant_transaction_id string 1-255 The merchant assigned identifier my-order-id-0001
transaction.updated_at datetime - Last time this transaction was updated, on ISO 8601 UTC 2018-02-16T16:33:40+00:00
transaction.created_at datetime - Time that transaction was created, on ISO 8601 UTC 2018-02-16T16:33:40+00:00
transaction.events.*.id uuid 36 This event’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.events.*.success boolean - If the event was a successful event or not true
transaction.events.*.event_type string 4-10 The type of event being performed auth, capture, sale, void, refund
transaction.events.*.amount number 0.01-9999999 Total event amount 3.56
transaction.events.*.processor_code string 2-10 The processor response code 00
transaction.events.*.processor_message string 1-255 A human readable message from the processor APPROVAL V12341
transaction.events.*.processor_transaction_id string 1-255 A processor assigned identifier 00000000143242
transaction.events.*.updated_at datetime - Last time this event was updated, on ISO 8601 UTC 2018-02-16T16:33:40+00:00
transaction.events.*.created_at datetime - Time that event was created, on ISO 8601 UTC 2018-02-16T16:33:40+00:00

PS: All fields that are included on the authorization message are also echoed back.

curl --request POST \
  --url https://gateway-api.paycertify.com/api/transactions/sale \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --form 'amount=1.00' \
  --form 'card_number=4111111111111111' \
  --form 'card_expiry_month=12' \
  --form 'card_expiry_year=2020' \
  --form 'card_cvv=999' \
  --form 'first_name=John' \
  --form 'last_name=Doe' \
  --form 'street_address_1=59 N Santa Cruz Avenue' \
  --form 'street_address_2=Suite M' \
  --form 'city=Los Gatos' \
  --form 'state=CA' \
  --form 'country=US' \
  --form 'ip_address=127.0.0.1' \
  --form 'dynamic_descripton=MY-DESCRIPTOR' \
  --form 'mobile_phone=+11231231234' \
  --form 'email=support@paycertify.com' \
  --form 'merchant_transaction_id=my-order-id-0001' \
  --form 'zip=95030'

Responds with:

{
  "transaction": {
    "id": "3410596f-d596-42d4-9811-41d43868e984",
    "merchant_id": "455a1c64-385b-41b2-a56f-34bf6c5c5335",
    "user_id": "6e064bf5-0e18-466b-811b-f967e8d73b9f",
    "processor_id": "30ff7682-6ec7-48f3-8d7a-62319a9c3c59",
    "merchant_transaction_id": "my-order-id-0001",
    "card_number": "411111******1111",
    "card_brand": "visa",
    "card_expiry_month": "12",
    "card_expiry_year": "2020",
    "first_name": "John",
    "last_name": "Doe",
    "street_address_1": "59 N Santa Cruz Avenue",
    "street_address_2": "Suite M",
    "city": "Los Gatos",
    "state": "CA",
    "country": "US",
    "zip": "95030",
    "email": "support@paycertify.com",
    "mobile_phone": "+11231231234",
    "updated_at": "2018-02-16T16:33:40+00:00",
    "created_at": "2018-02-16T16:33:39+00:00",
    "events": [
        {
            "id": "84a8ab86-ee0e-47d4-8686-4e42fa58355e",
            "success": true,
            "threeds_response": null,
            "avs_response": null,
            "event_type": "sale",
            "amount": "1.00",
            "ip_address": "127.0.0.1",
            "processor_code": "00",
            "processor_message": "APPROVAL TAS656 ",
            "processor_transaction_id": "000000000252616",
            "processor_threeds_response": null,
            "processor_avs_response": "0",
            "updated_at": "2018-02-16T16:33:40+00:00",
            "created_at": "2018-02-16T16:33:39+00:00"
        }
    ]
  }
}

Authorize and Charge Later

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

In order to charge later, you need to make two requests: first an auth request, which blocks balance on customer’s credit card, and then run capture request, to flag the authorization for settlement.

Parameter Type Length Presence Description Example
processor_id uuid 36 Optional[1] The Processor record ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
amount number 0.01-9999999 Required Total transaction amount 3.56
card_number string 8-19 Required The credit card to charge 411111111111111
card_expiry_month string 2 Required The expiration month with two positions 12
card_expiry_year string 4 Required The expiration year with four positions 2025
card_cvv string 3-4 Conditional[2] 3 or 4 digit card verification code 123
merchant_transaction_id string 1-255 Required A merchant assigned identifier (your transaction ID) my-order-id-0001
first_name string 1-255 Optional Customer’s first name John
last_name string 1-255 Optional Customer’s last name Doe
email string 1-255 Optional Customer’s email support@paycertify.com
mobile_phone string 11-15 Optional Customer’s phone in E.164 format +11231231234
street_address_1 string 1-255 Optional Billing address first line (street address) 59 N Santa Cruz Avenue
street_address_2 string 1-255 Optional Billing address second line (suite, apt, etc) Suite M
city string 1-255 Optional Billing address city Los Gatos
state string 2 Optional Billing address state abbreviation, ISO 3166-2 format. CA
country string 2 Optional Billing address country abbreviation, ISO 3166-1 alpha-2 format. US
zip string 5 Optional Billing address 5-digit postal code 95030
shipping_street_address_1 string 1-255 Optional Shipping address first line (street address) 59 N Santa Cruz Avenue
shipping_street_address_2 string 1-255 Optional Shipping address second line (suite, apt, etc) Suite M
shipping_city string 1-255 Optional Shipping address city Los Gatos
shipping_state string 2 Optional Shipping address state abbreviation, ISO 3166-2 format. CA
shipping_country string 2 Optional Shipping address country abbreviation, in ISO 3166-1 alpha-2 format. US
shipping_zip string 5 Optional Shipping address 5-digit postal code 95030
processor_id uuid 36 Optional[2] The processor ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
ip_address string 12 Required Customer’s IP address 192.168.108.105

[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.

Parameter Type Length Description Example
transaction.id uuid 36 This transaction’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.merchant_id uuid 36 The user’s merchant ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.user_id uuid 36 The user’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.processor_id uuid 36 The processor’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.merchant_transaction_id string 1-255 The merchant assigned identifier my-order-id-0001
transaction.updated_at datetime - Last time this transaction was updated, on ISO 8601 UTC 2018-02-16T16:33:40+00:00
transaction.created_at datetime - Time that transaction was created, on ISO 8601 UTC 2018-02-16T16:33:40+00:00
transaction.events.*.id uuid 36 This event’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.events.*.success boolean - If the event was a successful event or not true
transaction.events.*.event_type string 4-10 The type of event being performed auth, capture, sale, void, refund
transaction.events.*.amount number 0.01-9999999 Total event amount 3.56
transaction.events.*.processor_code string 2-10 The processor response code 00
transaction.events.*.processor_message string 1-255 A human readable message from the processor APPROVAL V12341
transaction.events.*.processor_transaction_id string 1-255 A processor assigned identifier 00000000143242
transaction.events.*.updated_at datetime - Last time this event was updated, on ISO 8601 UTC 2018-02-16T16:33:40+00:00
transaction.events.*.created_at datetime - Time that event was created, on ISO 8601 UTC 2018-02-16T16:33:40+00:00

PS: All fields that are included on the authorization message are also echoed back.

curl --request POST \
  --url https://gateway-api.paycertify.com/api/transactions/auth \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --form 'amount=1.00' \
  --form 'card_number=4111111111111111' \
  --form 'card_expiry_month=12' \
  --form 'card_expiry_year=2020' \
  --form 'card_cvv=999' \
  --form 'first_name=John' \
  --form 'last_name=Doe' \
  --form 'street_address_1=59 N Santa Cruz Avenue' \
  --form 'street_address_2=Suite M' \
  --form 'city=Los Gatos' \
  --form 'state=CA' \
  --form 'country=US' \
  --form 'ip_address=127.0.0.1' \
  --form 'dynamic_descripton=MY-DESCRIPTOR' \
  --form 'mobile_phone=+11231231234' \
  --form 'email=support@paycertify.com' \
  --form 'merchant_transaction_id=my-order-id-0001' \
  --form 'zip=95030'

Responds with:

{
  "transaction": {
    "id": "3410596f-d596-42d4-9811-41d43868e984",
    "merchant_id": "455a1c64-385b-41b2-a56f-34bf6c5c5335",
    "user_id": "6e064bf5-0e18-466b-811b-f967e8d73b9f",
    "processor_id": "30ff7682-6ec7-48f3-8d7a-62319a9c3c59",
    "merchant_transaction_id": "my-order-id-0001",
    "card_number": "411111******1111",
    "card_brand": "visa",
    "card_expiry_month": "12",
    "card_expiry_year": "2020",
    "first_name": "John",
    "last_name": "Doe",
    "street_address_1": "59 N Santa Cruz Avenue",
    "street_address_2": "Suite M",
    "city": "Los Gatos",
    "state": "CA",
    "country": "US",
    "zip": "95030",
    "email": "support@paycertify.com",
    "mobile_phone": "+11231231234",
    "updated_at": "2018-02-16T16:33:40+00:00",
    "created_at": "2018-02-16T16:33:39+00:00",
    "events": [
        {
            "id": "84a8ab86-ee0e-47d4-8686-4e42fa58355e",
            "success": true,
            "threeds_response": null,
            "avs_response": null,
            "event_type": "auth",
            "amount": "1.00",
            "ip_address": "127.0.0.1",
            "processor_code": "00",
            "processor_message": "APPROVAL TAS656 ",
            "processor_transaction_id": "000000000252616",
            "processor_threeds_response": null,
            "processor_avs_response": "0",
            "updated_at": "2018-02-16T16:33:40+00:00",
            "created_at": "2018-02-16T16:33:39+00:00"
        }
    ]
  }
}

POST https://gateway-api.paycertify.com/api/transactions/{transaction_id}/capture

After running the auth transaction event, you should be able to capture the funds. Use the transaction ID sent back on the response to capture the desired amount.

Parameter Type Length Presence Description Example
amount number 0.01-9999999 Required Total transaction amount 3.56
Parameter Type Length Description Example
transaction.id uuid 36 This transaction’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.merchant_id uuid 36 The user’s merchant ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.user_id uuid 36 The user’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.processor_id uuid 36 The processor’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.merchant_transaction_id string 1-255 The merchant assigned identifier my-order-id-0001
transaction.updated_at datetime - Last time this transaction was updated, on ISO 8601 UTC 2018-02-16T16:33:40+00:00
transaction.created_at datetime - Time that transaction was created, on ISO 8601 UTC 2018-02-16T16:33:40+00:00
transaction.events.*.id uuid 36 This event’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.events.*.success boolean - If the event was a successful event or not true
transaction.events.*.event_type string 4-10 The type of event being performed auth, capture, sale, void, refund
transaction.events.*.amount number 0.01-9999999 Total event amount 3.56
transaction.events.*.processor_code string 2-10 The processor response code 00
transaction.events.*.processor_message string 1-255 A human readable message from the processor APPROVAL V12341
transaction.events.*.processor_transaction_id string 1-255 A processor assigned identifier 00000000143242
transaction.events.*.updated_at datetime - Last time this event was updated, on ISO 8601 UTC 2018-02-16T16:33:40+00:00
transaction.events.*.created_at datetime - Time that event was created, on ISO 8601 UTC 2018-02-16T16:33:40+00:00
curl --request POST \
  --url https://gateway-api.paycertify.com/api/transactions/{transaction_id}/capture \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --form 'amount=0.50'

Responds with:

{
  "transaction": {
    "id": "3410596f-d596-42d4-9811-41d43868e984",
    "merchant_id": "455a1c64-385b-41b2-a56f-34bf6c5c5335",
    "user_id": "6e064bf5-0e18-466b-811b-f967e8d73b9f",
    "processor_id": "30ff7682-6ec7-48f3-8d7a-62319a9c3c59",
    "merchant_transaction_id": "my-order-id-0001",
    "card_number": "411111******1111",
    "card_brand": "visa",
    "card_expiry_month": "12",
    "card_expiry_year": "2020",
    "first_name": "John",
    "last_name": "Doe",
    "street_address_1": "59 N Santa Cruz Avenue",
    "street_address_2": "Suite M",
    "city": "Los Gatos",
    "state": "CA",
    "country": "US",
    "zip": "95030",
    "email": "support@paycertify.com",
    "mobile_phone": "+11231231234",
    "updated_at": "2018-02-16T16:33:40+00:00",
    "created_at": "2018-02-16T16:33:39+00:00",
    "events": [
      {
            "id": "84a8ab86-ee0e-47d4-8686-4e42fa58355e",
            "success": true,
            "threeds_response": null,
            "avs_response": null,
            "event_type": "capture",
            "amount": "0.50",
            "ip_address": "127.0.0.1",
            "processor_code": "00",
            "processor_message": "APPROVAL TAS123 ",
            "processor_transaction_id": "000000000252618",
            "processor_threeds_response": null,
            "processor_avs_response": "0",
            "updated_at": "2018-02-16T16:35:40+00:00",
            "created_at": "2018-02-16T16:35:39+00:00"
        }
        {
            "id": "84a8ab86-ee0e-47d4-8686-4e42fa58355e",
            "success": true,
            "threeds_response": null,
            "avs_response": null,
            "event_type": "auth",
            "amount": "1.00",
            "ip_address": "127.0.0.1",
            "processor_code": "00",
            "processor_message": "APPROVAL TAS656 ",
            "processor_transaction_id": "000000000252616",
            "processor_threeds_response": null,
            "processor_avs_response": "0",
            "updated_at": "2018-02-16T16:33:40+00:00",
            "created_at": "2018-02-16T16:33:39+00:00"
        }
    ]
  }
}

Voiding a Transaction

POST https://gateway-api.paycertify.com/api/transactions/{transaction_id}/void

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.

Parameter Type Length Presence Description Example
amount number 0.01-9999999 Required Total transaction amount 3.56
Parameter Type Length Description Example
transaction.id uuid 36 This transaction’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.merchant_id uuid 36 The user’s merchant ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.user_id uuid 36 The user’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.processor_id uuid 36 The processor’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.merchant_transaction_id string 1-255 The merchant assigned identifier my-order-id-0001
transaction.updated_at datetime - Last time this transaction was updated, on ISO 8601 UTC 2018-02-16T16:33:40+00:00
transaction.created_at datetime - Time that transaction was created, on ISO 8601 UTC 2018-02-16T16:33:40+00:00
transaction.events.*.id uuid 36 This event’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.events.*.success boolean - If the event was a successful event or not true
transaction.events.*.event_type string 4-10 The type of event being performed auth, capture, sale, void, refund
transaction.events.*.amount number 0.01-9999999 Total event amount 3.56
transaction.events.*.processor_code string 2-10 The processor response code 00
transaction.events.*.processor_message string 1-255 A human readable message from the processor APPROVAL V12341
transaction.events.*.processor_transaction_id string 1-255 A processor assigned identifier 00000000143242
transaction.events.*.updated_at datetime - Last time this event was updated, on ISO 8601 UTC 2018-02-16T16:33:40+00:00
transaction.events.*.created_at datetime - Time that event was created, on ISO 8601 UTC 2018-02-16T16:33:40+00:00
curl --request POST \
  --url https://gateway-api.paycertify.com/api/transactions/{transaction_id}/void \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --form 'amount=0.50'

Responds with:

{
  "transaction": {
    "id": "3410596f-d596-42d4-9811-41d43868e984",
    "merchant_id": "455a1c64-385b-41b2-a56f-34bf6c5c5335",
    "user_id": "6e064bf5-0e18-466b-811b-f967e8d73b9f",
    "processor_id": "30ff7682-6ec7-48f3-8d7a-62319a9c3c59",
    "merchant_transaction_id": "my-order-id-0001",
    "card_number": "411111******1111",
    "card_brand": "visa",
    "card_expiry_month": "12",
    "card_expiry_year": "2020",
    "first_name": "John",
    "last_name": "Doe",
    "street_address_1": "59 N Santa Cruz Avenue",
    "street_address_2": "Suite M",
    "city": "Los Gatos",
    "state": "CA",
    "country": "US",
    "zip": "95030",
    "email": "support@paycertify.com",
    "mobile_phone": "+11231231234",
    "updated_at": "2018-02-16T16:33:40+00:00",
    "created_at": "2018-02-16T16:33:39+00:00",
    "events": [
      {
            "id": "84a8ab86-ee0e-47d4-8686-4e42fa58355e",
            "success": true,
            "threeds_response": null,
            "avs_response": null,
            "event_type": "void",
            "amount": "0.50",
            "ip_address": "127.0.0.1",
            "processor_code": "00",
            "processor_message": "APPROVAL TAS123 ",
            "processor_transaction_id": "000000000252618",
            "processor_threeds_response": null,
            "processor_avs_response": "0",
            "updated_at": "2018-02-16T16:35:40+00:00",
            "created_at": "2018-02-16T16:35:39+00:00"
        }
        {
            "id": "84a8ab86-ee0e-47d4-8686-4e42fa58355e",
            "success": true,
            "threeds_response": null,
            "avs_response": null,
            "event_type": "auth",
            "amount": "1.00",
            "ip_address": "127.0.0.1",
            "processor_code": "00",
            "processor_message": "APPROVAL TAS656 ",
            "processor_transaction_id": "000000000252616",
            "processor_threeds_response": null,
            "processor_avs_response": "0",
            "updated_at": "2018-02-16T16:33:40+00:00",
            "created_at": "2018-02-16T16:33:39+00:00"
        }
    ]
  }
}

Refunding a Transaction

POST https://gateway-api.paycertify.com/api/transactions/{transaction_id}/refund

A refund should be ran when running a reversal for a transaction that has a capture or sale event. A refund flags the transaction to be sent for settlement and returns the funds to the customer.

Parameter Type Length Presence Description Example
amount number 0.01-9999999 Required Total transaction amount 3.56
Parameter Type Length Description Example
transaction.id uuid 36 This transaction’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.merchant_id uuid 36 The user’s merchant ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.user_id uuid 36 The user’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.processor_id uuid 36 The processor’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.merchant_transaction_id string 1-255 The merchant assigned identifier my-order-id-0001
transaction.updated_at datetime - Last time this transaction was updated, on ISO 8601 UTC 2018-02-16T16:33:40+00:00
transaction.created_at datetime - Time that transaction was created, on ISO 8601 UTC 2018-02-16T16:33:40+00:00
transaction.events.*.id uuid 36 This event’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.events.*.success boolean - If the event was a successful event or not true
transaction.events.*.event_type string 4-10 The type of event being performed auth, capture, sale, void, refund
transaction.events.*.amount number 0.01-9999999 Total event amount 3.56
transaction.events.*.processor_code string 2-10 The processor response code 00
transaction.events.*.processor_message string 1-255 A human readable message from the processor APPROVAL V12341
transaction.events.*.processor_transaction_id string 1-255 A processor assigned identifier 00000000143242
transaction.events.*.updated_at datetime - Last time this event was updated, on ISO 8601 UTC 2018-02-16T16:33:40+00:00
transaction.events.*.created_at datetime - Time that event was created, on ISO 8601 UTC 2018-02-16T16:33:40+00:00
curl --request POST \
  --url https://gateway-api.paycertify.com/api/transactions/{transaction_id}/refund \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --form 'amount=0.50'

Responds with:

{
  "transaction": {
    "id": "3410596f-d596-42d4-9811-41d43868e984",
    "merchant_id": "455a1c64-385b-41b2-a56f-34bf6c5c5335",
    "user_id": "6e064bf5-0e18-466b-811b-f967e8d73b9f",
    "processor_id": "30ff7682-6ec7-48f3-8d7a-62319a9c3c59",
    "merchant_transaction_id": "my-order-id-0001",
    "card_number": "411111******1111",
    "card_brand": "visa",
    "card_expiry_month": "12",
    "card_expiry_year": "2020",
    "first_name": "John",
    "last_name": "Doe",
    "street_address_1": "59 N Santa Cruz Avenue",
    "street_address_2": "Suite M",
    "city": "Los Gatos",
    "state": "CA",
    "country": "US",
    "zip": "95030",
    "email": "support@paycertify.com",
    "mobile_phone": "+11231231234",
    "updated_at": "2018-02-16T16:33:40+00:00",
    "created_at": "2018-02-16T16:33:39+00:00",
    "events": [
      {
            "id": "84a8ab86-ee0e-47d4-8686-4e42fa58355e",
            "success": true,
            "threeds_response": null,
            "avs_response": null,
            "event_type": "refund",
            "amount": "0.50",
            "ip_address": "127.0.0.1",
            "processor_code": "00",
            "processor_message": "APPROVAL TAS123 ",
            "processor_transaction_id": "000000000252618",
            "processor_threeds_response": null,
            "processor_avs_response": "0",
            "updated_at": "2018-02-16T16:35:40+00:00",
            "created_at": "2018-02-16T16:35:39+00:00"
        }
        {
            "id": "84a8ab86-ee0e-47d4-8686-4e42fa58355e",
            "success": true,
            "threeds_response": null,
            "avs_response": null,
            "event_type": "sale",
            "amount": "1.00",
            "ip_address": "127.0.0.1",
            "processor_code": "00",
            "processor_message": "APPROVAL TAS656 ",
            "processor_transaction_id": "000000000252616",
            "processor_threeds_response": null,
            "processor_avs_response": "0",
            "updated_at": "2018-02-16T16:33:40+00:00",
            "created_at": "2018-02-16T16:33:39+00:00"
        }
    ]
  }
}

Passing 3D Secure Data

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

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).

Parameter Type Length Presence Description Example
threeds_enabled boolean - Required (for 3DS) Flag to enable 3DS capabilities true
threeds_xid string 1-255 Required (for 3DS) Base-64 encoded Transaction ID MDAwMDAwMDAwMDEyMzQ2Njc4OTA=
threeds_eci string 2 Required (for 3DS) Electronic commerce indicator. 05
threeds_cavv string 1-255 Required (for 3DS) Cardholder authentication verification value. jI3JBkkaQ1p8CBAAABy0CHUAAAA=
threeds_status string 1 Required (for 3DS) Result of 3DS request. Y, N, A, U
Parameter Type Length Description Example
transaction.id uuid 36 This transaction’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.merchant_id uuid 36 The user’s merchant ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.user_id uuid 36 The user’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.processor_id uuid 36 The processor’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.merchant_transaction_id string 1-255 The merchant assigned identifier my-order-id-0001
transaction.updated_at datetime - Last time this transaction was updated, on ISO 8601 UTC 2018-02-16T16:33:40+00:00
transaction.created_at datetime - Time that transaction was created, on ISO 8601 UTC 2018-02-16T16:33:40+00:00
transaction.events.*.id uuid 36 This event’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.events.*.success boolean - If the event was a successful event or not true
transaction.events.*.event_type string 4-10 The type of event being performed auth, capture, sale, void, refund
transaction.events.*.amount number 0.01-9999999 Total event amount 3.56
transaction.events.*.processor_code string 2-10 The processor response code 00
transaction.events.*.processor_message string 1-255 A human readable message from the processor APPROVAL V12341
transaction.events.*.processor_transaction_id string 1-255 A processor assigned identifier 00000000143242
transaction.events.*.updated_at datetime - Last time this event was updated, on ISO 8601 UTC 2018-02-16T16:33:40+00:00
transaction.events.*.created_at datetime - Time that event was created, on ISO 8601 UTC 2018-02-16T16:33:40+00:00
curl --request POST \
  --url https://gateway-api.paycertify.com/api/transactions/{transaction_id}/void \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --form 'amount=1.00' \
  --form 'card_number=4111111111111111' \
  --form 'card_expiry_month=12' \
  --form 'card_expiry_year=2020' \
  --form 'card_cvv=999' \
  --form 'first_name=John' \
  --form 'last_name=Doe' \
  --form 'street_address_1=59 N Santa Cruz Avenue' \
  --form 'street_address_2=Suite M' \
  --form 'city=Los Gatos' \
  --form 'state=CA' \
  --form 'country=US' \
  --form 'ip_address=127.0.0.1' \
  --form 'dynamic_descripton=MY-DESCRIPTOR' \
  --form 'mobile_phone=+11231231234' \
  --form 'email=support@paycertify.com' \
  --form 'merchant_transaction_id=my-order-id-0001' \
  --form 'zip=95030'
  --form 'threeds_enabled=1' \
  --form 'threeds_xid=MDAwMDAwMDAwMDEyMzQ2Njc4OTA=' \
  --form 'threeds_eci=05' \
  --form 'threeds_cavv=jI3JBkkaQ1p8CBAAABy0CHUAAAA=' \
  --form 'threeds_cavv_algorithm=3' \
  --form 'threeds_status=Y' \
  --form 'threeds_pares=eJzVWFmvo0iyfu9f0ep5tL...[REDACTED]...6P97r/hNAOzNG'

Responds with:

{
  "transaction": {
    "id": "3410596f-d596-42d4-9811-41d43868e984",
    "merchant_id": "455a1c64-385b-41b2-a56f-34bf6c5c5335",
    "user_id": "6e064bf5-0e18-466b-811b-f967e8d73b9f",
    "processor_id": "30ff7682-6ec7-48f3-8d7a-62319a9c3c59",
    "merchant_transaction_id": "my-order-id-0001",
    "card_number": "411111******1111",
    "card_brand": "visa",
    "card_expiry_month": "12",
    "card_expiry_year": "2020",
    "first_name": "John",
    "last_name": "Doe",
    "street_address_1": "59 N Santa Cruz Avenue",
    "street_address_2": "Suite M",
    "city": "Los Gatos",
    "state": "CA",
    "country": "US",
    "zip": "95030",
    "email": "support@paycertify.com",
    "mobile_phone": "+11231231234",
    "updated_at": "2018-02-16T16:33:40+00:00",
    "created_at": "2018-02-16T16:33:39+00:00",
    "events": [
        {
            "id": "84a8ab86-ee0e-47d4-8686-4e42fa58355e",
            "success": true,
            "threeds_response": "attempted",
            "avs_response": null,
            "event_type": "auth",
            "amount": "1.00",
            "ip_address": "127.0.0.1",
            "processor_code": "00",
            "processor_message": "APPROVAL TAS656 ",
            "processor_transaction_id": "000000000252616",
            "processor_threeds_response": "4",
            "processor_avs_response": "0",
            "updated_at": "2018-02-16T16:33:40+00:00",
            "created_at": "2018-02-16T16:33:39+00:00"
        }
    ]
  }
}

Address Verification

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

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.

Parameter Type Length Presence Description Example
avs_enabled number 0-1 Required (for AVS) Flag to enable AVS capabilities (1 for enabled / 0 for not enabled) 1
street_address_1 string 1-255 Required (for AVS) Billing address first line (street address) 59 N Santa Cruz Avenue
street_address_2 string 1-255 Required (for AVS) Billing address second line (suite, apt, etc) Suite M
city string 1-255 Required (for AVS) Billing address city Los Gatos
state string 2 Required (for AVS) Billing address state abbreviation, ISO 3166-2 format. CA
country string 2 Required (for AVS) Billing address country abbreviation, ISO 3166-1 alpha-2 format. US
zip string 5 Required (for AVS) Billing address 5-digit postal code 95030
Parameter Type Length Description Example
transaction.id uuid 36 This transaction’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.merchant_id uuid 36 The user’s merchant ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.user_id uuid 36 The user’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.processor_id uuid 36 The processor’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.merchant_transaction_id string 1-255 The merchant assigned identifier my-order-id-0001
transaction.updated_at datetime - Last time this transaction was updated, on ISO 8601 UTC 2018-02-16T16:33:40+00:00
transaction.created_at datetime - Time that transaction was created, on ISO 8601 UTC 2018-02-16T16:33:40+00:00
transaction.events.*.id uuid 36 This event’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.events.*.success boolean - If the event was a successful event or not true
transaction.events.*.event_type string 4-10 The type of event being performed auth, capture, sale, void, refund
transaction.events.*.amount number 0.01-9999999 Total event amount 3.56
transaction.events.*.processor_code string 2-10 The processor response code 00
transaction.events.*.processor_message string 1-255 A human readable message from the processor APPROVAL V12341
transaction.events.*.processor_transaction_id string 1-255 A processor assigned identifier 00000000143242
transaction.events.*.updated_at datetime - Last time this event was updated, on ISO 8601 UTC 2018-02-16T16:33:40+00:00
transaction.events.*.created_at datetime - Time that event was created, on ISO 8601 UTC 2018-02-16T16:33:40+00:00
curl --request POST \
  --url https://gateway-api.paycertify.com/api/transactions/{transaction_id}/void \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --form 'amount=1.00' \
  --form 'card_number=4111111111111111' \
  --form 'card_expiry_month=12' \
  --form 'card_expiry_year=2020' \
  --form 'card_cvv=999' \
  --form 'first_name=John' \
  --form 'last_name=Doe' \
  --form 'street_address_1=59 N Santa Cruz Avenue' \
  --form 'street_address_2=Suite M' \
  --form 'city=Los Gatos' \
  --form 'state=CA' \
  --form 'country=US' \
  --form 'ip_address=127.0.0.1' \
  --form 'dynamic_descripton=MY-DESCRIPTOR' \
  --form 'mobile_phone=+11231231234' \
  --form 'email=support@paycertify.com' \
  --form 'merchant_transaction_id=my-order-id-0001' \
  --form 'zip=95030'
  --form 'avs_enabled=1'

Responds with:

{
  "transaction": {
    "id": "3410596f-d596-42d4-9811-41d43868e984",
    "merchant_id": "455a1c64-385b-41b2-a56f-34bf6c5c5335",
    "user_id": "6e064bf5-0e18-466b-811b-f967e8d73b9f",
    "processor_id": "30ff7682-6ec7-48f3-8d7a-62319a9c3c59",
    "merchant_transaction_id": "my-order-id-0001",
    "card_number": "411111******1111",
    "card_brand": "visa",
    "card_expiry_month": "12",
    "card_expiry_year": "2020",
    "first_name": "John",
    "last_name": "Doe",
    "street_address_1": "59 N Santa Cruz Avenue",
    "street_address_2": "Suite M",
    "city": "Los Gatos",
    "state": "CA",
    "country": "US",
    "zip": "95030",
    "email": "support@paycertify.com",
    "mobile_phone": "+11231231234",
    "updated_at": "2018-02-16T16:33:40+00:00",
    "created_at": "2018-02-16T16:33:39+00:00",
    "events": [
        {
            "id": "84a8ab86-ee0e-47d4-8686-4e42fa58355e",
            "success": true,
            "threeds_response": null,
            "avs_response": "exact_match",
            "event_type": "auth",
            "amount": "1.00",
            "ip_address": "127.0.0.1",
            "processor_code": "00",
            "processor_message": "EXACT MATCH  ",
            "processor_transaction_id": "000000000252616",
            "processor_threeds_response": null,
            "processor_avs_response": "Z",
            "updated_at": "2018-02-16T16:33:40+00:00",
            "created_at": "2018-02-16T16:33:39+00:00"
        }
    ]
  }
}

Airline & Travel Data

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

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.

Parameter Type Length Presence Description Example
amount[1] number 0.01-9999999 Required Total transaction amount 3.50
passenger_transport.*.ticket_number number 1-13 Required (for A&TD) The ticket number for this passenger AAL1234567890
passenger_transport.*.ticket_issuing_carrier_name[2] string 1-25 Required (for A&TD) The name of carrier that generated the tickets for airline travel American Airlines
passenger_transport.*.ticket_issuing_carrier_code[2] string 2 Required (for A&TD) The IATA code for the carrier that issued the ticket AA
passenger_transport.*.ticket_issuing_city[3] string 1-18 Required (for A&TD) The city where the ticket has been issued Los Gatos
passenger_transport.*.ticket_issuing_date[4] string 10 Required (for A&TD) The date the ticket was issued in Y-m-d format, with trailing zeros 2025-05-01
(May 1st 2025)
passenger_transport.*.passenger_name string 1-20 Required (for A&TD) Passenger’s name John Doe
passenger_transport.*.restricted_ticket_indicator boolean - Required (for A&TD) If the ticket can be refundable or not. Defaults to false false
passenger_transport.*.legs.*.carrier_code string 2 Required (for A&TD) The carrier’s IATA code for the leg AA
passenger_transport.*.legs.*.service_class string 1 Required (for A&TD) The service class for the leg F
passenger_transport.*.legs.*.departure_airport string 3 Required (for A&TD) The departure airport’s IATA code SFO
passenger_transport.*.legs.*.destination_airport string 3 Required (for A&TD) The destination airport’s IATA code LAX
passenger_transport.*.legs.*.departure_date string 10 Required (for A&TD) The departure date in Y-m-d format, with trailing zeros 2025-05-01
(May 1st 2025)
passenger_transport.*.legs.*.flight_number[4] string 4 Optional The flight number for the leg 1234
passenger_transport.*.legs.*.fare_basis string 1-15 Required The fare basis for the leg VLW4MQC1
passenger_transport.*.legs.*.fare[1] number 0.01-9999999 Required The total fare for the leg 1.50

[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.

Parameter Type Length Description Example
transaction.id uuid 36 This transaction’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.merchant_id uuid 36 The user’s merchant ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.user_id uuid 36 The user’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.processor_id uuid 36 The processor’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.merchant_transaction_id string 1-255 The merchant assigned identifier my-order-id-0001
transaction.updated_at datetime - Last time this transaction was updated, on ISO 8601 UTC 2018-02-16T16:33:40+00:00
transaction.created_at datetime - Time that transaction was created, on ISO 8601 UTC 2018-02-16T16:33:40+00:00
transaction.events.*.id uuid 36 This event’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.events.*.success boolean - If the event was a successful event or not true
transaction.events.*.event_type string 4-10 The type of event being performed auth, capture, sale, void, refund
transaction.events.*.amount number 0.01-9999999 Total event amount 3.56
transaction.events.*.processor_code string 2-10 The processor response code 00
transaction.events.*.processor_message string 1-255 A human readable message from the processor APPROVAL V12341
transaction.events.*.processor_transaction_id string 1-255 A processor assigned identifier 00000000143242
transaction.events.*.updated_at datetime - Last time this event was updated, on ISO 8601 UTC 2018-02-16T16:33:40+00:00
transaction.events.*.created_at datetime - Time that event was created, on ISO 8601 UTC 2018-02-16T16:33:40+00:00

PS: All fields that are included on the authorization message are also echoed back.

curl --request POST \
  --url https://gateway-api.paycertify.com/api/transactions/auth \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --form 'amount=100' \
  --form 'card_number=4111111111111111' \
  --form 'card_expiry_month=01' \
  --form 'card_expiry_year=2021' \
  --form 'card_cvv=999' \
  --form 'merchant_transaction_id=W1F3D4' \
  --form 'passenger_transport[0][ticket_number]=AAL1231231231' \
  --form 'passenger_transport[0][ticket_issuing_carrier_name]=American Airlines' \
  --form 'passenger_transport[0][ticket_issuing_carrier_code]=AA' \
  --form 'passenger_transport[0][ticket_issuing_city]=Los Angeles' \
  --form 'passenger_transport[0][ticket_issuing_date]=2018-01-01' \
  --form 'passenger_transport[0][passenger_name]=Mary Doe' \
  --form 'passenger_transport[0][legs][0][carrier_code]=AA' \
  --form 'passenger_transport[0][legs][0][service_class]=F' \
  --form 'passenger_transport[0][legs][0][departure_airport]=LAX' \
  --form 'passenger_transport[0][legs][0][destination_airport]=SFO' \
  --form 'passenger_transport[0][legs][0][flight_number]=1234' \
  --form 'passenger_transport[0][legs][0][fare_basis]=Y' \
  --form 'passenger_transport[0][legs][0][fare]=10.00' \
  --form 'passenger_transport[0][legs][0][departure_date]=2018-01-30' \
  --form 'passenger_transport[0][legs][1][carrier_code]=DL' \
  --form 'passenger_transport[0][legs][1][service_class]=F' \
  --form 'passenger_transport[0][legs][1][departure_airport]=SFO' \
  --form 'passenger_transport[0][legs][1][destination_airport]=EWR' \
  --form 'passenger_transport[0][legs][1][flight_number]=2345' \
  --form 'passenger_transport[0][legs][1][fare_basis]=J' \
  --form 'passenger_transport[0][legs][1][fare]=20.00' \
  --form 'passenger_transport[0][legs][1][departure_date]=2018-01-30' \
  --form 'passenger_transport[1][ticket_number]=AAL1212123434' \
  --form 'passenger_transport[1][ticket_issuing_carrier_name]=American Airlines' \
  --form 'passenger_transport[1][ticket_issuing_carrier_code]=AA' \
  --form 'passenger_transport[1][ticket_issuing_city]=Los Angeles' \
  --form 'passenger_transport[1][ticket_issuing_date]=2018-01-06' \
  --form 'passenger_transport[1][passenger_name]=John Doe' \
  --form 'passenger_transport[1][legs][0][service_class]=F' \
  --form 'passenger_transport[1][legs][0][departure_airport]=LAX' \
  --form 'passenger_transport[1][legs][0][destination_airport]=SFO' \
  --form 'passenger_transport[1][legs][0][flight_number]=1234' \
  --form 'passenger_transport[1][legs][0][fare_basis]=Y' \
  --form 'passenger_transport[1][legs][0][fare]=30.00' \
  --form 'passenger_transport[1][legs][0][departure_date]=2018-01-30' \
  --form 'passenger_transport[1][legs][1][carrier_code]=DL' \
  --form 'passenger_transport[1][legs][1][service_class]=F' \
  --form 'passenger_transport[1][legs][1][departure_airport]=SFO' \
  --form 'passenger_transport[1][legs][1][destination_airport]=EWR' \
  --form 'passenger_transport[1][legs][1][flight_number]=2345' \
  --form 'passenger_transport[1][legs][1][fare_basis]=J' \
  --form 'passenger_transport[1][legs][0][carrier_code]=AA' \
  --form 'passenger_transport[1][legs][1][departure_date]=2018-01-30' \
  --form 'passenger_transport[1][legs][1][fare]=40.00'

Responds with:

{
  "transaction": {
    "id": "14d5c6ac-856c-47aa-b39e-e44b815ff3a6",
    "merchant_id": "455a1c64-385b-41b2-a56f-34bf6c5c5335",
    "user_id": "6e064bf5-0e18-466b-811b-f967e8d73b9f",
    "processor_id": "1f7e5551-bddb-4c72-ab33-818a1860e69a",
    "merchant_transaction_id": "W1F3D4",
    "card_number": "401200******5439",
    "card_brand": "visa",
    "card_expiry_month": "12",
    "card_expiry_year": "2020",
    "updated_at": "2018-02-19T02:22:14+00:00",
    "created_at": "2018-02-19T02:22:12+00:00",
    "events": [
        {
            "id": "ddff299c-c6d4-4917-864c-bea03a52eb1a",
            "success": true,
            "threeds_response": null,
            "avs_response": "exact_match",
            "event_type": "auth",
            "amount": "100.00",
            "ip_address": "127.0.0.1",
            "processor_code": "00",
            "processor_message": "EXACT MATCH     ",
            "processor_transaction_id": "000000000297324",
            "processor_threeds_response": null,
            "processor_avs_response": "Y",
            "updated_at": "2018-02-19T02:22:14+00:00",
            "created_at": "2018-02-19T02:22:12+00:00"
        }
    ],
    "passengers": [
        {
            "id": "88e057c7-3d95-428f-b7c2-183b46aab443",
            "passenger_name": "Mary Doe",
            "ticket_number": "AAL1231231231",
            "ticket_issuing_carrier_name": "American Airlines",
            "ticket_issuing_carrier_code": "AA",
            "ticket_issuing_city": "Los Angeles",
            "ticket_issuing_date": "2018-01-01",
            "restricted_ticket_indicator": false,
            "legs": [
                {
                    "carrier_code": "AA",
                    "service_class": "F",
                    "departure_airport": "LAX",
                    "destination_airport": "SFO",
                    "departure_date": "2018-01-30",
                    "flight_number": "1234",
                    "fare_basis": "Y",
                    "fare": "10.00"
                },
                {
                    "carrier_code": "DL",
                    "service_class": "F",
                    "departure_airport": "SFO",
                    "destination_airport": "EWR",
                    "departure_date": "2018-01-30",
                    "flight_number": "2345",
                    "fare_basis": "J",
                    "fare": "20.00"
                }
            ]
        },
        {
            "id": "35563a54-3c9f-4872-9735-4b6b1f99573f",
            "passenger_name": "John Doe",
            "ticket_number": "AAL1212123434",
            "ticket_issuing_carrier_name": "American Airlines",
            "ticket_issuing_carrier_code": "AA",
            "ticket_issuing_city": "Los Angeles",
            "ticket_issuing_date": "2018-01-06",
            "restricted_ticket_indicator": false,
            "legs": [
                {
                    "carrier_code": "AA",
                    "service_class": "F",
                    "departure_airport": "LAX",
                    "destination_airport": "SFO",
                    "departure_date": "2018-01-30",
                    "flight_number": "1234",
                    "fare_basis": "Y",
                    "fare": "30.00"
                },
                {
                    "carrier_code": "DL",
                    "service_class": "F",
                    "departure_airport": "SFO",
                    "destination_airport": "EWR",
                    "departure_date": "2018-01-30",
                    "flight_number": "2345",
                    "fare_basis": "J",
                    "fare": "40.00"
                }
            ]
        }
    ]
  }
}

Capture, void and refunds for Airline & Travel Data

POST https://gateway-api.paycertify.com/api/transactions/{transaction_id}/capture
POST https://gateway-api.paycertify.com/api/transactions/{transaction_id}/void
POST https://gateway-api.paycertify.com/api/transactions/{transaction_id}/refund

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.

Parameter Type Length Presence Description Example
amount number 0.01-9999999 Required Total transaction amount 3.50
passenger_transport.*.passenger_id uuid 36 Required (for A&TD) The Passenger ID 88e057c7-3d95-428f-b7c2-183b46aab443
passenger_transport.*.amount[1] uuid 36 Required (for A&TD) The event amount associated to this passenger 3.50

[1] The amount provided should match the sum of passenger_transport.*.amount records.

Parameter Type Length Description Example
id uuid 36 This transaction’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
merchant_id uuid 36 The user’s merchant ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
user_id uuid 36 The user’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
processor_id uuid 36 The processor’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
merchant_transaction_id string 1-255 The merchant assigned identifier my-order-id-0001
updated_at datetime - Last time this transaction was updated, on ISO 8601 UTC 2018-02-16T16:33:40+00:00
created_at datetime - Time that transaction was created, on ISO 8601 UTC 2018-02-16T16:33:40+00:00
events.*.id uuid 36 This event’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
events.*.success boolean - If the event was a successful event or not true
events.*.event_type string 4-10 The type of event being performed auth, capture, sale, void, refund
events.*.amount number 0.01-9999999 Total event amount 3.56
events.*.processor_code string 2-10 The processor response code 00
events.*.processor_message string 1-255 A human readable message from the processor APPROVAL V12341
events.*.processor_transaction_id string 1-255 A processor assigned identifier 00000000143242
events.*.updated_at datetime - Last time this event was updated, on ISO 8601 UTC 2018-02-16T16:33:40+00:00
events.*.created_at datetime - Time that event was created, on ISO 8601 UTC 2018-02-16T16:33:40+00:00
curl --request POST \
  --url https://gateway-api.paycertify.com/api/transactions/28c7cfcf-fa2a-49c6-8860-98515407b3c5/refund \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Cache-Control: no-cache' \
  --form 'amount=3' \
  --form 'passenger_transport[1][passenger_id]=9dfe59a6-2173-4778-9fbd-4ce2e8b6d9e3' \
  --form 'passenger_transport[1][amount]=0.50'

Responds with:

{
    "id": "3410596f-d596-42d4-9811-41d43868e984",
    "merchant_id": "455a1c64-385b-41b2-a56f-34bf6c5c5335",
    "user_id": "6e064bf5-0e18-466b-811b-f967e8d73b9f",
    "processor_id": "30ff7682-6ec7-48f3-8d7a-62319a9c3c59",
    "merchant_transaction_id": "my-order-id-0001",
    "card_number": "411111******1111",
    "card_brand": "visa",
    "card_expiry_month": "12",
    "card_expiry_year": "2020",
    "first_name": "John",
    "last_name": "Doe",
    "street_address_1": "59 N Santa Cruz Avenue",
    "street_address_2": "Suite M",
    "city": "Los Gatos",
    "state": "CA",
    "country": "US",
    "zip": "95030",
    "email": "support@paycertify.com",
    "mobile_phone": "+11231231234",
    "updated_at": "2018-02-16T16:33:40+00:00",
    "created_at": "2018-02-16T16:33:39+00:00",
    "events": [
      {
            "id": "84a8ab86-ee0e-47d4-8686-4e42fa58355e",
            "success": true,
            "threeds_response": null,
            "avs_response": null,
            "event_type": "void",
            "amount": "0.50",
            "ip_address": "127.0.0.1",
            "processor_code": "00",
            "processor_message": "APPROVAL TAS123 ",
            "processor_transaction_id": "000000000252618",
            "processor_threeds_response": null,
            "processor_avs_response": "0",
            "updated_at": "2018-02-16T16:35:40+00:00",
            "created_at": "2018-02-16T16:35:39+00:00"
        },
        {
            "id": "84a8ab86-ee0e-47d4-8686-4e42fa58355e",
            "success": true,
            "threeds_response": null,
            "avs_response": null,
            "event_type": "auth",
            "amount": "1.00",
            "ip_address": "127.0.0.1",
            "processor_code": "00",
            "processor_message": "APPROVAL TAS656 ",
            "processor_transaction_id": "000000000252616",
            "processor_threeds_response": null,
            "processor_avs_response": "0",
            "updated_at": "2018-02-16T16:33:40+00:00",
            "created_at": "2018-02-16T16:33:39+00:00"
        }
    ],
    "passengers": [
        {
            "id": "88e057c7-3d95-428f-b7c2-183b46aab443",
            "passenger_name": "Mary Doe",
            "ticket_number": "AAL1231231231",
            "ticket_issuing_carrier_name": "American Airlines",
            "ticket_issuing_carrier_code": "AA",
            "ticket_issuing_city": "Los Angeles",
            "ticket_issuing_date": "2018-01-01",
            "restricted_ticket_indicator": false,
            "legs": [
                {
                    "carrier_code": "AA",
                    "service_class": "F",
                    "departure_airport": "LAX",
                    "destination_airport": "SFO",
                    "departure_date": "2018-01-30",
                    "flight_number": "1234",
                    "fare_basis": "Y",
                    "fare": "10.00"
                },
                {
                    "carrier_code": "DL",
                    "service_class": "F",
                    "departure_airport": "SFO",
                    "destination_airport": "EWR",
                    "departure_date": "2018-01-30",
                    "flight_number": "2345",
                    "fare_basis": "J",
                    "fare": "20.00"
                }
            ]
        },
        {
            "id": "35563a54-3c9f-4872-9735-4b6b1f99573f",
            "passenger_name": "John Doe",
            "ticket_number": "AAL1212123434",
            "ticket_issuing_carrier_name": "American Airlines",
            "ticket_issuing_carrier_code": "AA",
            "ticket_issuing_city": "Los Angeles",
            "ticket_issuing_date": "2018-01-06",
            "restricted_ticket_indicator": false,
            "legs": [
                {
                    "carrier_code": "AA",
                    "service_class": "F",
                    "departure_airport": "LAX",
                    "destination_airport": "SFO",
                    "departure_date": "2018-01-30",
                    "flight_number": "1234",
                    "fare_basis": "Y",
                    "fare": "30.00"
                },
                {
                    "carrier_code": "DL",
                    "service_class": "F",
                    "departure_airport": "SFO",
                    "destination_airport": "EWR",
                    "departure_date": "2018-01-30",
                    "flight_number": "2345",
                    "fare_basis": "J",
                    "fare": "40.00"
                }
            ]
        }
    ]
}

Dynamic Descriptors

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

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.

Parameter Type Length Presence Description Example  
dynamic_descriptor string 1-38 Optional The credit card statement descriptor MYBUSINESSINC 123-1231234
Parameter Type Length Description Example
transaction.id uuid 36 This transaction’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.merchant_id uuid 36 The user’s merchant ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.user_id uuid 36 The user’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.processor_id uuid 36 The processor’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.merchant_transaction_id string 1-255 The merchant assigned identifier my-order-id-0001
transaction.updated_at datetime - Last time this transaction was updated, on ISO 8601 UTC 2018-02-16T16:33:40+00:00
transaction.created_at datetime - Time that transaction was created, on ISO 8601 UTC 2018-02-16T16:33:40+00:00
transaction.events.*.id uuid 36 This event’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.events.*.success boolean - If the event was a successful event or not true
transaction.events.*.event_type string 4-10 The type of event being performed auth, capture, sale, void, refund
transaction.events.*.amount number 0.01-9999999 Total event amount 3.56
transaction.events.*.processor_code string 2-10 The processor response code 00
transaction.events.*.processor_message string 1-255 A human readable message from the processor APPROVAL V12341
transaction.events.*.processor_transaction_id string 1-255 A processor assigned identifier 00000000143242
transaction.events.*.updated_at datetime - Last time this event was updated, on ISO 8601 UTC 2018-02-16T16:33:40+00:00
transaction.events.*.created_at datetime - Time that event was created, on ISO 8601 UTC 2018-02-16T16:33:40+00:00
curl --request POST \
  --url https://gateway-api.paycertify.com/api/transactions/auth \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --form 'amount=1.00' \
  --form 'card_number=4111111111111111' \
  --form 'card_expiry_month=12' \
  --form 'card_expiry_year=2020' \
  --form 'card_cvv=999' \
  --form 'first_name=John' \
  --form 'last_name=Doe' \
  --form 'street_address_1=59 N Santa Cruz Avenue' \
  --form 'street_address_2=Suite M' \
  --form 'city=Los Gatos' \
  --form 'state=CA' \
  --form 'country=US' \
  --form 'ip_address=127.0.0.1' \
  --form 'mobile_phone=+11231231234' \
  --form 'email=support@paycertify.com' \
  --form 'merchant_transaction_id=my-order-id-0001' \
  --form 'dynamic_descriptor=MYBUSINESSINC|123-1231234' \
  --form 'zip=95030'

Responds with:

{
  "transaction": {
    "id": "3410596f-d596-42d4-9811-41d43868e984",
    "merchant_id": "455a1c64-385b-41b2-a56f-34bf6c5c5335",
    "user_id": "6e064bf5-0e18-466b-811b-f967e8d73b9f",
    "processor_id": "30ff7682-6ec7-48f3-8d7a-62319a9c3c59",
    "merchant_transaction_id": "my-order-id-0001",
    "card_number": "411111******1111",
    "card_brand": "visa",
    "card_expiry_month": "12",
    "card_expiry_year": "2020",
    "first_name": "John",
    "last_name": "Doe",
    "street_address_1": "59 N Santa Cruz Avenue",
    "street_address_2": "Suite M",
    "city": "Los Gatos",
    "state": "CA",
    "country": "US",
    "zip": "95030",
    "email": "support@paycertify.com",
    "mobile_phone": "+11231231234",
    "updated_at": "2018-02-16T16:33:40+00:00",
    "created_at": "2018-02-16T16:33:39+00:00",
    "events": [
        {
            "id": "84a8ab86-ee0e-47d4-8686-4e42fa58355e",
            "success": true,
            "threeds_response": null,
            "avs_response": null,
            "event_type": "auth",
            "amount": "1.00",
            "ip_address": "127.0.0.1",
            "processor_code": "00",
            "processor_message": "APPROVAL TAS656 ",
            "processor_transaction_id": "000000000252616",
            "processor_threeds_response": null,
            "processor_avs_response": "0",
            "updated_at": "2018-02-16T16:33:40+00:00",
            "created_at": "2018-02-16T16:33:39+00:00"
        }
    ]
  }
}

Using Tokenization

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

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.

Parameter Type Length Presence Description Example
tokenization_enabled boolean 8-19 Required (for Tokenization) Flag to enable Tokenization true
card_token string 8-19 Required (for Tokenization) The token value of the tokenized credit card 4111098765431111
Parameter Type Length Description Example
transaction.id uuid 36 This transaction’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.merchant_id uuid 36 The user’s merchant ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.user_id uuid 36 The user’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.processor_id uuid 36 The processor’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.merchant_transaction_id string 1-255 The merchant assigned identifier my-order-id-0001
transaction.updated_at datetime - Last time this transaction was updated, on ISO 8601 UTC 2018-02-16T16:33:40+00:00
transaction.created_at datetime - Time that transaction was created, on ISO 8601 UTC 2018-02-16T16:33:40+00:00
transaction.events.*.id uuid 36 This event’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transaction.events.*.success boolean - If the event was a successful event or not true
transaction.events.*.event_type string 4-10 The type of event being performed auth, capture, sale, void, refund
transaction.events.*.amount number 0.01-9999999 Total event amount 3.56
transaction.events.*.processor_code string 2-10 The processor response code 00
transaction.events.*.processor_message string 1-255 A human readable message from the processor APPROVAL V12341
transaction.events.*.processor_transaction_id string 1-255 A processor assigned identifier 00000000143242
transaction.events.*.updated_at datetime - Last time this event was updated, on ISO 8601 UTC 2018-02-16T16:33:40+00:00
transaction.events.*.created_at datetime - Time that event was created, on ISO 8601 UTC 2018-02-16T16:33:40+00:00
curl --request POST \
  --url https://gateway-api.paycertify.com/api/transactions/auth \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --form 'amount=1.00' \
  --form 'card_token=4111098765431111' \
  --form 'tokenization_enabled=true' \
  --form 'first_name=John' \
  --form 'last_name=Doe' \
  --form 'street_address_1=59 N Santa Cruz Avenue' \
  --form 'street_address_2=Suite M' \
  --form 'city=Los Gatos' \
  --form 'state=CA' \
  --form 'country=US' \
  --form 'ip_address=127.0.0.1' \
  --form 'mobile_phone=+11231231234' \
  --form 'email=support@paycertify.com' \
  --form 'merchant_transaction_id=my-order-id-0001' \
  --form 'zip=95030'

Responds with:

{
  "transaction": {
    "id": "3410596f-d596-42d4-9811-41d43868e984",
    "merchant_id": "455a1c64-385b-41b2-a56f-34bf6c5c5335",
    "user_id": "6e064bf5-0e18-466b-811b-f967e8d73b9f",
    "processor_id": "30ff7682-6ec7-48f3-8d7a-62319a9c3c59",
    "merchant_transaction_id": "my-order-id-0001",
    "card_number": "411111******1111",
    "card_brand": "visa",
    "card_expiry_month": "12",
    "card_expiry_year": "2020",
    "first_name": "John",
    "last_name": "Doe",
    "street_address_1": "59 N Santa Cruz Avenue",
    "street_address_2": "Suite M",
    "city": "Los Gatos",
    "state": "CA",
    "country": "US",
    "zip": "95030",
    "email": "support@paycertify.com",
    "mobile_phone": "+11231231234",
    "updated_at": "2018-02-16T16:33:40+00:00",
    "created_at": "2018-02-16T16:33:39+00:00",
    "events": [
        {
            "id": "84a8ab86-ee0e-47d4-8686-4e42fa58355e",
            "success": true,
            "threeds_response": null,
            "avs_response": null,
            "event_type": "auth",
            "amount": "1.00",
            "ip_address": "127.0.0.1",
            "processor_code": "00",
            "processor_message": "APPROVAL TAS656 ",
            "processor_transaction_id": "000000000252616",
            "processor_threeds_response": null,
            "processor_avs_response": "0",
            "updated_at": "2018-02-16T16:33:40+00:00",
            "created_at": "2018-02-16T16:33:39+00:00"
        }
    ]
  }
}

Recurring Billing

The Payment Gateway allow merchants to receive recurring credit card payments using subscriptions.

Create a Subscription

POST https://gateway-api.paycertify.com/api/subscriptions

To create a subscription, you should define when and how much to charge your customer. To start billing, simply create a subscription and then the Gateway will handle the entire billing flow for you. The charging period should be defined by the interval and interval_count fields. Being interval the period of time to calculate the next charge and interval_count being the interval number that we should wait until the next charge. For example:

  • Charging every month: interval = month and interval_count = 1;
  • Charging every 3 weeks: interval = week and interval_count = 3.

Subscriptions should also receive the start_date and end_date fields, which means the start and end date of the subscription, respectively. The first charge will always occur on the start_date. The next payment cycles will be automatically calculated by the Gateway. The whole period until start_date will be considered as trial and you can charge your customer for this period filling the trial_amount field.

Parameter Type Length Presence Description Example
processor_id uuid 36 Optional[1] The Processor record ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
description string 1-255 Required A brief description of the current subscription Monthly tennis club signature
start_date string string Required The date and time when subscription should start Y-m-d h:m:s format. 2018-10-01 12:00:00
end_date string string Required The date and time when subscription should end Y-m-d h:m:s format. 2019-10-01 12:00:00
interval string 1-255 Required Time period measure you require (day, week, month) day
interval_count number 1-255 Required Number of interval between payments 10
amount number 0.01-9999999 Required Amount to be charged every recurring cycle 3.56
trial_amount number 0.01-9999999 Optional The amount charged on Subscription creating, used for paid trial periods. 3.56
card_number string 8-19 Required The credit card to charge 411111111111111
card_expiry_month string 2 Required The expiration month with two positions 12
card_expiry_year string 4 Required The expiration year with four positions 2025
card_cvv string 3-4 Required 3 or 4 digit card verification code 123
merchant_subscription_id string 1-255 Required A merchant assigned identifier (your subscription ID) my-subscription-id-0001
first_name string 1-255 Required Customer’s first name John
last_name string 1-255 Required Customer’s last name Doe
email string 1-255 Optional Customer’s email support@paycertify.com
mobile_phone string 11-15 Optional Customer’s phone in E.164 format +11231231234
street_address_1 string 1-255 Required Billing address first line (street address) 59 N Santa Cruz Avenue
street_address_2 string 1-255 Optional Billing address second line (suite, apt, etc) Suite M
city string 1-255 Required Billing address city Los Gatos
state string 2 Required Billing address state abbreviation, ISO 3166-2 format. CA
country string 2 Required Billing address country abbreviation, ISO 3166-1 alpha-2 format. US
zip string 5 Required Billing address 5-digit postal code 95030
shipping_street_address_1 string 1-255 Optional Shipping address first line (street address) 59 N Santa Cruz Avenue
shipping_street_address_2 string 1-255 Optional Shipping address second line (suite, apt, etc) Suite M
shipping_city string 1-255 Optional Shipping address city Los Gatos
shipping_state string 2 Optional Shipping address state abbreviation, ISO 3166-2 format. CA
shipping_country string 2 Optional Shipping address country abbreviation, in ISO 3166-1 alpha-2 format. US
shipping_zip string 5 Optional Shipping address 5-digit postal code 95030

[1] if processor_id has not been provided, the gateway will pick the record flagged as “default”.

Parameter Type Length Description Example
subscription.id uuid 36 The Subscription record ID e57aa3bf-a3df-4056-b1f2-d4de7252fe99
subscription.merchant_id uuid 36 The user’s merchant ID e57aa3bf-a3df-4056-b1f2-d4de7252fe99
subscription.user_id uuid 36 The user’s ID e57aa3bf-a3df-4056-b1f2-d4de7252fe99
subscription.status string 6-8 Result of Subscription request trialing
subscription.description string 1-255 A brief description of the current subscription Monthly tennis club signature
subscription.interval string 3-5 Time period measure you require (day, week, month) day
subscription.interval_count number - Number of interval between payments 1
subscription.processor_id uuid 36 The processor’s ID e57aa3bf-a3df-4056-b1f2-d4de7252fe99
subscription.merchant_subscription_id string 1-255 A merchant assigned identifier (your subscription ID) MY-ORDER
subscription.first_name string 1-255 Customer’s first name John
subscription.last_name string 1-255 Customer’s last name Doe
subscription.street_address_1 string 1-255 Billing address first line (street address) 59 N Santa Cruz Avenue
subscription.street_address_2 string 1-255 Billing address second line (suite, apt, etc) Suite M
subscription.city string 1-255 Billing address city Los Gatos
subscription.state string 2 Billing address state abbreviation, ISO 3166-2 format. CA
subscription.country string 2 Billing address country abbreviation, ISO 3166-1 alpha-2 format. US
subscription.zip string 5 Billing address 5-digit postal code 95030
subscription.email string 1-255 Customer’s email support@paycertify.com
subscription.mobile_phone string 11-15 Customer’s phone in E.164 format +11231231234
subscription.amount number 0.01-9999999 Amount to be charged every recurring cycle 3.56
subscription.trial_amount number 0.01-9999999 The amount charged on Subscription creating, used for paid trial periods. 3.56
subscription.start_date datetime 19 The date and time when subscription should start Y-m-d h:m:s format. 2018-10-01 12:00:00
subscription.end_date datetime 19 The date and time when subscription should end Y-m-d h:m:s format. 2019-10-01 12:00:00
subscription.next_cycle_date datetime 19 The date and time of the next charge Y-m-d h:m:s format. 2019-10-01 12:00:00
subscription.transactions array - Listing of Subscription related transactions -
subscription.updated_at datetime 19 Last time this event was updated, on ISO 8601 UTC 2018-02-16T16:33:40+00:00
subscription.created_at datetime 19 Time that event was created, on ISO 8601 UTC 2018-02-16T16:33:40+00:00
subscription.card_number string 8-19 Redacted card number 411111**1111
subscription.card_expiry_month string 2 The expiration month with two positions 12
subscription.card_expiry_year string 4 The expiration year with four positions 2020
curl --request POST \
  --url https://gateway-api.paycertify.com/api/subscriptions \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --form 'amount=1.00' \
  --form 'description=Monthly tennis club signature' \
  --form 'start_date=2018-09-07' \
  --form 'end_date=2018-10-07' \
  --form 'interval=day' \
  --form 'card_number=4111111111111111' \
  --form 'merchant_subscription_id=MY-ORDER' \
  --form 'interval_count=1' \
  --form 'card_expiry_month=12' \
  --form 'card_expiry_year=2020' \
  --form 'card_cvv=999' \
  --form 'first_name=John' \
  --form 'last_name=Doe' \
  --form 'street_address_1=59 N Santa Cruz Avenue' \
  --form 'street_address_2=Suite M' \
  --form 'city=Los Gatos' \
  --form 'state=CA' \
  --form 'country=US' \
  --form 'mobile_phone=+11231231234' \
  --form 'email=support@paycertify.com' \
  --form 'merchant_transaction_id=my-order-id-0001' \
  --form 'zip=95030'
{
    "subscription": {
        "id": "e57aa3bf-a3df-4056-b1f2-d4de7252fe99",
        "merchant_id": "c8444f15-887b-45bf-a143-a1112962f600",
        "user_id": "03825915-d9ac-48c9-9bda-8055ed415c25",
        "status": "trialing",
        "description": "Monthly tennis club signature",
        "interval": "day",
        "interval_count": "1",
        "processor_id": "5364358a-b8f7-4f45-b600-7fc614bf0285",
        "merchant_subscription_id": "MY-ORDER",
        "first_name": "John",
        "last_name": "Doe",
        "street_address_1": "59 N Santa Cruz Avenue",
        "street_address_2": "Suite M",
        "city": "Los Gatos",
        "state": "CA",
        "country": "US",
        "zip": "41970",
        "email": "support@paycertify.com",
        "mobile_phone": "+11231231234",
        "amount": "1.00",
        "trial_amount": null,
        "start_date": "2018-07-09T00:00:00+0000",
        "end_date": "2018-07-10T00:00:00+0000",
        "next_cycle_date": "2018-09-11T21:24:19+0000",
        "transactions": [
            {
                "id": "3410596f-d596-42d4-9811-41d43868e984",
                "merchant_id": "455a1c64-385b-41b2-a56f-34bf6c5c5335",
                "user_id": "6e064bf5-0e18-466b-811b-f967e8d73b9f",
                "processor_id": "30ff7682-6ec7-48f3-8d7a-62319a9c3c59",
                "merchant_transaction_id": "REC-MY-ORDER-0000",
                "card_number": "411111******1111",
                "card_brand": "visa",
                "card_expiry_month": "12",
                "card_expiry_year": "2020",
                "first_name": "John",
                "last_name": "Doe",
                "street_address_1": "59 N Santa Cruz Avenue",
                "street_address_2": "Suite M",
                "city": "Los Gatos",
                "state": "CA",
                "country": "US",
                "zip": "95030",
                "email": "support@paycertify.com",
                "mobile_phone": "+11231231234",
                "updated_at": "2018-02-16T16:33:40+00:00",
                "created_at": "2018-02-16T16:33:39+00:00",
                "events": [
                    {
                        "id": "84a8ab86-ee0e-47d4-8686-4e42fa58355e",
                        "success": true,
                        "threeds_response": null,
                        "avs_response": null,
                        "event_type": "refund",
                        "amount": "1.00",
                        "ip_address": "127.0.0.1",
                        "processor_code": "00",
                        "processor_message": "APPROVAL TAS656 ",
                        "processor_transaction_id": "000000000252616",
                        "processor_threeds_response": null,
                        "processor_avs_response": "0",
                        "updated_at": "2018-02-16T16:33:40+00:00",
                        "created_at": "2018-02-16T16:33:39+00:00"
                    },
                    {
                        "id": "84a8ab86-ee0e-47d4-8686-1e12fa12345e",
                        "success": true,
                        "threeds_response": null,
                        "avs_response": null,
                        "event_type": "sale",
                        "amount": "1.00",
                        "ip_address": "127.0.0.1",
                        "processor_code": "00",
                        "processor_message": "APPROVAL TAS656 ",
                        "processor_transaction_id": "000000000252616",
                        "processor_threeds_response": null,
                        "processor_avs_response": "0",
                        "updated_at": "2018-02-16T16:33:40+00:00",
                        "created_at": "2018-02-16T16:33:39+00:00"
                    }
                ]
            }
        ],
        "updated_at": "2018-09-10T21:24:19+0000",
        "created_at": "2018-09-10T21:24:19+0000",
        "card_number": "411111******1111",
        "card_expiry_month": "12",
        "card_expiry_year": "2020"
    }
}

Cancel a Subscription

DELETE https://gateway-api.paycertify.com/api/subscriptions/{subscription_id}

To cancel a subscription, you should use the Subscription ID response field to reference the subscription being canceled. This endpoint simply cancels the subscription and stops charging it.

Parameter Type Length Presence Description Example
subscription_id uuid 36 Required The Subscription record ID, sent on the URL 41f00869-d7b3-413e-9476-9ef1a8bc2f28
Parameter Type Length Description Example
subscription.id uuid 36 The Subscription record ID e57aa3bf-a3df-4056-b1f2-d4de7252fe99
subscription.merchant_id uuid 36 The user’s merchant ID e57aa3bf-a3df-4056-b1f2-d4de7252fe99
subscription.user_id uuid 36 The user’s ID e57aa3bf-a3df-4056-b1f2-d4de7252fe99
subscription.status string 6-8 Result of Subscription request trialing
subscription.description string 1-255 A brief description of the current subscription Monthly tennis club signature
subscription.interval string 3-5 Time period measure you require (day, week, month) day
subscription.interval_count number - Number of interval between payments 1
subscription.processor_id uuid 36 The processor’s ID e57aa3bf-a3df-4056-b1f2-d4de7252fe99
subscription.merchant_subscription_id string 1-255 A merchant assigned identifier (your subscription ID) MY-ORDER
subscription.first_name string 1-255 Customer’s first name John
subscription.last_name string 1-255 Customer’s last name Doe
subscription.street_address_1 string 1-255 Billing address first line (street address) 59 N Santa Cruz Avenue
subscription.street_address_2 string 1-255 Billing address second line (suite, apt, etc) Suite M
subscription.city string 1-255 Billing address city Los Gatos
subscription.state string 2 Billing address state abbreviation, ISO 3166-2 format. CA
subscription.country string 2 Billing address country abbreviation, ISO 3166-1 alpha-2 format. US
subscription.zip string 5 Billing address 5-digit postal code 95030
subscription.email string 1-255 Customer’s email support@paycertify.com
subscription.mobile_phone string 11-15 Customer’s phone in E.164 format +11231231234
subscription.amount number 0.01-9999999 Amount to be charged every recurring cycle 3.56
subscription.trial_amount number 0.01-9999999 The amount charged on Subscription creating, used for paid trial periods. 3.56
subscription.start_date datetime 19 The date and time when subscription should start Y-m-d h:m:s format. 2018-10-01 12:00:00
subscription.end_date datetime 19 The date and time when subscription should end Y-m-d h:m:s format. 2019-10-01 12:00:00
subscription.next_cycle_date datetime 19 The date and time of the next charge Y-m-d h:m:s format. 2019-10-01 12:00:00
subscription.transactions array - Listing of Subscription related transactions -
subscription.updated_at datetime 19 Last time this event was updated, on ISO 8601 UTC 2018-02-16T16:33:40+00:00
subscription.created_at datetime 19 Time that event was created, on ISO 8601 UTC 2018-02-16T16:33:40+00:00
subscription.card_number string 8-19 Redacted card number 411111**1111
subscription.card_expiry_month string 2 The expiration month with two positions 12
subscription.card_expiry_year string 4 The expiration year with four positions 2020
curl --request DELETE \
  --url https://gateway-api.paycertify.com/api/subscriptions/{subscription_id} \
  --header 'Authorization: Bearer YOUR_API_TOKEN' 
{
    "subscription": {
        "id": "e57aa3bf-a3df-4056-b1f2-d4de7252fe99",
        "merchant_id": "c8444f15-887b-45bf-a143-a1112962f600",
        "user_id": "03825915-d9ac-48c9-9bda-8055ed415c25",
        "status": "canceled",
        "description": "Monthly tennis club signature",
        "interval": "day",
        "interval_count": "1",
        "processor_id": "5364358a-b8f7-4f45-b600-7fc614bf0285",
        "merchant_subscription_id": "MY-ORDER",
        "first_name": "John",
        "last_name": "Doe",
        "street_address_1": "59 N Santa Cruz Avenue",
        "street_address_2": "Suite M",
        "city": "Los Gatos",
        "state": "CA",
        "country": "US",
        "zip": "41970",
        "email": "support@paycertify.com",
        "mobile_phone": "+11231231234",
        "amount": "1.00",
        "trial_amount": null,
        "start_date": "2018-07-09T00:00:00+0000",
        "end_date": "2018-07-10T00:00:00+0000",
        "next_cycle_date": "2018-09-11T21:24:19+0000",
        "transactions": [
            {
                "id": "3410596f-d596-42d4-9811-41d43868e984",
                "merchant_id": "455a1c64-385b-41b2-a56f-34bf6c5c5335",
                "user_id": "6e064bf5-0e18-466b-811b-f967e8d73b9f",
                "processor_id": "30ff7682-6ec7-48f3-8d7a-62319a9c3c59",
                "merchant_transaction_id": "REC-MY-ORDER-0000",
                "card_number": "411111******1111",
                "card_brand": "visa",
                "card_expiry_month": "12",
                "card_expiry_year": "2020",
                "first_name": "John",
                "last_name": "Doe",
                "street_address_1": "59 N Santa Cruz Avenue",
                "street_address_2": "Suite M",
                "city": "Los Gatos",
                "state": "CA",
                "country": "US",
                "zip": "95030",
                "email": "support@paycertify.com",
                "mobile_phone": "+11231231234",
                "updated_at": "2018-02-16T16:33:40+00:00",
                "created_at": "2018-02-16T16:33:39+00:00",
                "events": [
                    {
                        "id": "84a8ab86-ee0e-47d4-8686-4e42fa58355e",
                        "success": true,
                        "threeds_response": null,
                        "avs_response": null,
                        "event_type": "refund",
                        "amount": "1.00",
                        "ip_address": "127.0.0.1",
                        "processor_code": "00",
                        "processor_message": "APPROVAL TAS656 ",
                        "processor_transaction_id": "000000000252616",
                        "processor_threeds_response": null,
                        "processor_avs_response": "0",
                        "updated_at": "2018-02-16T16:33:40+00:00",
                        "created_at": "2018-02-16T16:33:39+00:00"
                    },
                    {
                        "id": "84a8ab86-ee0e-47d4-8686-1e12fa12345e",
                        "success": true,
                        "threeds_response": null,
                        "avs_response": null,
                        "event_type": "sale",
                        "amount": "1.00",
                        "ip_address": "127.0.0.1",
                        "processor_code": "00",
                        "processor_message": "APPROVAL TAS656 ",
                        "processor_transaction_id": "000000000252616",
                        "processor_threeds_response": null,
                        "processor_avs_response": "0",
                        "updated_at": "2018-02-16T16:33:40+00:00",
                        "created_at": "2018-02-16T16:33:39+00:00"
                    }
                ]
            }
        ],
        "updated_at": "2018-09-10T21:24:19+0000",
        "created_at": "2018-09-10T21:24:19+0000",
        "card_number": "411111******1111",
        "card_expiry_month": "12",
        "card_expiry_year": "2020"
    }
}

Renew a Subscription

PATCH https://gateway-api.paycertify.com/api/subscriptions/{subscription_id}

You can renew a subscription by updating its end_date field, you should use the Subscription ID response field to reference the subscription being renewed.

Parameter Type Length Presence Description Example
subscription_id uuid 36 Required The Subscription record ID, sent on the URL 41f00869-d7b3-413e-9476-9ef1a8bc2f28
subscription.end_date datetime 19 The new date and time when subscription should end Y-m-d h:m:s format. 2020-10-01 12:00:00  
Parameter Type Length Description Example
subscription.id uuid 36 The Subscription record ID e57aa3bf-a3df-4056-b1f2-d4de7252fe99
subscription.merchant_id uuid 36 The user’s merchant ID e57aa3bf-a3df-4056-b1f2-d4de7252fe99
subscription.user_id uuid 36 The user’s ID e57aa3bf-a3df-4056-b1f2-d4de7252fe99
subscription.status string 6-8 Result of Subscription request trialing
subscription.description string 1-255 A brief description of the current subscription Monthly tennis club signature
subscription.interval string 3-5 Time period measure you require (day, week, month) day
subscription.interval_count number - Number of interval between payments 1
subscription.processor_id uuid 36 The processor’s ID e57aa3bf-a3df-4056-b1f2-d4de7252fe99
subscription.merchant_subscription_id string 1-255 A merchant assigned identifier (your subscription ID) MY-ORDER
subscription.first_name string 1-255 Customer’s first name John
subscription.last_name string 1-255 Customer’s last name Doe
subscription.street_address_1 string 1-255 Billing address first line (street address) 59 N Santa Cruz Avenue
subscription.street_address_2 string 1-255 Billing address second line (suite, apt, etc) Suite M
subscription.city string 1-255 Billing address city Los Gatos
subscription.state string 2 Billing address state abbreviation, ISO 3166-2 format. CA
subscription.country string 2 Billing address country abbreviation, ISO 3166-1 alpha-2 format. US
subscription.zip string 5 Billing address 5-digit postal code 95030
subscription.email string 1-255 Customer’s email support@paycertify.com
subscription.mobile_phone string 11-15 Customer’s phone in E.164 format +11231231234
subscription.amount number 0.01-9999999 Amount to be charged every recurring cycle 3.56
subscription.trial_amount number 0.01-9999999 The amount charged on Subscription creating, used for paid trial periods. 3.56
subscription.start_date datetime 19 The date and time when subscription should start Y-m-d h:m:s format. 2018-10-01 12:00:00
subscription.end_date datetime 19 The date and time when subscription should end Y-m-d h:m:s format. 2020-10-01 12:00:00
subscription.next_cycle_date datetime 19 The date and time of the next charge Y-m-d h:m:s format. 2019-10-01 12:00:00
subscription.transactions array - Listing of Subscription related transactions -
subscription.updated_at datetime 19 Last time this event was updated, on ISO 8601 UTC 2018-02-16T16:33:40+00:00
subscription.created_at datetime 19 Time that event was created, on ISO 8601 UTC 2018-02-16T16:33:40+00:00
subscription.card_number string 8-19 Redacted card number 411111**1111
subscription.card_expiry_month string 2 The expiration month with two positions 12
subscription.card_expiry_year string 4 The expiration year with four positions 2020
curl --request PATCH \
  --url https://gateway-api.paycertify.com/api/subscriptions/{subscription_id} \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --form 'end_date=2020-10-10' 
{
    "subscription": {
        "id": "e57aa3bf-a3df-4056-b1f2-d4de7252fe99",
        "merchant_id": "c8444f15-887b-45bf-a143-a1112962f600",
        "user_id": "03825915-d9ac-48c9-9bda-8055ed415c25",
        "status": "active",
        "description": "Monthly tennis club signature",
        "interval": "day",
        "interval_count": "1",
        "processor_id": "5364358a-b8f7-4f45-b600-7fc614bf0285",
        "merchant_subscription_id": "MY-ORDER",
        "first_name": "John",
        "last_name": "Doe",
        "street_address_1": "59 N Santa Cruz Avenue",
        "street_address_2": "Suite M",
        "city": "Los Gatos",
        "state": "CA",
        "country": "US",
        "zip": "41970",
        "email": "support@paycertify.com",
        "mobile_phone": "+11231231234",
        "amount": "1.00",
        "trial_amount": null,
        "start_date": "2018-07-09T00:00:00+0000",
        "end_date": "2020-10-10T00:00:00+0000",
        "next_cycle_date": "2018-09-11T21:24:19+0000",
        "transactions": [
            {
                "id": "3410596f-d596-42d4-9811-41d43868e984",
                "merchant_id": "455a1c64-385b-41b2-a56f-34bf6c5c5335",
                "user_id": "6e064bf5-0e18-466b-811b-f967e8d73b9f",
                "processor_id": "30ff7682-6ec7-48f3-8d7a-62319a9c3c59",
                "merchant_transaction_id": "REC-MY-ORDER-0000",
                "card_number": "411111******1111",
                "card_brand": "visa",
                "card_expiry_month": "12",
                "card_expiry_year": "2020",
                "first_name": "John",
                "last_name": "Doe",
                "street_address_1": "59 N Santa Cruz Avenue",
                "street_address_2": "Suite M",
                "city": "Los Gatos",
                "state": "CA",
                "country": "US",
                "zip": "95030",
                "email": "support@paycertify.com",
                "mobile_phone": "+11231231234",
                "updated_at": "2018-02-16T16:33:40+00:00",
                "created_at": "2018-02-16T16:33:39+00:00",
                "events": [
                    {
                        "id": "84a8ab86-ee0e-47d4-8686-4e42fa58355e",
                        "success": true,
                        "threeds_response": null,
                        "avs_response": null,
                        "event_type": "refund",
                        "amount": "1.00",
                        "ip_address": "127.0.0.1",
                        "processor_code": "00",
                        "processor_message": "APPROVAL TAS656 ",
                        "processor_transaction_id": "000000000252616",
                        "processor_threeds_response": null,
                        "processor_avs_response": "0",
                        "updated_at": "2018-02-16T16:33:40+00:00",
                        "created_at": "2018-02-16T16:33:39+00:00"
                    },
                    {
                        "id": "84a8ab86-ee0e-47d4-8686-1e12fa12345e",
                        "success": true,
                        "threeds_response": null,
                        "avs_response": null,
                        "event_type": "sale",
                        "amount": "1.00",
                        "ip_address": "127.0.0.1",
                        "processor_code": "00",
                        "processor_message": "APPROVAL TAS656 ",
                        "processor_transaction_id": "000000000252616",
                        "processor_threeds_response": null,
                        "processor_avs_response": "0",
                        "updated_at": "2018-02-16T16:33:40+00:00",
                        "created_at": "2018-02-16T16:33:39+00:00"
                    }
                ]
            }
        ],
        "updated_at": "2018-09-10T21:24:19+0000",
        "created_at": "2018-09-10T21:24:19+0000",
        "card_number": "411111******1111",
        "card_expiry_month": "12",
        "card_expiry_year": "2020"
    }
}

Check Transactions

The Check Transactions API makes it possible to send and receive money between U.S.A. bank accounts. It does this by using standards implemented by banks and the Federal Reserve for transferring money called ACH. It works through a account validation process, and then issuing the check. Settlement generally occurs within a few hours, when you can safely confirm that the transaction was successfully settled and funds deducted from the customer’s account.

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

Authorization which stands for performing a validation of the bank info, while not blocking funds from the customer’s account; That means the balance is still available for the customer and there’s no guarantee of deduction yet.

Settlement which stands for a process that usually happens every 2 hours, 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 customer’s account. At this point, it is safe to allow access to product, that being shipping the product, or delivering a digital good / service.

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 two different types of events for check transactions:

A sale which runs the authorization portion and the settlement portion, which is not real-time; meaning you will have to use the reporting endpoints to check for settlement later; A refund request that works basically as a cancellation of the check if the sale didn’t settle, or an actual credit to the customer’s account if that transaction was already settled.

Charge an Account

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

Charging a bank account using PayCertify Gateway is simple. All you need is the bank account information of the person or entity you want to credit or debit. Then decide how much you want to send or receive from their bank account.

Refund an Account

POST https://gateway-api.paycertify.com/api/checks/{transaction_id}/refund

Refunding a bank account using PayCertify Gateway is simple. A refund stops the transaction from being settled and don’t remove funds from the customer.

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.

Parameter Type Length Presence Filter Type
merchant_transaction_id string 1-255 Optional starts with
card_number[1] string 8-19 Optional starts with
first_name string 1-255 Optional starts with
last_name string 1-255 Optional starts with
email string 1-255 Optional starts with
mobile_phone string 11-15 Optional starts with
user_id string 36 Optional exact comparison
city string 1-255 Optional starts with
state string 2 Optional exact comparison
zip string 5 Optional exact comparison
shipping_city string 1-255 Optional starts with
shipping_state string 2 Optional exact comparison
shipping_zip string 5 Optional exact comparison
created_at_gte datetime 19 Optional date
created_at_lte datetime 19 Optional date
updated_at_gte datetime 19 Optional date
updated_at_lte datetime 19 Optional date

[1] Please note that whenever searching for card numbers, you should only search by the first six digits, fill with 8 asterisks

Parameter Type Length Description Example
transactions.*.id uuid 36 This transaction’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transactions.*.merchant_id uuid 36 The user’s merchant ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transactions.*.user_id uuid 36 The user’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transactions.*.processor_id uuid 36 The processor’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transactions.*.merchant_transaction_id string 1-255 The merchant assigned identifier my-order-id-0001
transactions.*.updated_at datetime - Last time this transaction was updated, on ISO 8601 UTC 2018-02-16T16:33:40+00:00
trqnsactions.*.created_at datetime - Time that transaction was created, on ISO 8601 UTC 2018-02-16T16:33:40+00:00
transactions.*.events.*.id uuid 36 This event’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
transactions.*.events.*.success boolean - If the event was a successful event or not true
transactions.*.events.*.event_type string 4-10 The type of event being performed auth, capture, sale, void, refund
transactions.*.events.*.amount number 0.01-9999999 Total event amount 3.56
transactions.*.events.*.processor_code string 2-10 The processor response code 00
transactions.*.events.*.processor_message string 1-255 A human readable message from the processor APPROVAL V12341
transactions.*.events.*.processor_transaction_id string 1-255 A processor assigned identifier 00000000143242
transactions.*.events.*.updated_at datetime - Last time this event was updated, on ISO 8601 UTC 2018-02-16T16:33:40+00:00
transactions.*.events.*.created_at datetime - Time that event was created, on ISO 8601 UTC 2018-02-16T16:33:40+00:00
meta.last_page number - The last page for this query 1
meta.current_page number - The current page for this query 1
meta.total number - The total count of records for this page 1
curl --request GET \
  --url 'https://gateway-api.paycertify.com/api/transactions?search[first_name]=John&search[last_name]=Doe' \
  --header 'Authorization: Bearer EE9DC8DB823EF153186B9B3F2702DE378ACC2254' \
  --header 'Cache-Control: no-cache'

Responds with:

{
    "transactions": [
        {
            "id": "3410596f-d596-42d4-9811-41d43868e984",
            "merchant_id": "455a1c64-385b-41b2-a56f-34bf6c5c5335",
            "user_id": "6e064bf5-0e18-466b-811b-f967e8d73b9f",
            "processor_id": "30ff7682-6ec7-48f3-8d7a-62319a9c3c59",
            "merchant_transaction_id": "my-order-id-0001",
            "card_number": "411111******1111",
            "card_brand": "visa",
            "card_expiry_month": "12",
            "card_expiry_year": "2020",
            "first_name": "John",
            "last_name": "Doe",
            "street_address_1": "59 N Santa Cruz Avenue",
            "street_address_2": "Suite M",
            "city": "Los Gatos",
            "state": "CA",
            "country": "US",
            "zip": "95030",
            "email": "support@paycertify.com",
            "mobile_phone": "+11231231234",
            "updated_at": "2018-02-16T16:33:40+00:00",
            "created_at": "2018-02-16T16:33:39+00:00",
            "events": [
                {
                    "id": "84a8ab86-ee0e-47d4-8686-4e42fa58355e",
                    "success": true,
                    "threeds_response": null,
                    "avs_response": null,
                    "event_type": "sale",
                    "amount": "1.00",
                    "ip_address": "127.0.0.1",
                    "processor_code": "00",
                    "processor_message": "APPROVAL TAS656 ",
                    "processor_transaction_id": "000000000252616",
                    "processor_threeds_response": null,
                    "processor_avs_response": "0",
                    "updated_at": "2018-02-16T16:33:40+00:00",
                    "created_at": "2018-02-16T16:33:39+00:00"
                }
            ]
        },
        {
            "id": "93174e5d-79dd-4fa5-b817-ac366c37e524",
            "merchant_id": "455a1c64-385b-41b2-a56f-34bf6c5c5335",
            "user_id": "6e064bf5-0e18-466b-811b-f967e8d73b9f",
            "processor_id": "30ff7682-6ec7-48f3-8d7a-62319a9c3c59",
            "merchant_transaction_id": "my-order-id-0001",
            "card_number": "411111******1111",
            "card_brand": "visa",
            "card_expiry_month": "12",
            "card_expiry_year": "2020",
            "first_name": "John",
            "last_name": "Doe",
            "street_address_1": "59 N Santa Cruz Avenue",
            "street_address_2": "Suite M",
            "city": "Los Gatos",
            "state": "CA",
            "country": "US",
            "zip": "95030",
            "email": "support@paycertify.com",
            "mobile_phone": "+11231231234",
            "updated_at": "2018-02-16T16:33:32+00:00",
            "created_at": "2018-02-16T16:33:29+00:00",
            "events": [
                {
                    "id": "8525c0c9-f05f-4199-9646-e413728c57a0",
                    "success": false,
                    "threeds_response": null,
                    "avs_response": null,
                    "event_type": "sale",
                    "amount": "1.00",
                    "ip_address": "127.0.0.1",
                    "processor_code": "N7",
                    "processor_message": "CVV2 MISMATCH   ",
                    "processor_transaction_id": "000000000252613",
                    "processor_threeds_response": null,
                    "processor_avs_response": "0",
                    "updated_at": "2018-02-16T16:33:32+00:00",
                    "created_at": "2018-02-16T16:33:29+00:00"
                }
            ]
        }
    ],
    "meta": {
        "last_page": 1,
        "current_page": 1,
        "total": 2
    }
}

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.

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.

Parameter Type Length Description Example
processors.*.id uuid 36 This processor’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
processors.*.merchant_id uuid 36 The user’s merchant ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
processors.*.mid_number string 1-25 Merchant Identification Number 888000541200
processors.*.alias string 1-50 An alias given to identify this processor LOS GATOS STORE TERMINAL #1
processors.*.processor_type string 1-20 The processor integrator name tsys
processors.*.mcc string 4 Merchant Classification Code 1234
data.industry string 1-20 The industry for this processor ecommerce
meta.last_page number - The last page for this query 1
meta.current_page number - The current page for this query 1
meta.total number - The total count of records for this page 1
curl --request GET \
  --url 'https://gateway-api.paycertify.com/api/processors' \
  --header 'Authorization: Bearer EE9DC8DB823EF153186B9B3F2702DE378ACC2254' \
  --header 'Cache-Control: no-cache'

Responds with:

{
    "processors": [
        {
            "id": "ef7d010c-aeec-4dea-bbea-c89c4452b795",
            "merchant_id": "544ab96b-187a-4103-ac4b-247064856f1b",
            "mode": "live",
            "mid_number": "123123123",
            "alias": "LIVE PROCESSOR",
            "processor_type": "tsys",
            "mcc": "1234",
            "industry": "ecommerce",
            "acquirer_bin": "123123",
            "store_number": "1234",
            "terminal_number": "1234",
            "agent_bank_number": "123123",
            "agent_chain_number": "123123",
            "v_number": "12312312",
            "timezone_differential": "123",
            "merchant_name": "123",
            "merchant_city": "123",
            "merchant_state": "ca",
            "merchant_website": "1sadc.com",
            "merchant_phone": "123-1231234",
            "merchant_zip": "12345",
            "merchant_location_number": "12345",
            "level2_tax_percentage": null
        },
        {
            "id": "9b10b4b4-7752-40fd-9d9c-cb300c65b713",
            "merchant_id": "544ab96b-187a-4103-ac4b-247064856f1b",
            "mode": "test",
            "mid_number": "888000541200",
            "alias": "SOMETHING ELSE",
            "processor_type": "tsys",
            "mcc": "5999",
            "industry": "ecommerce",
            "acquirer_bin": "999995",
            "store_number": "5999",
            "terminal_number": "1515",
            "agent_bank_number": "000000",
            "agent_chain_number": "111111",
            "v_number": "76248476",
            "timezone_differential": "107",
            "merchant_name": "paycertify",
            "merchant_city": "Los Gatos",
            "merchant_state": "CA",
            "merchant_website": "test.com",
            "merchant_phone": "480-1231234",
            "merchant_zip": "85284",
            "merchant_location_number": "00001",
            "level2_tax_percentage": null
        }
    ]
}

Supported Processor Features

The follow table shows which features and transactions are supported by each processor that Pay Certify works with.

Feature Tsys AMEX PP Offshore MojoPay Skrill FirstData
Mastercard alt text alt text alt text alt text
VISA alt text alt text alt text alt text
AMEX alt text alt text alt text alt text
China Union Pay alt text
JCB alt text
Dinners alt text
Discover alt text
Auth alt text alt text
Sale alt text alt text alt text alt text
Capture alt text alt text
Void alt text alt text alt text
Refund alt text alt text alt text alt text
Address Verification Service alt text alt text
3D-Secure alt text
Dynamic Descriptors alt text alt text alt text
Partial Captures alt text alt text
Partial Voids alt text alt text
Partial Refunds alt text alt text alt text
Airline Data alt text alt text
Address Info Required? alt text alt text
CVV Required? alt text
First Name and Last Name alt text alt text alt text

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.

Parameter Type Length Presence Description Example
card_number string 8-19 Required The credit card to tokenize 4111111111111111
card_expiry_month string 2 Required The expiration month with two positions 12
card_expiry_year string 4 Required The expiration year with four positions 2025
Parameter Type Length Description Example
card_token.id uuid 36 This token’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
card_token.merchant_id uuid 36 The token’s merchant ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
card_token.card_token string 8-19 The tokenized credit card 4111098765431111
  curl --request POST \
    --url https://gateway-api.paycertify.com/api/tokens/tokenize \
    --header 'Authorization: Bearer YOUR_API_TOKEN' \
    --form 'card_number=4111111111111111' \
    --form 'card_expiry_month=12' \
    --form 'card_expiry_year=2025' \

Responds with:

  {
    "card_token": {
      "id": "41f00869-d7b3-413e-9476-9ef1a8bc2f28",
      "merchant_id": "41f00869-d7b3-413e-9476-9ef1a8bc2f28",
      "card_token": "4111098765431111"
    }
  }

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.

Parameter Type Length Presence Description Example
card_token string 8-19 Required The card token to de-tokenize 4111098765431111
Parameter Type Length Description Example
card_token.id uuid 36 This token’s ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
card_token.merchant_id uuid 36 The token’s merchant ID 41f00869-d7b3-413e-9476-9ef1a8bc2f28
card_token.card_number string 8-19 The original credit card number 4111111111111111
card_token.card_expiry_month string 8-19 The original credit card expiration month 12
card_token.card_expiry_year string 8-19 The original credit card expiration year 2025
  curl --request POST \
    --url https://gateway-api.paycertify.com/api/tokens/detokenize \
    --header 'Authorization: Bearer YOUR_API_TOKEN' \
    --form 'card_token=4111098765431111'

Responds with:

  {
    "card_token": {
      "id": "41f00869-d7b3-413e-9476-9ef1a8bc2f28",
      "merchant_id": "41f00869-d7b3-413e-9476-9ef1a8bc2f28",
      "card_number": "4111111111111111",
      "card_expiry_month": "12",
      "card_expiry_year": "2025"
    }
  }

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.

  • WooCommerce
  • Magento 1 (comming soon)
  • Magento 2 (comming soon)
  • Shopify
  • OpenCart (coming soon)

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.

To add a WordPress Plugin using the built-in plugin installer:

  1. Go to Plugins > Add New.
  2. Type in “WooCommerce PayCertify Payment Gateway” in Search Plugins box.
  3. Find the PayCertify Plugin.
  4. Click Install Now to install PayCertify Payment Gateway plugin.
  5. The resulting installation screen will list the installation as successful.
  6. 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:

  1. Download your WordPress Plugin to your desktop.
  2. If downloaded as a zip archive, extract the Plugin folder to your desktop.
  3. Read through the “readme” file thoroughly to ensure you follow the installation instructions.
  4. With your FTP program, upload the Plugin folder to the wp-content/plugins folder in your WordPress directory online.
  5. Go to Plugins screen and find the newly uploaded Plugin in the list.
  6. Click Activate to activate it.

Check the Details readme file for customization and further instructions.

You can check WordPress Codex for more information.

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.

  1. First of all, we need to enable the plugin. Check the “Enable PayCertify Gateway” box.
  2. 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.
  3. Description: is the information that customer will see during the checkout process.
  4. API Token: Insert your PayCertify API Token here. Don’t have one? Reach out to support@paycertify.com.
  5. AVS: If you want to use AVS, please enable this field. You can check Address Verification for more info. *
  6. Enable Partial Refunds: Enable this field if you want to enable Partial Refunds for WooCommerce orders. *
  7. Dynamic Descriptor: You can set credit card statement descriptor here. *

* Please check with PayCertify Support if your processor supports this feature.

Shopify Plugin

The PayCertify plugin for Shopify allows you to accept payments on PayCertify Secure hosted checkout page.

Installation

We need to do a manual installation to enable your store to use the PayCeritfy Payment Gateway. We made it easy for you, so just follow the following steps and you will have everything up and working quickly.

  1. Go to the following link to install PayCertify Shopify App.
  2. Enter your Store domain at Shopify and click on Submit; It should be the original domain, the one that finish with .myshopify.com;
  3. Now, you’ll receive a message to asking to install PayCertify App and that is not listed on the App Store, it is ok since Shopify don’t allow new Gateways to be officially integrated with them anymore.
  4. Click on Install unlisted app.

Configuration

After installing the PayCeritfy Payment Gateway App, it is time to configure and setup all the PayCertify settings on your store.

  1. First of all, we need to enable the plugin. Select Yes on the Enabled field.
  2. AVS Enabled: If you want to use AVS, please select Yes on this field. You can check Address Verification for more info. *
  3. API Token: Insert your PayCertify API Token here. Don’t have one? Reach out to support@paycertify.com.
  4. Dynamic Descriptor: You can set credit card statement descriptor here. *
  5. Click on Save button.

Now we have the App installed and configured, the next step is to add PayCertify as a payment method for your store.

  1. Go to Settings » Payment Providers and find the Manual Payments box.
  2. Click on Activate custom payment drop down and select: Create custom payment method.
  3. Name of the custom payment method should be PayCertify. Please note: if you enter anything else then this app will not work.
  4. Additional details: Is the information that customer will see during the checkout process, while customer is choosing how to pay.
  5. Payment Instructions: This information is displayed on the Thank You page. After the customer has placed the order.
  6. Click on Activate.

Now we have added PayCertify payment method, we are almost live. The last step here is to add a custom Javascript code to load the PayCertify Secure hosted checkout page.

  1. Go to Settings » Checkout.
  2. Find the Order Processing box.
  3. Put the following code into the Additional Scripts text field.
  4. Click on Save.
<script>
if ("{{order.gateway}}" === 'PayCertify' && "{{order.financial_status}}" == 'pending') {
    window.location = "https://shopify.paycertify.com/paycertify/checkout/?order_id={{ order_id }}&shop={{ shop.permanent_domain }}";
}
</script>