Versapay API Reference (1.3.0)

Download OpenAPI specification:Download

Overview

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

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

  • 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 [email protected] for support & setup of A/R invoicing integration, hosted checkout, and/or payment acceptance.

Environments

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

Rate Limits

There is a 120 request per minute API limit. Any requests above this limit will result in HTTP return code 403 Forbidden (Rate Limit Exceeded).

API Keys

Visit your account settings in demo or production to setup API keys needed for authentication as well as webhooks to receive relevant callbacks from Versapay transaction processing. You can generate/disable your API Keys 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.

Authentication

API requests are authenticated using HTTP Basic Access Authentication. Simply provide the token/key values as the user and password parameters, using cURL for instance

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

Webhooks

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.

You can view details for the latest notifications sent to your application by visiting /developers/webhook_responses in demo 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 ARC entities:

  • Recent events for any ARC Customer part of your ARC 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 ARC Invoice part of your ARC 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 ARC Payment part of your ARC supplier account. The request parameters will contain the same attributes as returned by viewing a payment via GET /api/exports/payment/{reference_or_token}.

PayPort Suppliers

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":"[email protected]",
    "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}"

ARC Suppliers

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}`);
});

Testing Transactions

EFT Bank Account Numbers

In the demo environment, the following test bank accounts can be setup up in your account.

Institution Institution Number Branch Account Number
TD 004 99960 1-12 digits
RBC 003 16824 1-12 digits
BMO 001 99520 1-12 digits
HSBC 016 10880 1-12 digits

When Versapay prompts you to verify these bank accounts enter a value of 1.23 for the verification amount.

To determine the outcome of a transaction funded by a bank account, set the amount accordingly:

Amount Resulting State
$x.10 nsfed
$x.11 completed_but_nsfed
$x.30 error
anything else completed

ACH Bank Account Numbers

Please contact [email protected] for support & setup of ACH acceptance and bank account numbers that can be used for testing.

Credit Card Numbers

Please contact [email protected] for support & setup of Credit Card acceptance and card brands/numbers that can be used for testing.

Postman

Try out the API using Postman app, a powerful REST API client. Download the Versapay API Reference as a Postman Collection by clicking on the button below:

Run in Postman

After downloading the collection, set up and configure the environment as follows:

  1. Download the sample environment file.

  2. Import the environment file in Postman.

    Import Environment

  3. Once it is imported, edit the environment to add API token and keys associated to your test account.

    Edit Environment

  4. Click Update to save your changes.

  5. Before placing API calls, make sure the correct environment is selected.

    Select Environment

Fund Sources

Fund Sources include bank accounts, credit cards, and balance associated with your account. The tokenized representation of these fund sources can be used to specify which fund to use when working with Transactions and Debit Agreements.

View Your Fund Sources

Responses

200

Successful Operation

401

Unauthorized

get /api/funds

Production

https://secure.versapay.com/api/funds

UAT

https://uat.versapay.com/api/funds

Response samples

Content type
application/json
Copy
Expand all Collapse all
[
  • {
    },
  • {
    },
  • {
    }
]

Vault a Bank Account

Vault a Bank Account for subsequent Transaction Use/Creation

Request Body schema: application/json

Bank account to vault.

business_name
string

Name of account holder.

country
string

CA (default), US, AU

account_number
string

Bank account number.

account_type
string

checking or savings, defaults checking (required country = US)

institution_number
string

Financial institution number (required country = CA).

branch_number
string

Financial institution branch/transit (required country = CA).

routing_number
string

Financial institution branch/location (required country = US, AU).

Responses

201

Created

401

Unauthorized

412

Precondition Failed

post /api/vault/bank

Production

https://secure.versapay.com/api/vault/bank

UAT

https://uat.versapay.com/api/vault/bank

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "business_name": "John Doe",
  • "country": "CA",
  • "account_number": "10101234",
  • "account_type": "checking",
  • "institution_number": "001",
  • "branch_number": "03662",
  • "routing_number": ""
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "token": "79VMZNLXCBL9",
  • "name": "TD Canada Trust (1234)",
  • "type": "bank_account"
}

Transactions

Transactions are used to move funds between fund sources. The directionality of the money transfer depends on the transaction type and the specified from/to fund tokens.

Lifecycle

The lifecycle states of transaction settlement/flow are:

State Context Action to Take
new The initial state for a new transaction. N/A
wait_for_claim The transaction has been created and an email delivered to the other party. They have not yet signed up and approved the transaction. None. You may want to remind the other party if the payment has not been approved for a sufficient length of time.
wait_for_request_approval The requestee has an account already. They have not yet approved the transaction. None. You may want to remind the other party if the payment has not been approved for a sufficient length of time.
wait_for_bank_account_verification The requestee has signed up and accepted the transaction, however they have not yet verified their bank account.

Note: Users are required to verify their bank account by going through the micro-debit process in which Versapay debits and credits the user’s bank account an undisclosed amount. The user then checks their online banking and fills in the amount on the Versapay website.
None. You may want to remind the other party if the bank has not been verified in a sufficient length of time.
rejected The transaction was rejected by the requestee. Review the rejection message.
in_progress The transaction has been sent to the bank and is in progress. N/A
error There was an error while processing the transaction. Contact your bank if the error pertains to your bank account.

Contact client or create a new transaction if the error is with the other party’s bank account.
nsfed The transaction's selected fund has in-sufficient funds and the transaction has been cancelled. Contact your bank if the error pertains to your bank account.

Contact client or create a new transaction if the error is with the other party’s bank account.
cancelled The transaction has been cancelled by an administrator. A transaction can only be cancelled before the debit has been sent to the bank. N/A
completed The transaction has been completed successfully. Update your order to "Paid".
completed_but_nsfed The transaction was completed successfully, but has been returned by the bank as in-sufficient funds. Update your order to "Un-paid".

Webhooks

When using Webhooks, your application will be notified any time a transaction's status has been updated. Note that for a variety of reasons strict ordering of notifications cannot be guaranteed. We recommend any integrations that track a "last seen" state either be aware of the flow of states (downward on the preceeding list), or only track actionable states.

Create Transactions

Request Body schema: application/json
transaction_type
required
string
amount_in_cents
required
integer

Transaction amount in cents.

email
required
string <email>

Recipient email address.

message
string

A message describing the transaction.

transaction_reference
string

Extra useful data to help link transactions to other systems e.g. PO numbers, account numbers etc.

unique_reference
string

Similar to transaction_reference, except it must be unique. Can be used as a duplicate transaction check.

process_on
string <date>

The date YYYY-MM-DD when this transaction should be started.

auto_withdraw
boolean

Set true to have transaction auto settle from Versapay balance to the specified bank account the night of completion; false to settle directly to Versapay balance. Auto withdraw must be enabled for your account. Only applicable to request and pre_authorized_debit transactions.

debit_agreement_token
string

The token that represents a pre-authorized agreement, see Agreements.

fund_token
string

Token of fund to use as the source.

credit
boolean

Set true to send money with Versapay credit. Your account must be credit enabled.

link_url
string

A specified url associated with transaction for instance linking to an invoice.

Responses

201

Created

401

Unauthorized

412

Precondition Failed

post /api/transactions

Production

https://secure.versapay.com/api/transactions

UAT

https://uat.versapay.com/api/transactions

Request samples

Content type
application/json
Example
Copy
Expand all Collapse all
{
  • "transaction_type": "send",
  • "amount_in_cents": 20000,
  • "email": "[email protected]",
  • "message": "Thank you",
  • "transaction_reference": "Order 3487",
  • "process_on": "2018-01-05",
  • "fund_token": "string",
  • "debit_agreement_token": "string",
  • "credit": true,
  • "link_url": "string"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "token": "79VMZNLXCBL9",
  • "amount_in_cents": 15000,
  • "message": "Thank you for doing business",
  • "type": "transaction",
  • "transaction_type": "send_money",
  • "email": "[email protected]",
  • "state": "in_progress",
  • "transaction_reference": "Lease 123",
  • "unique_reference": null,
  • "from_account": "John Doe",
  • "to_account": "Jane Smith",
  • "process_on": null,
  • "from_fund": "TD Canada Trust",
  • "created_by_user": "Uf6TaxzBMBBT_rXjsrN7"
}

View Transactions

query Parameters
page
integer

50 items are displayed per page.

Responses

200

Successful Operation

401

Unauthorized

get /api/transactions

Production

https://secure.versapay.com/api/transactions

UAT

https://uat.versapay.com/api/transactions

Response samples

Content type
application/json
Copy
Expand all Collapse all
[
  • {
    }
]

View a Transaction

path Parameters
token_or_unique_reference
required
string

The transaction identifier (or unique_reference).

Responses

200

Successful Operation

401

Unauthorized

get /api/transactions/{token_or_unique_reference}

Production

https://secure.versapay.com/api/transactions/{token_or_unique_reference}

UAT

https://uat.versapay.com/api/transactions/{token_or_unique_reference}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "token": "79VMZNLXCBL9",
  • "amount_in_cents": 15000,
  • "message": "Thank you for doing business",
  • "type": "transaction",
  • "transaction_type": "send_money",
  • "email": "