The Versapay API offers operations in support of its flagship products:

• Collaborative AR (formerly ARC) - accounts receivable platform with automated invoicing, effective collaboration, flexible payments and cash application to improve efficiency and customer relationships.

  • Importing & exporting customers, invoices, and payments.

  • Monitoring file based imports/batches.

  • Importing & exporting orders and processing order based payment transactions.

  • Ecommerce integrations.

• PayPort - cloud based platform to electronically push and pull funds across the EFT / ACH network.

  • Moving funds using transactions and pre-authorized debit agreements.

  • A secure hosted checkout for accepting payments through your website or email.

Please contact us at support@versapay.com for support & setup of A/R invoicing integration, hosted checkout, and/or payment acceptance.

The current API version is Versapay API Reference (1.3.31).

Versapay commits to maintaining backward compatibility and existing API endpoints with each released version updating existing endpoints and/or introducing new endpoints.

Should Versapay require deprecation of a published API, Versapay will work with its API clients/users to confirm specific EOL/migration timelines with ample lead times, as well as endpoint migration strategies.

The UAT environment is a useful sandbox for integration testing where transaction settlements are simulated using test account numbers and test dollar amounts.

https://uat.versapay.com

Once integration testing is complete via the UAT environment, start sending your requests to the production URL to start moving money and/or integrating with Versapay.

https://secure.versapay.com

The standard rate limit is 1500 requests per minute per IP address, but Versapay reserves the right to raise or lower that limit based on network conditions. When the rate limit is exceeded, APIs will return error HTTP 1015 you are being rate limited. Partner- or customer-specific rate limits can be established by special agreement.

Visit your account settings in UAT (https://uat.versapay.com/account) or Production (https://secure.versapay.com/account) to setup API credentials needed for authentication as well as webhooks to receive relevant callbacks from Versapay transaction processing.

You can generate/disable your API credentials as often as necessary for security reasons.

If you do not have an account, please contact Versapay Support for support & setup of AR invoicing integration, hosted checkout and/or payment acceptance for partner and/or API credential setup.

API requests are authenticated using API Token & Key via HTTPS Basic Access Authentication.

Security Scheme Type	HTTPS
HTTPS Authorization Scheme	basic

Simply provide the API Token & Key values as the user and password parameters, using cURL for instance:

curl -u "Nvax...:UN0I..." -X POST https://secure.versapay.com/api/...

Alternatively, API requests can also be authenticated using JWT Token via HTTPS Bearer Authentication.

Security Scheme Type	HTTPS
HTTP Authorization Scheme	bearer JWT

JWT Tokens, automatically generated alongside API Token & Key, are displayed along with expiration in account settings as well as via authenticated /api/whoami, see Authentication Echo identity and account profile settings

Simply provide the JWT Token in the authorization header, using cURL for instance:

curl -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0b2tlbiI6Im54eDFaSjgzeXRNNmhtb3NGVExCIiwiZXhwIjoxNzEyOTU5NDA5fQ.adV6U1vW69Ypskt61uPL8hZ-4muvtM4FLM48QN6iCc4" -X POST https://secure.versapay.com/api/...

Versapay uses the Webhook pattern to POST updates to a HTTP (port 80) or HTTPS (port 443) URL you specify.

The specified URL must return a status code of 200 otherwise Versapay will continue attempting to deliver the POST up to a system defined number of attempts.

A webhook consumer must be idempotent in receiving replayed/duplicated webhook payload transmissions which may arise as a result of subscription configuration and event timing and/or retry scenarios.

You can view details for the latest notifications sent to your application by visiting /developers/webhook_responses in uat or production.

Webhooks can receive updates for the following PayPort entities:

• State updates of any Transaction created by your account or going to your account. The request parameters will contain the same attributes as returned by viewing a transaction via GET /api/transactions/{token}.

• State updates of any Debit Agreement created by your account or sent to your account. The request parameters will contain the same attributes as returned by viewing a debit agreement via GET /api/debit_agreements/{token}.

Webhooks can receive updates for the following Collaborative AR entities:

• Recent events for any Customer part of your supplier account. The request parameters will contain the same attributes as returned by viewing a customer via GET /api/exports/customer/{identifier}.

• Recent events for any Invoice part of your supplier account. The request parameters will contain the same attributes as returned by viewing an invoice via GET /api/exports/invoice/{number_or_id}.

• Recent events for any Payment part of your supplier account. The request parameters will contain the same attributes as returned by viewing a payment via GET /api/exports/payment/{reference_or_token}.

Versapay will append a HMAC-SHA256 signature attribute to all webhook notifications. For instance:

POST http://your.domain.com/your/webhook/url
{
    "to_account":"Example user",
    "token":"5TH3ACC3AU21",
    "transaction_reference":"",
    "from_account":"First1 Last1",
    "from_fund":"THE TORONTO-DOMINION BANK",
    "transaction_type":"send_money",
    "amount_in_cents":500,
    "type":"transaction",
    "created_by_user":"699cMPe6BAyqvVsZA5mo",
    "message":"",
    "state":"completed",
    "link_url":"",
    "email":"user@example.com",
    "signature":"USYpBfZFQQHa2%2BT6UtDPUVFfUPP0aobWpXe5DE9hPOY%3D%0A"
}

To verify the authenticity of received webhook notifications:

1. Generate a single line request string concatenated with new line from:

   • The upper cased HTTP verb/method
     
   • The webhook URL
     
   • The attribute key/value pairs (without spaces) sorted ascending by key (excluding the signature attribute)
     

2. Calculate the HMAC-SHA256 of the single line string along using your Versapay signing key (which is displayed on your webhook account settings) and Base64 the result.

3. URL Encode the HMAC and compare to the value of the signature attribute for a match.

# Example of HMAC-SHA256 signature calculation - using Rails/Sinatra our POST payload is accessible via params

require 'openssl'
require 'base64'
require 'erb'

webhook_url = 'http://your.domain.com/your/webhook/url';
webhook_signing_key = 'v7aJHjbbxASKiwDW5wq6';

original_signature = params.delete(:signature)
sorted_key_values = params.keys.sort.map{ |key| "#{key}#{params[key]}" }.join

request_string = "POST\n#{webhook_url}\n#{sorted_key_values}"

expected_signature = ERB::Util.url_encode( Base64.encode64( OpenSSL::HMAC.digest(
OpenSSL::Digest::SHA256.new, webhook_signing_key, request_string
) ) )

puts "\nexpected signature: #{expected_signature}"
puts "\noriginal signature: #{original_signature}"
puts "\nauthentic? #{expected_signature == original_signature}"

Versapay will send a HMAC-SHA256 signature attribute to all webhook notification request headers under the key X-Versapay-Signature

To verify the authenticity of received webhook notifications:

1. Calculate the HMAC-SHA256 of the JSON request body using your Versapay signing key (which is displayed on your webhook account settings) and Base64 the result.
2. URL Encode the HMAC and compare the result to the value of the original signature found in the request header

/* Example of HMAC-SHA256 signature calculation - using JavaScript/Express our POST payload is accessible via req.body */
const express = require('express');
const bodyParser = require('body-parser');
const crypto = require('crypto');
const app = express();

app.use(bodyParser.json());
app.use(bodyParser.urlencoded({ extended: true }));

app.post('/webhook', (req, res) => {
  let original_signature = req.headers['x-versapay-signature'];
  let webhook_signing_key = 'v7aJHjbbxASKiwDW5wq6';
  let raw_request_body = JSON.stringify(req.body);
  let hmac = crypto.createHmac('sha256', webhook_signing_key).update(raw_request_body).digest('base64');
  let expected_signature = encodeURIComponent(hmac + "\n")
  console.log(`original signature: ${original_signature}`);
  console.log(`expected signature: ${expected_signature}`);
  console.log(`authentic? ${expected_signature === original_signature}`);
});

The API offers polling based endpoints to supplement/alternative to webhook integration. The requisite GET endpoints for customer, invoice, payment, and settlement reporting accept a "watermark" option to ensure that data more recent than the provided watermark is retrieved.

They also support a limit argument, which defaults to 100 items -- and are capped up to 2500 for performance reasons. Otherwise, the limit can be used to draw 1-2500 items at a time depending on the integrators need and performance boundaries.

The watermark & limit are specified as part of the API call e.g. GET /api/exports/open_invoices?watermark=13207500&limit=5

The watermark is typically an 8-byte integer unless otherwise specified. The limit is an integer between 1 and 2500.

The general response structure of these API are an ordered hash of records, whose key/index is a watermark value.

The iteration pattern would be, for instance:

last_watermark = 0
json = GET /api/...?watermark={last_watermark}
for each watermark_key in json.keys

  record = json[watermark_key]

  last_watermark = watermark_key if watermark_key > last_watermark

Otherwise, an API response may be a flat array list, where the watermark value is a key in the array item record, just the same:

last_watermark = 0
json = GET /api/...?watermark={last_watermark}
for each record in json

  watermark_key = record["watermark"]

  last_watermark = watermark_key if watermark_key > last_watermark

The last watermark key (or last watermark attribute where echo'd on a record) in the result set can be used as the argument to the next call e.g.

• GET /api/exports/open_invoices
• GET /api/exports/open_invoices?limit=2
• GET /api/exports/open_invoices?watermark=13207500&limit=7

The flat array list response structure can be explicitly requested via list=true URL argument.

For convenience purposes only, Versapay can supply third party reference data to its partners and users. This data can be used to implement client-side tooling (e.g., fraud mitigation services), but it may not be redistributed. The accuracy and completeness of this third party data cannot be guaranteed and is for informational and convenience purposes only. Contact support@versapay.com for eligibility for reference data enablement.

Onboarding supports the automated process of applying for merchant services. Contact support@versapay.com for support & setup of supplier onboarding partner credentials.

The Versapay e-commerce solution is composed of several components. First, is a server-side API that allows your application to configure a new payment session, manage customer wallets, create orders, and initiate payments. In addition, there is a client-side JavaScript SDK that enables your web application to accept secure payment data via an iframe hosted by Versapay. Your sensitive payment data will not transit your application when you use the iframe, so your application will have a reduced PCI scope.

In order to accept a payment, the general flow is to first create a session using the server-side API. Once a session ID has been generated by the Versapay server and returned to your application, your client-side code can use that session ID to initialize the Versapay payment SDK, which will, in turn, render the iframe. Next, the customer will interact with the iframe to specify a payment method. The SDK will return a token representing that payment method to your client-side code. Your client-side code must return the token to your server-side code, which will then use the original session ID and the token to create an order and take a payment. Finally, your ERP or order fulfillment system will query the Versapay cloud platform for new orders so that they may be created and fulfilled via your standard workflow.

For more information see Ecommerce API.

The Order entity represents the sales document in the ERP system. The fields in the ERP system should be aligned as closely as possible with the fields in the order entity, as the gateway will use these fields for credit card interchange optimization. Contact support@versapay.com for support & setup for Order and/or Order Transactions enablement.

Order-based card/ACH and card present EMV payment transactions include verify, authorize, capture, sale, void, return refund, and return credit transaction types. If participating in a gift card program, gift cards can be used in sale, void, refund transaction types. Contact support@versapay.com for support & setup for Order Transactions enablement.

There are two types of credit card payments: sale and delayed capture. Sale payments occur when the merchant wishes to accept a payment for goods or services that have already been shipped or provided to the cardholder. A sale is a financial transaction, and the movement of funds will be initiated in response to a sale request. Delayed capture payments are used when there is a separation between accepting an order and fulfilling that order. With delayed capture, the credit card is first authorized for the estimated order total. The authorization reserves funds on the cardholder’s account for the merchant but does not initiate a movement of funds. Once the products or services are ready to be delivered to the cardholder, the authorization is captured for the final amount. The capture request initiates the movement of funds.

ACH payments are bank-to-bank transfers of funds. Unlike credit card payments, ACH payments only have one type – sale, and there is no prior authorization. Therefore, sale amounts are final and cannot be adjusted after the fact. ACH payments assume success, and if there is a problem with the funding source, like with a bounced paper check, the originator will be notified of a rejection several days after the payment attempt.

Provisioned gift cards can be activated/enabled (or deactivated/disabled) as well as have their balances loaded/re-loaded with an amount. Contact support@versapay.com for support & setup for Gift Card acceptance.

Card Present EMV payment transactions require a Versapay certified point-of-sale terminal. In addition to the card not present transaction types, the following payment transaction types are also supported: device setup, request signature, and cancel. Contact support@versapay.com for support & setup for POS/CP EMV enablement.