Back to top

VersaPay API

Overview

The VersaPay API offers support for secure hosted checkout, payment transactions & pre-authorized debit agreements, and integration points to it’s flagship accounts receivable (A/R) solution.

Environments

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

https://demo.versapay.com

Once integration testing is complete via the demo 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 60 request per minute API limit. Any requests above this limit will result in HTTP return code 403 Forbidden (Rate Limit Exceeded).

Your Account

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

Otherwise, 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.

API Keys & Authentication

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

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:

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

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":"bLyDAezQTo0cyxiyA++OGIEXAaPAK5/SuP31VnPbEpw=%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)
  1. 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.

  2. 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 'uri'

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', webhook_url, sorted_key_values].join('\n')

expected_signature = URI.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}"

Formats

The VersaPay API accepts parameters in the request body as:

JSON/XML formats can be specified in any of the following ways:

  • By setting the Content-type header to text/json/application/json or text/xml
curl -X POST https://secure.versapay.com/api/transactions -H 'Content-type: application/json' -d "{\"transaction_type\":\"request\",\"amount_in_cents\":\"3000\",\"email\":\"user@example.com\"}"
  • By appending a .json or .xml suffix to the API URL
curl -X POST https://secure.versapay.com/api/transactions.json -d "{\"transaction_type\":\"request\",\"amount_in_cents\":\"3000\",\"email\":\"user@example.com\"}"

HTTP Response Codes

Successful create operations typically return 201 otherwise success is returned as HTTP 200.

Failures return 412 and the response body should be inspected for further error messages.

Authentication and/or account setup related failures return 401.

Testing Transactions

EFT Bank Account Numbers

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

Institution Branch Account Number
004 (TD) 99960 1-12 digits
003 (RBC) 16824 1-12 digits
001 (BMO) 99520 1-12 digits
016 (HSBC) 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 us at support@versapay.com for support & setup of ACH acceptance and bank account numbers that can be used for testing.

Credit Card Numbers

Please contact us at support@versapay.com for support & setup of Credit Card acceptance and card brands/numbers that can be used for testing.

Fund Sources

Fund Sources include the 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

  • Debit Agreements

View your fund sources

View your fund sources
GET/api/funds

Attribute Value
type ‘bank_account’, ‘credit_card’, or ‘balance’
token Fund’s unique identifier used to identify fund when using other API calls.
name Masked display name
state Returned for bank accounts. Values are ‘verified’, ‘unverified’, and ‘invalid’.

Example URI

GET /api/funds
Request  JSON
HideShow
Headers
Content-Type: application/json
Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
[
  {
    "type": "bank_account",
    "token": "BA7YQ5881W8Q",
    "name": "TD Canada Trust (2929)",
    "state": "verified"
  },
  {
    "type": "bank_account",
    "token": "BA9SL6DXVV9F",
    "name": "white - TD Canada Trust (5622)",
    "state": "verified"
  },
  {
    "type": "credit_card",
    "token": "CC7HPKMIUP2D",
    "name": "VISA **2224"
  },
  {
    "type": "credit_card",
    "token": "CC7W4GFHF2UI",
    "name": "VISA **1234"
  },
  {
    "type": "balance",
    "token": "VPB2VJ7W9UVW",
    "name": "VersaPay 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 (see Lifecycle).

Create send, request transactions

Create send, request transactions
POST/api/transactions

Example URI

POST /api/transactions
URI Parameters
HideShow
amount_in_cents
number (required) 

Transaction amount in cents.

transaction_type
string (required) 

‘send’ or ‘request’

email
string (required) 

Recipient email address.

fund_token
string (optional) 

Token of fund to use as the source (send) or destination (request, pre_authorized_debit).

message
string (optional) 

A message describing the transaction

transaction_reference
string (optional) 

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

unique_reference
string (optional) 

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

auto_withdraw
string (optional) 

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.

link_url
string (optional) 

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

credit
string (optional) 

Set ‘true’ to send money with VersaPay credit. Your account must be credit enabled. Only applicable to send transactions.

process_on
string (optional) 

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

Response  201
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "token": "5TH3ACC3AU21",
  "amount_in_cents": 12345,
  "message": "Thank you for doing business",
  "email": "user@example.com",
  "state": "in_progress",
  "from_account": "John Doe",
  "to_account": "Jane Smith",
  "from_fund": "CIBC 1223",
  "to_fund": "BMO 9877",
  "from_fund_token": "XJ129",
  "to_fund_token": "AK982",
  "created_by_user": "XJABCDIRH",
  "transaction_reference": "Lease 123",
  "link_url": "http://a.link.to/your/invoice",
  "process_on": "2016",
  "auto_withdraw": "true"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "token": {
      "type": "string",
      "description": "The transaction identifier\n"
    },
    "amount_in_cents": {
      "type": "number",
      "description": "Transaction amount in cents\n"
    },
    "message": {
      "type": "string",
      "description": "A message describing the transaction\n"
    },
    "email": {
      "type": "string",
      "description": "Recipient email address\n"
    },
    "state": {
      "type": "string",
      "description": "Transactions current state, see Lifecycle\n"
    },
    "from_account": {
      "type": "string",
      "description": "Name of the originating account\n"
    },
    "to_account": {
      "type": "string",
      "description": "Name of the recipient account\n"
    },
    "from_fund": {
      "type": "string",
      "description": "Name of the balance or bank account used when **transaction_type** is 'send' or 'direct_credit'\n"
    },
    "to_fund": {
      "type": "string",
      "description": "Name of the destination balance or bank account when **transaction_type** is 'request' or 'direct_debit'\n"
    },
    "from_fund_token": {
      "type": "string",
      "description": "Source fund identifier for reuse when **transaction_type** is 'direct_debit'\n"
    },
    "to_fund_token": {
      "type": "string",
      "description": "Destination fund identifier for reuse when **transaction_type** is 'direct_credit'\n"
    },
    "created_by_user": {
      "type": "string",
      "description": "Name of the user otherwise the API token appears if the transaction was created with the api.\n"
    },
    "transaction_reference": {
      "type": "string",
      "description": "Reference value associated with the transaction\n"
    },
    "link_url": {
      "type": "string",
      "description": "A specified url associated with transaction.\n"
    },
    "process_on": {
      "type": "string",
      "description": "07-29 (string)\n\nThe YYYY-MM-DD date when this transaction will be started\n"
    },
    "auto_withdraw": {
      "type": "string",
      "description": "If true then the transaction will be auto withdrawn the night of completion.\n"
    }
  }
}

Create pre_authorized_debit transactions

Create pre_authorized_debit transactions
POST/api/transactions

Example URI

POST /api/transactions
URI Parameters
HideShow
debit_agreement_token
string (required) 

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

amount_in_cents
number (required) 

Transaction amount in cents.

transaction_type
string (required) 

‘send’ or ‘request’

email
string (required) 

Recipient email address.

fund_token
string (optional) 

Token of fund to use as the source (send) or destination (request, pre_authorized_debit).

message
string (optional) 

A message describing the transaction

transaction_reference
string (optional) 

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

unique_reference
string (optional) 

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

auto_withdraw
string (optional) 

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.

link_url
string (optional) 

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

credit
string (optional) 

Set ‘true’ to send money with VersaPay credit. Your account must be credit enabled. Only applicable to send transactions.

process_on
string (optional) 

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

Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "token": "5TH3ACC3AU21",
  "amount_in_cents": 12345,
  "message": "Thank you for doing business",
  "email": "user@example.com",
  "state": "in_progress",
  "from_account": "John Doe",
  "to_account": "Jane Smith",
  "from_fund": "CIBC 1223",
  "to_fund": "BMO 9877",
  "from_fund_token": "XJ129",
  "to_fund_token": "AK982",
  "created_by_user": "XJABCDIRH",
  "transaction_reference": "Lease 123",
  "link_url": "http://a.link.to/your/invoice",
  "process_on": "2016",
  "auto_withdraw": "true"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "token": {
      "type": "string",
      "description": "The transaction identifier\n"
    },
    "amount_in_cents": {
      "type": "number",
      "description": "Transaction amount in cents\n"
    },
    "message": {
      "type": "string",
      "description": "A message describing the transaction\n"
    },
    "email": {
      "type": "string",
      "description": "Recipient email address\n"
    },
    "state": {
      "type": "string",
      "description": "Transactions current state, see Lifecycle\n"
    },
    "from_account": {
      "type": "string",
      "description": "Name of the originating account\n"
    },
    "to_account": {
      "type": "string",
      "description": "Name of the recipient account\n"
    },
    "from_fund": {
      "type": "string",
      "description": "Name of the balance or bank account used when **transaction_type** is 'send' or 'direct_credit'\n"
    },
    "to_fund": {
      "type": "string",
      "description": "Name of the destination balance or bank account when **transaction_type** is 'request' or 'direct_debit'\n"
    },
    "from_fund_token": {
      "type": "string",
      "description": "Source fund identifier for reuse when **transaction_type** is 'direct_debit'\n"
    },
    "to_fund_token": {
      "type": "string",
      "description": "Destination fund identifier for reuse when **transaction_type** is 'direct_credit'\n"
    },
    "created_by_user": {
      "type": "string",
      "description": "Name of the user otherwise the API token appears if the transaction was created with the api.\n"
    },
    "transaction_reference": {
      "type": "string",
      "description": "Reference value associated with the transaction\n"
    },
    "link_url": {
      "type": "string",
      "description": "A specified url associated with transaction.\n"
    },
    "process_on": {
      "type": "string",
      "description": "07-29 (string)\n\nThe YYYY-MM-DD date when this transaction will be started\n"
    },
    "auto_withdraw": {
      "type": "string",
      "description": "If true then the transaction will be auto withdrawn the night of completion.\n"
    }
  }
}

Create EFT direct_debit, direct_credit transactions

Create EFT direct_debit, direct_credit transactions
POST/api/transactions

Example URI

POST /api/transactions
URI Parameters
HideShow
amount_in_cents
number (required) 

Transaction amount in cents.

transaction_type
string (required) 

‘direct_debit’ or ‘direct_credit’

email
string (required) 

Recipient email address.

fund_token
string (optional) 

Token of fund to use as the source direct_credit or destination direct_debit.

message
string (optional) 

A message describing the transaction

transaction_reference
string (optional) 

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

unique_reference
string (optional) 

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

memo
string (optional) 

Memo displayed on customer banking statement.

auto_withdraw
string (optional) 

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.

business_name
string (required) 

Required if first_name and last_name are omitted

first_name
string (optional) 

First name of recipient

last_name
string (optional) 

Last name of recipient

institution_number
string (required) 

Canadian Bank Account institution number. 3 digits. Required for new funding sources. Omitted if using to/from_fund_token instead.

branch_number
string (required) 

Canadian Bank Account branch number. Between 4-5 digits. Required for new funding sources. Omitted if using to/from_fund_token instead.

account_number
string (required) 

Canadian Bank Account number. Between 1-12 digits Required for new funding sources. Omitted if using to/from_fund_token instead.

to_fund_token
string (optional) 

May be provided instead of destination bank numbers on subsequent transactions when transaction_type is ‘direct_credit’.

from_fund_token
string (optional) 

May be provided instead of source bank numbers on subsequent transactions when transaction_type is ‘direct_debit’.

process_on
string (optional) 

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

Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "token": "5TH3ACC3AU21",
  "amount_in_cents": 12345,
  "message": "Thank you for doing business",
  "email": "user@example.com",
  "state": "in_progress",
  "from_account": "John Doe",
  "to_account": "Jane Smith",
  "from_fund": "CIBC 1223",
  "to_fund": "BMO 9877",
  "from_fund_token": "XJ129",
  "to_fund_token": "AK982",
  "created_by_user": "XJABCDIRH",
  "transaction_reference": "Lease 123",
  "link_url": "http://a.link.to/your/invoice",
  "process_on": "2016",
  "auto_withdraw": "true"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "token": {
      "type": "string",
      "description": "The transaction identifier\n"
    },
    "amount_in_cents": {
      "type": "number",
      "description": "Transaction amount in cents\n"
    },
    "message": {
      "type": "string",
      "description": "A message describing the transaction\n"
    },
    "email": {
      "type": "string",
      "description": "Recipient email address\n"
    },
    "state": {
      "type": "string",
      "description": "Transactions current state, see Lifecycle\n"
    },
    "from_account": {
      "type": "string",
      "description": "Name of the originating account\n"
    },
    "to_account": {
      "type": "string",
      "description": "Name of the recipient account\n"
    },
    "from_fund": {
      "type": "string",
      "description": "Name of the balance or bank account used when **transaction_type** is 'send' or 'direct_credit'\n"
    },
    "to_fund": {
      "type": "string",
      "description": "Name of the destination balance or bank account when **transaction_type** is 'request' or 'direct_debit'\n"
    },
    "from_fund_token": {
      "type": "string",
      "description": "Source fund identifier for reuse when **transaction_type** is 'direct_debit'\n"
    },
    "to_fund_token": {
      "type": "string",
      "description": "Destination fund identifier for reuse when **transaction_type** is 'direct_credit'\n"
    },
    "created_by_user": {
      "type": "string",
      "description": "Name of the user otherwise the API token appears if the transaction was created with the api.\n"
    },
    "transaction_reference": {
      "type": "string",
      "description": "Reference value associated with the transaction\n"
    },
    "link_url": {
      "type": "string",
      "description": "A specified url associated with transaction.\n"
    },
    "process_on": {
      "type": "string",
      "description": "07-29 (string)\n\nThe YYYY-MM-DD date when this transaction will be started\n"
    },
    "auto_withdraw": {
      "type": "string",
      "description": "If true then the transaction will be auto withdrawn the night of completion.\n"
    }
  }
}

Create ACH direct_debit, direct_credit transactions

Create ACH direct_debit, direct_credit transactions
POST/api/transactions

Example URI

POST /api/transactions
URI Parameters
HideShow
amount_in_cents
number (required) 

Transaction amount in cents.

transaction_type
string (required) 

‘direct_debit’ or ‘direct_credit’

email
string (required) 

Recipient email address.

fund_token
string (optional) 

Token of fund to use as the source direct_credit or destination direct_debit.

message
string (optional) 

A message describing the transaction

transaction_reference
string (optional) 

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

unique_reference
string (optional) 

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

memo
string (optional) 

Memo displayed on customer banking statement.

auto_withdraw
string (optional) 

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.

business_name
string (required) 

Required if first_name and last_name are omitted

first_name
string (optional) 

First name of recipient

last_name
string (optional) 

Last name of recipient

routing_number
string (required) 

US Bank Account routing number. Required for new funding sources. Omitted if using to/from_fund_token instead.

account_number
string (required) 

US Bank Account number. Required for new funding sources. Omitted if using to/from_fund_token instead.

account_type
string (required) 

US Bank Account type ‘checking’ or ‘savings’. Required for new funding sources. Omitted if using to/from_fund_token instead.

to_fund_token
string (optional) 

May be provided instead of destination bank numbers on subsequent transactions when transaction_type is ‘direct_credit’.

from_fund_token
string (optional) 

May be provided instead of source bank numbers on subsequent transactions when transaction_type is ‘direct_debit’.

process_on
string (optional) 

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

Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "token": "5TH3ACC3AU21",
  "amount_in_cents": 12345,
  "message": "Thank you for doing business",
  "email": "user@example.com",
  "state": "in_progress",
  "from_account": "John Doe",
  "to_account": "Jane Smith",
  "from_fund": "CIBC 1223",
  "to_fund": "BMO 9877",
  "from_fund_token": "XJ129",
  "to_fund_token": "AK982",
  "created_by_user": "XJABCDIRH",
  "transaction_reference": "Lease 123",
  "link_url": "http://a.link.to/your/invoice",
  "process_on": "2016",
  "auto_withdraw": "true"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "token": {
      "type": "string",
      "description": "The transaction identifier\n"
    },
    "amount_in_cents": {
      "type": "number",
      "description": "Transaction amount in cents\n"
    },
    "message": {
      "type": "string",
      "description": "A message describing the transaction\n"
    },
    "email": {
      "type": "string",
      "description": "Recipient email address\n"
    },
    "state": {
      "type": "string",
      "description": "Transactions current state, see Lifecycle\n"
    },
    "from_account": {
      "type": "string",
      "description": "Name of the originating account\n"
    },
    "to_account": {
      "type": "string",
      "description": "Name of the recipient account\n"
    },
    "from_fund": {
      "type": "string",
      "description": "Name of the balance or bank account used when **transaction_type** is 'send' or 'direct_credit'\n"
    },
    "to_fund": {
      "type": "string",
      "description": "Name of the destination balance or bank account when **transaction_type** is 'request' or 'direct_debit'\n"
    },
    "from_fund_token": {
      "type": "string",
      "description": "Source fund identifier for reuse when **transaction_type** is 'direct_debit'\n"
    },
    "to_fund_token": {
      "type": "string",
      "description": "Destination fund identifier for reuse when **transaction_type** is 'direct_credit'\n"
    },
    "created_by_user": {
      "type": "string",
      "description": "Name of the user otherwise the API token appears if the transaction was created with the api.\n"
    },
    "transaction_reference": {
      "type": "string",
      "description": "Reference value associated with the transaction\n"
    },
    "link_url": {
      "type": "string",
      "description": "A specified url associated with transaction.\n"
    },
    "process_on": {
      "type": "string",
      "description": "07-29 (string)\n\nThe YYYY-MM-DD date when this transaction will be started\n"
    },
    "auto_withdraw": {
      "type": "string",
      "description": "If true then the transaction will be auto withdrawn the night of completion.\n"
    }
  }
}

View the latest transactions for your account

View the latest transactions for your account
GET/api/transactions?page={page}

Example URI

GET /api/transactions?page=1
URI Parameters
HideShow
page
number (optional) Example: 1

50 items are displayed per page

Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
[
  {
    "token": "5TH3ACC3AU21",
    "amount_in_cents": 12345,
    "message": "Thank you for doing business",
    "email": "user@example.com",
    "state": "in_progress",
    "from_account": "John Doe",
    "to_account": "Jane Smith",
    "from_fund": "CIBC 1223",
    "to_fund": "BMO 9877",
    "from_fund_token": "XJ129",
    "to_fund_token": "AK982",
    "created_by_user": "XJABCDIRH",
    "transaction_reference": "Lease 123",
    "link_url": "http://a.link.to/your/invoice",
    "process_on": "2016",
    "auto_withdraw": "true"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

View a transaction

View a transaction
GET/api/transactions/{token}

Example URI

GET /api/transactions/5TH3ACC3AU21
URI Parameters
HideShow
token
string (required) Example: 5TH3ACC3AU21

The transaction identifier

Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "token": "5TH3ACC3AU21",
  "amount_in_cents": 12345,
  "message": "Thank you for doing business",
  "email": "user@example.com",
  "state": "in_progress",
  "from_account": "John Doe",
  "to_account": "Jane Smith",
  "from_fund": "CIBC 1223",
  "to_fund": "BMO 9877",
  "from_fund_token": "XJ129",
  "to_fund_token": "AK982",
  "created_by_user": "XJABCDIRH",
  "transaction_reference": "Lease 123",
  "link_url": "http://a.link.to/your/invoice",
  "process_on": "2016",
  "auto_withdraw": "true"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "token": {
      "type": "string",
      "description": "The transaction identifier\n"
    },
    "amount_in_cents": {
      "type": "number",
      "description": "Transaction amount in cents\n"
    },
    "message": {
      "type": "string",
      "description": "A message describing the transaction\n"
    },
    "email": {
      "type": "string",
      "description": "Recipient email address\n"
    },
    "state": {
      "type": "string",
      "description": "Transactions current state, see Lifecycle\n"
    },
    "from_account": {
      "type": "string",
      "description": "Name of the originating account\n"
    },
    "to_account": {
      "type": "string",
      "description": "Name of the recipient account\n"
    },
    "from_fund": {
      "type": "string",
      "description": "Name of the balance or bank account used when **transaction_type** is 'send' or 'direct_credit'\n"
    },
    "to_fund": {
      "type": "string",
      "description": "Name of the destination balance or bank account when **transaction_type** is 'request' or 'direct_debit'\n"
    },
    "from_fund_token": {
      "type": "string",
      "description": "Source fund identifier for reuse when **transaction_type** is 'direct_debit'\n"
    },
    "to_fund_token": {
      "type": "string",
      "description": "Destination fund identifier for reuse when **transaction_type** is 'direct_credit'\n"
    },
    "created_by_user": {
      "type": "string",
      "description": "Name of the user otherwise the API token appears if the transaction was created with the api.\n"
    },
    "transaction_reference": {
      "type": "string",
      "description": "Reference value associated with the transaction\n"
    },
    "link_url": {
      "type": "string",
      "description": "A specified url associated with transaction.\n"
    },
    "process_on": {
      "type": "string",
      "description": "07-29 (string)\n\nThe YYYY-MM-DD date when this transaction will be started\n"
    },
    "auto_withdraw": {
      "type": "string",
      "description": "If true then the transaction will be auto withdrawn the night of completion.\n"
    }
  }
}

Approve a transaction

Approve a transaction
POST/api/transactions/{token}/approve

Approve a new, wait_for_request_approval transaction.

An API key with administrative access is required to approve a transaction.

Example URI

POST /api/transactions/5TH3ACC3AU21/approve
URI Parameters
HideShow
token
string (required) Example: 5TH3ACC3AU21

The transaction identifier

fund_token
string (optional) 

Your bank account or balance’s token attribute. Omitting this option will approve the transaction using your default bank account.

Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "token": "5TH3ACC3AU21",
  "amount_in_cents": 12345,
  "message": "Thank you for doing business",
  "email": "user@example.com",
  "state": "in_progress",
  "from_account": "John Doe",
  "to_account": "Jane Smith",
  "from_fund": "CIBC 1223",
  "to_fund": "BMO 9877",
  "from_fund_token": "XJ129",
  "to_fund_token": "AK982",
  "created_by_user": "XJABCDIRH",
  "transaction_reference": "Lease 123",
  "link_url": "http://a.link.to/your/invoice",
  "process_on": "2016",
  "auto_withdraw": "true"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "token": {
      "type": "string",
      "description": "The transaction identifier\n"
    },
    "amount_in_cents": {
      "type": "number",
      "description": "Transaction amount in cents\n"
    },
    "message": {
      "type": "string",
      "description": "A message describing the transaction\n"
    },
    "email": {
      "type": "string",
      "description": "Recipient email address\n"
    },
    "state": {
      "type": "string",
      "description": "Transactions current state, see Lifecycle\n"
    },
    "from_account": {
      "type": "string",
      "description": "Name of the originating account\n"
    },
    "to_account": {
      "type": "string",
      "description": "Name of the recipient account\n"
    },
    "from_fund": {
      "type": "string",
      "description": "Name of the balance or bank account used when **transaction_type** is 'send' or 'direct_credit'\n"
    },
    "to_fund": {
      "type": "string",
      "description": "Name of the destination balance or bank account when **transaction_type** is 'request' or 'direct_debit'\n"
    },
    "from_fund_token": {
      "type": "string",
      "description": "Source fund identifier for reuse when **transaction_type** is 'direct_debit'\n"
    },
    "to_fund_token": {
      "type": "string",
      "description": "Destination fund identifier for reuse when **transaction_type** is 'direct_credit'\n"
    },
    "created_by_user": {
      "type": "string",
      "description": "Name of the user otherwise the API token appears if the transaction was created with the api.\n"
    },
    "transaction_reference": {
      "type": "string",
      "description": "Reference value associated with the transaction\n"
    },
    "link_url": {
      "type": "string",
      "description": "A specified url associated with transaction.\n"
    },
    "process_on": {
      "type": "string",
      "description": "07-29 (string)\n\nThe YYYY-MM-DD date when this transaction will be started\n"
    },
    "auto_withdraw": {
      "type": "string",
      "description": "If true then the transaction will be auto withdrawn the night of completion.\n"
    }
  }
}

Cancel a transaction

Cancel a transaction
POST/api/transactions/{token}/cancel

Cancel a new, wait_for_request_approval or wait_for_bank_account_verification transaction you created. Transactions cannot be cancelled after they have been sent to the bank and are in_progress.

An API key with administrative access is required to cancel a transaction.

Example URI

POST /api/transactions/5TH3ACC3AU21/cancel
URI Parameters
HideShow
token
string (required) Example: 5TH3ACC3AU21

The transaction identifier

Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "token": "5TH3ACC3AU21",
  "amount_in_cents": 12345,
  "message": "Thank you for doing business",
  "email": "user@example.com",
  "state": "in_progress",
  "from_account": "John Doe",
  "to_account": "Jane Smith",
  "from_fund": "CIBC 1223",
  "to_fund": "BMO 9877",
  "from_fund_token": "XJ129",
  "to_fund_token": "AK982",
  "created_by_user": "XJABCDIRH",
  "transaction_reference": "Lease 123",
  "link_url": "http://a.link.to/your/invoice",
  "process_on": "2016",
  "auto_withdraw": "true"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "token": {
      "type": "string",
      "description": "The transaction identifier\n"
    },
    "amount_in_cents": {
      "type": "number",
      "description": "Transaction amount in cents\n"
    },
    "message": {
      "type": "string",
      "description": "A message describing the transaction\n"
    },
    "email": {
      "type": "string",
      "description": "Recipient email address\n"
    },
    "state": {
      "type": "string",
      "description": "Transactions current state, see Lifecycle\n"
    },
    "from_account": {
      "type": "string",
      "description": "Name of the originating account\n"
    },
    "to_account": {
      "type": "string",
      "description": "Name of the recipient account\n"
    },
    "from_fund": {
      "type": "string",
      "description": "Name of the balance or bank account used when **transaction_type** is 'send' or 'direct_credit'\n"
    },
    "to_fund": {
      "type": "string",
      "description": "Name of the destination balance or bank account when **transaction_type** is 'request' or 'direct_debit'\n"
    },
    "from_fund_token": {
      "type": "string",
      "description": "Source fund identifier for reuse when **transaction_type** is 'direct_debit'\n"
    },
    "to_fund_token": {
      "type": "string",
      "description": "Destination fund identifier for reuse when **transaction_type** is 'direct_credit'\n"
    },
    "created_by_user": {
      "type": "string",
      "description": "Name of the user otherwise the API token appears if the transaction was created with the api.\n"
    },
    "transaction_reference": {
      "type": "string",
      "description": "Reference value associated with the transaction\n"
    },
    "link_url": {
      "type": "string",
      "description": "A specified url associated with transaction.\n"
    },
    "process_on": {
      "type": "string",
      "description": "07-29 (string)\n\nThe YYYY-MM-DD date when this transaction will be started\n"
    },
    "auto_withdraw": {
      "type": "string",
      "description": "If true then the transaction will be auto withdrawn the night of completion.\n"
    }
  }
}

Agreement

Debit Agreements are a digital analog to paper pre-authorized debit agreements that businesses could use, for instance, for monthly billing.

The creator of an agreement can cancel at any time. The other party can approve, reject, or later revoke an agreement at any time.

Lifecycle

The lifecycle states of debit agreements are:

State Context Action to take
pending The recipient has been sent an email to approve the agreement. N/A
approved The agreement has been approved. Create a pre-authorized debit transaction that references the agreement when you bill.
rejected The agreement was rejected by the requestee. Review the rejection message
cancelled The agreement was cancelled by the requestor. Cancel the subscription with the other party.
revoked The agreement was cancelled by the requestee. Cancel the subscription with the other party.
wait_for_bank_account_verification The associated bank account has not yet been verified. None - The recipient has been notified.

Email the recipient if the bank account is not verified within a reasonable amount of time.
invalid_funding_source There were errors with the associated bank account or credit card. None - The recipient has been notified to change the funding source.

Email the recipient if the fund is not changed within a reasonable amount of time.

Webhooks

When using Webhooks, your application will be notified any time an agreement’s status has been updated (see Lifecycle); allowing you to start billing when approved or cancel a subscription when rejected or revoked.

Create an agreement

Create an agreement
POST/api/debit_agreements

Example URI

POST /api/debit_agreements
URI Parameters
HideShow
email
string (required) 

Recipient email address.

reference
string (optional) 

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

message
string (optional) 

A message describing what the agreement is for.

Response  201
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "token": "5TH3ACC3AU21",
  "state": "in_progress",
  "email": "user@example.com",
  "name": "John Doe",
  "created_by_user": "XJABCDIRH",
  "created_by_account": "Central Media News",
  "reference": "Ad 123",
  "message": "Thank you for doing business",
  "rejection_reason": "Hello, world!",
  "type": "'debit_agreement'"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "token": {
      "type": "string",
      "description": "The agreement identifier\n"
    },
    "state": {
      "type": "string",
      "description": "Transactions current state, see Lifecycle\n"
    },
    "email": {
      "type": "string",
      "description": "Recipient email address\n"
    },
    "name": {
      "type": "string",
      "description": "Recipient name\n"
    },
    "created_by_user": {
      "type": "string",
      "description": "Name of the user otherwise the API token appears if the transaction was created with the api.\n"
    },
    "created_by_account": {
      "type": "string",
      "description": "Account name of the user otherwise the API token appears if the transaction was created with the api.\n"
    },
    "reference": {
      "type": "string",
      "description": "An optional reference\n"
    },
    "message": {
      "type": "string",
      "description": "A message describing the agreement\n"
    },
    "rejection_reason": {
      "type": "string",
      "description": "Message for the creator of an agreement. Set when state is **rejected**.\n"
    },
    "type": {
      "type": "string"
    }
  }
}

View sent agreements

View sent agreements
GET/api/debit_agreements/sent?page={page}

Example URI

GET /api/debit_agreements/sent?page=1
URI Parameters
HideShow
page
number (optional) Example: 1

50 items are displayed per page

Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
[
  {
    "token": "5TH3ACC3AU21",
    "state": "in_progress",
    "email": "user@example.com",
    "name": "John Doe",
    "created_by_user": "XJABCDIRH",
    "created_by_account": "Central Media News",
    "reference": "Ad 123",
    "message": "Thank you for doing business",
    "rejection_reason": "Hello, world!",
    "type": "'debit_agreement'"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

View received agreements

View received agreements
GET/api/debit_agreements/received?page={page}

Example URI

GET /api/debit_agreements/received?page=1
URI Parameters
HideShow
page
number (optional) Example: 1

50 items are displayed per page

Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
[
  {
    "token": "5TH3ACC3AU21",
    "state": "in_progress",
    "email": "user@example.com",
    "name": "John Doe",
    "created_by_user": "XJABCDIRH",
    "created_by_account": "Central Media News",
    "reference": "Ad 123",
    "message": "Thank you for doing business",
    "rejection_reason": "Hello, world!",
    "type": "'debit_agreement'"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

Approve an agreement

Approve an agreement
POST/api/debit_agreements/{token}/approve

Example URI

POST /api/debit_agreements/5TH3ACC3AU21/approve
URI Parameters
HideShow
token
string (required) Example: 5TH3ACC3AU21

The agreement identifier

fund_token
string (optional) 

Your bank account or balance’s token attribute. Omitting this option will approve the agreement using your default bank account.

Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "token": "5TH3ACC3AU21",
  "state": "in_progress",
  "email": "user@example.com",
  "name": "John Doe",
  "created_by_user": "XJABCDIRH",
  "created_by_account": "Central Media News",
  "reference": "Ad 123",
  "message": "Thank you for doing business",
  "rejection_reason": "Hello, world!",
  "type": "'debit_agreement'"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "token": {
      "type": "string",
      "description": "The agreement identifier\n"
    },
    "state": {
      "type": "string",
      "description": "Transactions current state, see Lifecycle\n"
    },
    "email": {
      "type": "string",
      "description": "Recipient email address\n"
    },
    "name": {
      "type": "string",
      "description": "Recipient name\n"
    },
    "created_by_user": {
      "type": "string",
      "description": "Name of the user otherwise the API token appears if the transaction was created with the api.\n"
    },
    "created_by_account": {
      "type": "string",
      "description": "Account name of the user otherwise the API token appears if the transaction was created with the api.\n"
    },
    "reference": {
      "type": "string",
      "description": "An optional reference\n"
    },
    "message": {
      "type": "string",
      "description": "A message describing the agreement\n"
    },
    "rejection_reason": {
      "type": "string",
      "description": "Message for the creator of an agreement. Set when state is **rejected**.\n"
    },
    "type": {
      "type": "string"
    }
  }
}

Cancel an agreement

Cancel an agreement
POST/api/debit_agreements/{token}/cancel

Example URI

POST /api/debit_agreements/5TH3ACC3AU21/cancel
URI Parameters
HideShow
token
string (required) Example: 5TH3ACC3AU21

The agreement identifier

Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "token": "5TH3ACC3AU21",
  "state": "in_progress",
  "email": "user@example.com",
  "name": "John Doe",
  "created_by_user": "XJABCDIRH",
  "created_by_account": "Central Media News",
  "reference": "Ad 123",
  "message": "Thank you for doing business",
  "rejection_reason": "Hello, world!",
  "type": "'debit_agreement'"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "token": {
      "type": "string",
      "description": "The agreement identifier\n"
    },
    "state": {
      "type": "string",
      "description": "Transactions current state, see Lifecycle\n"
    },
    "email": {
      "type": "string",
      "description": "Recipient email address\n"
    },
    "name": {
      "type": "string",
      "description": "Recipient name\n"
    },
    "created_by_user": {
      "type": "string",
      "description": "Name of the user otherwise the API token appears if the transaction was created with the api.\n"
    },
    "created_by_account": {
      "type": "string",
      "description": "Account name of the user otherwise the API token appears if the transaction was created with the api.\n"
    },
    "reference": {
      "type": "string",
      "description": "An optional reference\n"
    },
    "message": {
      "type": "string",
      "description": "A message describing the agreement\n"
    },
    "rejection_reason": {
      "type": "string",
      "description": "Message for the creator of an agreement. Set when state is **rejected**.\n"
    },
    "type": {
      "type": "string"
    }
  }
}

Reject an agreement

Reject an agreement
POST/api/debit_agreements/{token}/reject

Reject a pending agreement by supplying an agreement’s token attribute and providing a rejection_reason.

Example URI

POST /api/debit_agreements/5TH3ACC3AU21/reject
URI Parameters
HideShow
token
string (required) Example: 5TH3ACC3AU21

The agreement identifier

Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "token": "5TH3ACC3AU21",
  "state": "in_progress",
  "email": "user@example.com",
  "name": "John Doe",
  "created_by_user": "XJABCDIRH",
  "created_by_account": "Central Media News",
  "reference": "Ad 123",
  "message": "Thank you for doing business",
  "rejection_reason": "Hello, world!",
  "type": "'debit_agreement'"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "token": {
      "type": "string",
      "description": "The agreement identifier\n"
    },
    "state": {
      "type": "string",
      "description": "Transactions current state, see Lifecycle\n"
    },
    "email": {
      "type": "string",
      "description": "Recipient email address\n"
    },
    "name": {
      "type": "string",
      "description": "Recipient name\n"
    },
    "created_by_user": {
      "type": "string",
      "description": "Name of the user otherwise the API token appears if the transaction was created with the api.\n"
    },
    "created_by_account": {
      "type": "string",
      "description": "Account name of the user otherwise the API token appears if the transaction was created with the api.\n"
    },
    "reference": {
      "type": "string",
      "description": "An optional reference\n"
    },
    "message": {
      "type": "string",
      "description": "A message describing the agreement\n"
    },
    "rejection_reason": {
      "type": "string",
      "description": "Message for the creator of an agreement. Set when state is **rejected**.\n"
    },
    "type": {
      "type": "string"
    }
  }
}

Revoke an agreement

Revoke an agreement
POST/api/debit_agreements/{token}/revoke

Revoke an approved agreement for your account by supplying an agreement’s token attribute. The agreement’s creator will no longer be able to debit your account using this agreement.

Example URI

POST /api/debit_agreements/5TH3ACC3AU21/revoke
URI Parameters
HideShow
token
string (required) Example: 5TH3ACC3AU21

The agreement identifier

Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "token": "5TH3ACC3AU21",
  "state": "in_progress",
  "email": "user@example.com",
  "name": "John Doe",
  "created_by_user": "XJABCDIRH",
  "created_by_account": "Central Media News",
  "reference": "Ad 123",
  "message": "Thank you for doing business",
  "rejection_reason": "Hello, world!",
  "type": "'debit_agreement'"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "token": {
      "type": "string",
      "description": "The agreement identifier\n"
    },
    "state": {
      "type": "string",
      "description": "Transactions current state, see Lifecycle\n"
    },
    "email": {
      "type": "string",
      "description": "Recipient email address\n"
    },
    "name": {
      "type": "string",
      "description": "Recipient name\n"
    },
    "created_by_user": {
      "type": "string",
      "description": "Name of the user otherwise the API token appears if the transaction was created with the api.\n"
    },
    "created_by_account": {
      "type": "string",
      "description": "Account name of the user otherwise the API token appears if the transaction was created with the api.\n"
    },
    "reference": {
      "type": "string",
      "description": "An optional reference\n"
    },
    "message": {
      "type": "string",
      "description": "A message describing the agreement\n"
    },
    "rejection_reason": {
      "type": "string",
      "description": "Message for the creator of an agreement. Set when state is **rejected**.\n"
    },
    "type": {
      "type": "string"
    }
  }
}

Hosted Checkout

Hosted checkout is a URL based method for accepting a payment through your website or email without the need for custom programming.

Single Payment Hosted Checkout

Single Payment Hosted Checkout
GET/send_money

Clients, customers, or donors, for instance, can send your organization money directly from their bank account or credit card simply by clicking a link which displays a page with your account name allowing your customer to make a payment to you for the specified dollar amount:

https://secure.versapay.com/send_money?api_token={your_api_token}&amount={dollar_amount_for_customer_to_pay}

Funds will go to the fund destination passed in the to_fund parameter. By default, the funds will be deposited into your default bank account once the transaction clears from the other party.

Example URI

GET /send_money
URI Parameters
HideShow
api_token
string (required) Example: XJ15

A valid API token generated from your account.

amount
number (required) Example: 250.75

The amount in dollars that the transaction is for.

message
string (optional) Example: Thank you for your donation

A message which will be stored with the transaction.

return_to
string (optional) Example: https://your.site.com/thank/you

A url which will displayed to the user to return to your website after they finish the Signup and Confirmation.

link_url
string (optional) Example: https://your.site.com/your/tax/receipt

A url that gets stored and displayed on the transaction for an invoice.

pref
string (optional) 

The preferred payment type either ba or cc for bank or credit card respectively.

to_fund
string (optional) Example: 699cMPe6BAyqvVsZA5mo

The token of the bank account or balance where the funds should go to.

reference
string (optional) Example: Lease 123

Extra data (max 255 characters). Great for storing internal order or account number.

locale
string (optional) Example: fr

Set the default language of the checkout, either en or fr. Users will still be able to switch to their preferred language.

Debit Agreement Hosted Checkout

Debit Agreement Hosted Checkout
GET/authorize

Clients, customers, or donors, for instance, can initiate a pre-authorized debit agreement by clicking a link on your website or in an email.

https://secure.versapay.com/authorize?api_token={your_api_token}&message={explanation_of_what_this_is_for}

Example URI

GET /authorize
URI Parameters
HideShow
api_token
string (required) Example: XJ15

A valid API token generated from your account.

message
string (required) Example: Your monthly bill

A message for the user describing the pre-authorized debit agreement.

return_to
string (optional) Example: https://your.site.com/thank/you

A url which will displayed to the user to return to your website after they finish the Signup and Confirmation.

reference
string (optional) Example: Lease 123

Extra data (max 255 characters). Great for storing internal order or account number.

Imports

Invoicing enabled supplier accounts can transmit customer, invoice, and payment data (for instance, from their source ERP) to leverage the ARC platform for presentment, collaboration, collections/buyer payment via the customer portal, and remittance reconcilation.

Import a CSV file as a batch

Import a CSV file as a batch
POST/api/imports

When uploading a CSV formatted file it’s helpful to use your language/framework tooling to simplify the multipart/form-data file upload, for instance:

  • Using cURL:
curl \
  -u "Nvax...:UN0I..." \
  -F "filename=data.csv" \
  -F "file=@/home/user/Desktop/data.csv" \
  https://secure.versapay.com/api/imports/
  • Using ruby (and HTTParty/HTTMultiParty):
file = { :file => File.new('/home/user/Desktop/data.csv') }
auth = { :basic_auth => { :username => 'Nvax...', :password => 'UN0I...' } }
HTTMultiParty.post('https://secure.versapay.com/api/imports/', auth.merge( :query => file ))

Size Limit

The file cannot exceed 25MB

Layouts

Please contact us at support@versapay.com for our standard inbound CSV file layouts.

  • Example Customers:
identifier,name,email,first_name,last_name,notes,address_1,address_2,city,province,postal_code,country,URL,telephone,fax,business_number,locale
10001,Foo Inc.,jane@example.com,Jane,Doe,This is the guy for the stuff,123 Main. St,Unit 12,Whoville,BC,H0H 0H0,CA,www.exmaple.com,(905) 555-1212,(905) 555-1213,1234567890,en
10004,Royal Food Products,bob.smith@foo.ca,Bob,Smith,,999 Any St.,,Albany,NY,12345,US,http://www.foo.com,,,,fr
  • Example Invoices:
number,purchase_order_number,amount,currency,due_date,order_date,date,customer_identifier,line_item_number,line_item_description,line_item_amount,line_item_quantity,line_item_unit_cost,notes,shipping_name,shipping_address_1,shipping_address_2,shipping_city,shipping_province,shipping_postal_code,shipping_country,auto_debit,division,auto_debit_reference,balance,extra_information
REF0001,87654321,531.28,CAD,2014-07-31,2014-06-30,2014-07-01,10001,1,Item 1,511.28,20.05,25.5,Thanks for your business,ABC Retail Company Warehouse,11 Main St.,Unit 2,Anytown,ON,H0H 0H0,CA,T,DIV1,45009,531.28,invoice and line_item
REF0001,87654321,531.28,CAD,2014-07-31,2014-06-30,2014-07-01,10001,2,Item 2,20,10,2,Thanks for your business,ABC Retail Company Warehouse,11 Main St.,Unit 2,Anytown,ON,H0H 0H0,CA,T,DIV1,45009,531.28,line_item
REF0002,,122.5,CAD,2014-07-31,2014-06-30,2014-07-01,10001,1,A thing,122.5,10,12.25,Thanks for your business,ABC Retail Company Warehouse,11 Main St.,Unit 2,Anytown,ON,H0H 0H0,CA,T,DIV1,47980,122.5,invoice and line_item
REF0003,,200,CAD,2014-07-31,2014-06-30,2014-07-01,10004,1,Another thing,200,2,100,Thanks for your business,ABC Retail Company Warehouse,11 Main St.,Unit 2,Anytown,ON,H0H 0H0,CA,T,DIV1,,150,invoice and line_item
INV0001,,910,USD,2014-08-31,2014-07-29,2014-08-01,2001,1,Service 1,120,2,60,Thanks for your business,LA Studios,123 Hollywood St.,Unit 600,Los Angeles,CA,95004,US,,DIV2,,910,invoice and line_item
INV0001,,910,USD,2014-08-31,2014-07-29,2014-08-01,2002,2,Service 2,540,6,90,Thanks for your business,LA Studios,123 Hollywood St.,Unit 600,Los Angeles,CA,95004,US,,DIV2,,910,line_item
INV0001,,910,USD,2014-08-31,2014-07-29,2014-08-01,2003,3,Service 3,250,10,25,Thanks for your business,LA Studios,123 Hollywood St.,Unit 600,Los Angeles,CA,95004,US,,DIV2,,910,line_item
  • Example Payments:
identifier,invoice_number,amount,date,currency,payment_code,payment_description,payment_note
P1,REF0001,200,2014-07-02,CAD,,,
P2,REF0002,122.5,2014-07-03,CAD,,,
P3,REF0004,70,2014-07-04,CAD,,,
P3,REF0005,30,2014-07-05,CAD,,,
P4,REF0003,40,2014-07-06,CAD,PMT,Payment,For first line item only.
P5,REF0003,60,2014-07-07,CAD,PMT,Payment,For second line item.
P6,REF0006,100,2014-07-07,CAD,DISP,To cover dispute,
P7,REF0007,-50,2014-07-07,CAD,DISC,Discount,
P8,REF0010,300,2014-07-07,CAD,BD,Bad Debt,
P9,REF0010,-300,2014-07-08,CAD,RBD,Reverse Bad Debt,

Example URI

POST /api/imports
URI Parameters
HideShow
file
binary (required) Example: multipart/form-data

multipart/form-data

filename
string (optional) Example: invoices.csv

Name of original file

Response  201
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "id": 21877,
  "file_name": "invoices.csv",
  "file_size": 1024,
  "file_content_type": "text/plain",
  "file_fingerprint": "bf817b5548d69f6a3a49b6bb872fb906",
  "error": "",
  "result_message": "5487 invoices",
  "complete_at": "2016-08-30T15:39:30-04:00"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The import batch identifier\n"
    },
    "file_name": {
      "type": "string",
      "description": "The original filename of the raw file\n"
    },
    "file_size": {
      "type": "number",
      "description": "The original size of the raw file in bytes\n"
    },
    "file_content_type": {
      "type": "string",
      "description": "The MIME/content-type of the raw file\n"
    },
    "file_fingerprint": {
      "type": "string",
      "description": "The fingerprint/hash representing the raw file contents\n"
    },
    "error": {
      "type": "string",
      "description": "The error message corresponding to a failed import\n"
    },
    "result_message": {
      "type": "string"
    },
    "complete_at": {
      "type": "string",
      "description": "The ISO8601 timestamp corresponding to completion of the import\n"
    }
  }
}

View recent in progress & completed import batches

View recent in progress & completed import batches
GET/api/imports?page={page}

Example URI

GET /api/imports?page=1
URI Parameters
HideShow
page
number (optional) Example: 1

50 items are displayed per page

Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
[
  {
    "id": 21877,
    "file_name": "invoices.csv",
    "file_size": 1024,
    "file_content_type": "text/plain",
    "file_fingerprint": "bf817b5548d69f6a3a49b6bb872fb906",
    "error": "",
    "result_message": "5487 invoices",
    "complete_at": "2016-08-30T15:39:30-04:00"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

View only recent in progress import batches

View only recent in progress import batches
GET/api/imports/processing?page={page}

Example URI

GET /api/imports/processing?page=1
URI Parameters
HideShow
page
number (optional) Example: 1

50 items are displayed per page

Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
[
  {
    "id": 21877,
    "file_name": "invoices.csv",
    "file_size": 1024,
    "file_content_type": "text/plain",
    "file_fingerprint": "bf817b5548d69f6a3a49b6bb872fb906",
    "error": "",
    "result_message": "5487 invoices",
    "complete_at": "2016-08-30T15:39:30-04:00"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

View only recent completed import batches

View only recent completed import batches
GET/api/imports/completed?page={page}

Example URI

GET /api/imports/completed?page=1
URI Parameters
HideShow
page
number (optional) Example: 1

50 items are displayed per page

Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
[
  {
    "id": 21877,
    "file_name": "invoices.csv",
    "file_size": 1024,
    "file_content_type": "text/plain",
    "file_fingerprint": "bf817b5548d69f6a3a49b6bb872fb906",
    "error": "",
    "result_message": "5487 invoices",
    "complete_at": "2016-08-30T15:39:30-04:00"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}

View an import batch

View an import batch
GET/api/imports/{id}

Example URI

GET /api/imports/21877
URI Parameters
HideShow
id
string (required) Example: 21877

The import batch identifier

Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "id": 21877,
  "file_name": "invoices.csv",
  "file_size": 1024,
  "file_content_type": "text/plain",
  "file_fingerprint": "bf817b5548d69f6a3a49b6bb872fb906",
  "error": "",
  "result_message": "5487 invoices",
  "complete_at": "2016-08-30T15:39:30-04:00"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number",
      "description": "The import batch identifier\n"
    },
    "file_name": {
      "type": "string",
      "description": "The original filename of the raw file\n"
    },
    "file_size": {
      "type": "number",
      "description": "The original size of the raw file in bytes\n"
    },
    "file_content_type": {
      "type": "string",
      "description": "The MIME/content-type of the raw file\n"
    },
    "file_fingerprint": {
      "type": "string",
      "description": "The fingerprint/hash representing the raw file contents\n"
    },
    "error": {
      "type": "string",
      "description": "The error message corresponding to a failed import\n"
    },
    "result_message": {
      "type": "string"
    },
    "complete_at": {
      "type": "string",
      "description": "The ISO8601 timestamp corresponding to completion of the import\n"
    }
  }
}

Import a customer

Import a customer
POST/api/imports/customer

Please contact us at support@versapay.com for information on standard inbound attributes.

Note any additional non-standard attributes supplied will be stored with invoice record and available for presentment rendering

Example URI

POST /api/imports/customer
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "identifier": "cci007",
  "name": "Coffee Company Inc",
  "email": "tim@coffee.co"
}
Response  201
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "message": "1 customer 1 contacts",
  "identifier": "cci007"
}

Import a customer with multiple contacts

Import a customer with multiple contacts
POST/api/imports/customer

Please contact us at support@versapay.com for information on standard inbound attributes.

Example URI

POST /api/imports/customer
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "identifier": "cci007",
  "name": "Coffee Company Inc",
  "email": "tim@coffee.co",
  "line_item_attributes": [
    {
      "email": "fred@coffee.co",
      "first_name": "Fred",
      "last_name": "Smith"
    }
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "message": "1 customer 1 contacts",
  "identifier": "cci007"
}

Import an invoice

Import an invoice
POST/api/imports/invoice

Please contact us at support@versapay.com for information on standard inbound attributes.

Note customer will be created/updated using the customer_* attributes if necessary at time of invoice import

Note any additional non-standard attributes supplied will be stored with invoice record and available for presentment rendering

Example URI

POST /api/imports/invoice
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "customer_identifier": "cci007",
  "number": "INV007",
  "display_number": "INV007",
  "purchase_order_number": "PO007",
  "amount": 250.5,
  "owing_cents": 250.5,
  "currency": "usd",
  "date": "2017-01-01",
  "due_date": "2017-02-01",
  "notes_text": "Thank you for your business",
  "shipping_name": "Coffee Company Accounts Payable",
  "address_1": "1 Wall Street",
  "address_2": "Suite 600",
  "postal_code": "90210",
  "city": "Beverly Hills",
  "province": "CA",
  "shipping_country": "USA",
  "draft": "false",
  "line_item_attributes": [
    {
      "number": "1",
      "description": "Widget part",
      "quantity": 2,
      "amount": 250.5,
      "purchase_order_number": "L101",
      "order_key": "O1234567"
    }
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "message": "1 invoice 1 line items",
  "identifier": "INV007"
}

Import a payment

Import a payment
POST/api/imports/payment

Please contact us at support@versapay.com for information on standard inbound attributes.

Note customer will be created using the customer_* attributes if doesn’t already exist at time of payment import

Example URI

POST /api/imports/payment
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "identifier": "PMT123",
  "invoice_number": "INV007",
  "amount": 125,
  "currency": "usd",
  "date": "2017-01-01",
  "customer_identifier": "cci007",
  "customer_name": "Coffee Company Inc",
  "notes_text": "Thank you for your business"
}
Response  201
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "message": "1 payment 1 invoice amounts",
  "identifier": "PMT123"
}

Import a payment for multiple invoices

Import a payment for multiple invoices
POST/api/imports/payment

Please contact us at support@versapay.com for information on standard inbound attributes.

Note customer will be created using the customer_* attributes if doesn’t already exist at time of payment import

Example URI

POST /api/imports/payment
Request
HideShow
Headers
Content-Type: application/json
Body
{
  "identifier": "PMT123",
  "amount": 125,
  "currency": "usd",
  "date": "2017-01-01",
  "customer_identifier": "cci007",
  "customer_name": "Coffee Company Inc",
  "notes_text": "Thank you for your business",
  "payment_amounts_attributes": [
    {
      "invoice_number": "INV007",
      "amount": 100.5,
      "notes": "Partial payment"
    }
  ]
}
Response  201
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
{
  "message": "1 payment 1 invoice amounts",
  "identifier": "PMT123"
}

Exports

Invoicing enabled supplier accounts can transmit customer, invoice, and payment data (for instance, from their source ERP) to leverage the ARC platform for presentment, collaboration, collections/buyer payment via the customer portal, and remittance reconciliation.

Invoice payments made in ARC

Invoice payments made in ARC
GET/api/exports/payment_amounts?watermark={watermark}

Payments made to your supplier account from your customers since watermark, limited to 100 payment amounts at a time.

A consumer should store the last “id” value of each response and include it as the watermark parameter for a subsequent calls.

Example URI

GET /api/exports/payment_amounts?watermark=0
URI Parameters
HideShow
watermark
number (optional) Example: 0

The “id” value to base a subsequent extract of the next 100 payment amounts.

Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
[
  {
    "payment_reference": "PMT12345",
    "invoice_number": "INV0001",
    "date": "2016-08-30",
    "amount": "$125.75",
    "payment_amount": "$250.00",
    "payment_method": "Electronic Payment",
    "short_pay_indicator": "N",
    "payment_note": "Thank you",
    "auto_debit_indicator": "N",
    "invoice_balance": "$15.00",
    "payment_timestamp": "2016-08-30T15:39:30-04:00",
    "invoice_division": "' '",
    "invoice_division_number": "' '",
    "pay_to_bank_account": "123456789",
    "pay_to_bank_account_name": "AR1 - TD Canada Trust (5622)",
    "customer_identifier": "10004",
    "customer_name": "Royal Food Products",
    "status": "PAID",
    "payment_source": "ARC",
    "payment_code": "' '",
    "payment_description": "' '",
    "gateway_authorization_code": "oJ3w2k1",
    "invoice_amount_paid": "$155.75",
    "invoice_identifier": "INV0001",
    "invoice_external_id": "QBO",
    "invoice_currency": "usd"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}
Response  200
HideShow

An array of PaymentAmount:

Headers
Content-Type: application/json; charset=utf-8
Body
{
  "payment_reference": "PMT12345",
  "invoice_number": "INV0001",
  "date": "2016-08-30",
  "amount": "$125.75",
  "payment_amount": "$250.00",
  "payment_method": "Electronic Payment",
  "short_pay_indicator": "N",
  "payment_note": "Thank you",
  "auto_debit_indicator": "N",
  "invoice_balance": "$15.00",
  "payment_timestamp": "2016-08-30T15:39:30-04:00",
  "invoice_division": "' '",
  "invoice_division_number": "' '",
  "pay_to_bank_account": "123456789",
  "pay_to_bank_account_name": "AR1 - TD Canada Trust (5622)",
  "customer_identifier": "10004",
  "customer_name": "Royal Food Products",
  "status": "PAID",
  "payment_source": "ARC",
  "payment_code": "' '",
  "payment_description": "' '",
  "gateway_authorization_code": "oJ3w2k1",
  "invoice_amount_paid": "$155.75",
  "invoice_identifier": "INV0001",
  "invoice_external_id": "QBO",
  "invoice_currency": "usd"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "payment_reference": {
      "type": "string",
      "description": "The payment identifier\n"
    },
    "invoice_number": {
      "type": "string",
      "description": "The display number of the invoice for which the payment was made\n"
    },
    "date": {
      "type": "string",
      "description": "The YYYY-MM-DD payment date\n"
    },
    "amount": {
      "type": "string",
      "description": "The amount of the payment applied to the invoice\n"
    },
    "payment_amount": {
      "type": "string",
      "description": "The amount of the total payment\n"
    },
    "payment_method": {
      "type": "string",
      "description": "The method used to make payment\n"
    },
    "short_pay_indicator": {
      "type": "string",
      "description": "Y if a short payment was made\n"
    },
    "payment_note": {
      "type": "string",
      "description": "Note accompanying the payment\n"
    },
    "auto_debit_indicator": {
      "type": "string",
      "description": "Y if the payment was made via AutoPay agreement\n"
    },
    "invoice_balance": {
      "type": "string",
      "description": "Remaining invoice balance\n"
    },
    "payment_timestamp": {
      "type": "string",
      "description": "The ISO8601 timestamp corresponding to payment\n"
    },
    "invoice_division": {
      "type": "string",
      "description": "The division code if any associated with the invoice\n"
    },
    "invoice_division_number": {
      "type": "string",
      "description": "The division identifier if any associated with the invoice\n"
    },
    "pay_to_bank_account": {
      "type": "string",
      "description": "The GL number of the settlement account receiving the payment\n"
    },
    "pay_to_bank_account_name": {
      "type": "string",
      "description": "The display name of the settlement account receiving the payment\n"
    },
    "customer_identifier": {
      "type": "string",
      "description": "The invoice customer identifier\n"
    },
    "customer_name": {
      "type": "string",
      "description": "The invoice customer name\n"
    },
    "status": {
      "type": "string",
      "description": "The payment status\n"
    },
    "payment_source": {
      "type": "string",
      "description": "The source of the payment\n"
    },
    "payment_code": {
      "type": "string",
      "description": "The back office payment code (applicable to externally sourced payments)\n"
    },
    "payment_description": {
      "type": "string",
      "description": "The back office payment description (applicable to externally sourced payments)\n"
    },
    "gateway_authorization_code": {
      "type": "string",
      "description": "The underlying gateway authorization code\n"
    },
    "invoice_amount_paid": {
      "type": "string",
      "description": "The total amount of payments made to date via ARC towards this invoice\n"
    },
    "invoice_identifier": {
      "type": "string",
      "description": "The identifier of the invoice for which the payment was made\n"
    },
    "invoice_external_id": {
      "type": "string",
      "description": "INV-Z123\n\nThe external identifier/reference, if any, of the invoice for which the payment was made\n"
    },
    "invoice_currency": {
      "type": "string",
      "description": "The currency of the invoice for which the payment was made\n"
    }
  }
}

Open and closed disputes made in ARC

Open and closed disputes made in ARC
GET/api/exports/disputes?watermark={watermark}

Open and closed disputes since watermark, limited to 100 disputes at a time.

Example URI

GET /api/exports/disputes?watermark=2016-01-15
URI Parameters
HideShow
watermark
date (optional) Example: 2016-01-15

The date value to base a subsequent extract of the next 100 disputes.

Response  200
HideShow
Headers
Content-Type: application/json; charset=utf-8
Body
[
  {
    "closed_at": "2016-08-30T15:39:30-04:00",
    "opened_at": "2016-08-30T15:39:30-04:00",
    "opener": "John Smith",
    "closer": "Jane Doe",
    "opening_comment_text": "Defective product",
    "closing_comment_text": "Issued 10% discount",
    "invoice_number": "INV0001",
    "invoice_balance": "$15.00",
    "invoice_amount_paid": "$155.75",
    "invoice_identifier": "INV0001",
    "invoice_external_id": "QBO"
  }
]
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "array"
}
Response  200
HideShow

An array of Dispute:

Headers
Content-Type: application/json; charset=utf-8
Body
{
  "closed_at": "2016-08-30T15:39:30-04:00",
  "opened_at": "2016-08-30T15:39:30-04:00",
  "opener": "John Smith",
  "closer": "Jane Doe",
  "opening_comment_text": "Defective product",
  "closing_comment_text": "Issued 10% discount",
  "invoice_number": "INV0001",
  "invoice_balance": "$15.00",
  "invoice_amount_paid": "$155.75",
  "invoice_identifier": "INV0001",
  "invoice_external_id": "QBO"
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "closed_at": {
      "type": "string",
      "description": "The ISO8601 timestamp corresponding to closing of the dispute\n"
    },
    "opened_at": {
      "type": "string",
      "description": "The ISO8601 timestamp corresponding to opening of the dispute\n"
    },
    "opener": {
      "type": "string",
      "description": "The name of the user opening the dispute\n"
    },
    "closer": {
      "type": "string",
      "description": "The name of the user closing the dispute\n"
    },
    "opening_comment_text": {
      "type": "string",
      "description": "The comment associated with the dispute\n"
    },
    "closing_comment_text": {
      "type": "string",
      "description": "The comment associated with the dispute resolution\n"
    },
    "invoice_number": {
      "type": "string",
      "description": "The display number of the invoice for which the payment was made\n"
    },
    "invoice_balance": {
      "type": "string",
      "description": "Remaining invoice balance\n"
    },
    "invoice_amount_paid": {
      "type": "string",
      "description": "The total amount of payments made to date via ARC towards this invoice\n"
    },
    "invoice_identifier": {
      "type": "string",
      "description": "The identifier of the invoice for which the payment was made\n"
    },
    "invoice_external_id": {
      "type": "string",
      "description": "INV-Z123\n\nThe external identifier/reference, if any, of the invoice for which the payment was made\n"
    }
  }
}

Copyright © 2016Versapay-transparent