kinlane
3/25/2018 - 2:18 AM
VersaPay OpenAPI
VersaPay OpenAPI
{
"swagger" : "2.0",
"info" : {
"description" : "# Introduction\n\nThe VersaPay API offers operations in support of its flagship products:\n* ARC - accounts receivable platform with automated invoicing, effective collaboration, flexible payments and cash application to improve efficiency and customer relationships.\n\n * Importing & exporting customers, invoices, and payments.\n\n * Monitoring file based imports/batches.\n\n* PayPort - cloud based platform to electronically push and pull funds across the EFT / ACH network.\n\n * Moving funds using transactions and pre-authorized debit agreements.\n\n * A secure hosted checkout for accepting payments through your website or email.\n\nPlease contact us at support@versapay.com for support & setup of A/R invoicing integration, hosted checkout, and/or payment acceptance.\n\n## Environments\n\nThe demo environment is a useful sandbox for integration testing where transaction settlements are simulated using test account numbers and test dollar amounts.\n\n`https://demo.versapay.com`\n\nOnce 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.\n\n`https://secure.versapay.com`\n\n## Rate Limits\n\nThere is a 60 request per minute API limit. Any requests above this limit will result in HTTP return code `403 Forbidden (Rate Limit Exceeded)`.\n\n## Access to API Keys\n\nVisit your account settings in [demo](https://demo.versapay.com/account) or [production](https://secure.versapay.com/account) 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.\n\nIf you do not have an account, please contact VersaPay Support for support & setup of AR invoicing integration, hosted checkout and/or payment acceptance.\n\n# Authentication\n\nAPI requests are authenticated using [HTTP Basic Access Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication). Simply provide the token/key values as the user and password parameters, using cURL for instance:\n\n`curl -u \"Nvax...:UN0I...\" -X POST https://secure.versapay.com/api/...`\n\n# Testing Transactions\n\n## EFT Bank Account Numbers\n\nIn the demo environment, the following test bank accounts can be setup up in your account.\n\n|Institution|Institution Number|Branch|Account Number|\n|:--|:--|:--|:--|\n|TD|004|99960|1-12 digits|\n|RBC|003|16824|1-12 digits|\n|BMO|001|99520|1-12 digits|\n|HSBC|016|10880|1-12 digits|\n\nWhen VersaPay prompts you to verify these bank accounts enter a value of `1.23` for the verification amount.\n\nTo determine the outcome of a transaction funded by a bank account, set the amount accordingly:\n\n|Amount|Resulting State|\n|:--|:--|\n|$x.10|nsfed|\n|$x.11|completed_but_nsfed|\n|$x.30|error|\n|anything else|completed|\n\n## ACH Bank Account Numbers\n\nPlease contact support@versapay.com for support & setup of ACH acceptance and bank account numbers that can be used for testing.\n\n## Credit Card Numbers\n\nPlease contact support@versapay.com for support & setup of Credit Card acceptance and card brands/numbers that can be used for testing.\n\n# Tools\n\n## Postman\n\nTry out the API using [Postman app](https://www.getpostman.com/), a powerful REST API client. Download the VersaPay API Reference as a Postman Collection by clicking on the button below:\n\n[](https://app.getpostman.com/run-collection/7e34e0700a2f8c3074c6)\n\nAfter downloading the collection, set up and configure the environment as follows:\n\n1. Download [the sample environment file](https://developers.versapay.com/demo.postman_environment.json).\n\n2. Import the environment file in Postman.\n\n \n\n3. Once it is imported, edit the environment to add API token and keys associated to your test account.\n\n \n\n4. Click Update to save your changes.\n\n5. Before placing API calls, make sure the correct environment is selected.\n\n \n",
"version" : "1.0.3",
"title" : "VersaPay API Reference",
"contact" : {
"name" : "VersaPay Support",
"url" : "https://www.versapay.com/support",
"email" : "support@versapay.com"
},
"x-logo" : {
"url" : "https://developers.versapay.com/images/logo.png"
}
},
"host" : "secure.versapay.com",
"tags" : [ {
"name" : "Fund Sources",
"description" : "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.\n"
}, {
"name" : "Transactions",
"description" : "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.\n\n## Lifecycle\n\nThe lifecycle states of transaction settlement/flow are:\n\n|State|Context|Action to Take|\n|:--|:--|:--|\n|`new`|The initial state for a new transaction.|N/A|\n|`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.|\n|`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.|\n|`wait_for_bank_account_verification`|The requestee has signed up and accepted the transaction, however they have not yet verified their bank account.<br><br>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.|\n|`rejected`|The transaction was rejected by the requestee.|Review the rejection message.|\n|`in_progress`|The transaction has been sent to the bank and is in progress.|N/A|\n|`error`|There was an error while processing the transaction.|Contact your bank if the error pertains to your bank account.<br><br>Contact client or create a new transaction if the error is with the other party’s bank account.|\n|`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.<br><br>Contact client or create a new transaction if the error is with the other party’s bank account.|\n|`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|\n|`completed`|The transaction has been completed successfully.|Update your order to \"Paid\".|\n|`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\".|\n\n## Webhooks\n\nWhen 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.\n"
}, {
"name" : "Agreements",
"description" : "Debit Agreements are a digital analog to paper pre-authorized debit agreements that businesses could use, for instance, for monthly billing.\n\nThe creator of an agreement can cancel at any time. The other party can approve, reject, or later revoke an agreement at any time.\n\n## Lifecycle\n\nThe lifecycle states of debit agreements are:\n\n|State|Context|Action to take|\n|:--|:--|:--|\n|`pending`|The recipient has been sent an email to approve the agreement.|N/A|\n|`approved`|The agreement has been approved.|Create a pre-authorized debit transaction that references the agreement when you bill.|\n|`rejected`|The agreement was rejected by the requestee.|Review the rejection message.|\n|`cancelled`|The agreement was cancelled by the requestor.|Cancel the subscription with the other party.|\n|`revoked`|The agreement was cancelled by the requestee.|Cancel the subscription with the other party.|\n|`wait_for_bank_account_verification`|The associated bank account has not yet been verified.|None - The recipient has been notified.<br><br>Email the recipient if the bank account is not verified within a reasonable amount of time.|\n|`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.<br><br>Email the recipient if the fund is not changed within a reasonable amount of time.|\n\n## Webhooks\n\nWhen 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.\n"
}, {
"name" : "Hosted Checkout",
"description" : "Hosted checkout is a URL based method for accepting a payment through your website or email without the need for custom programming.\n"
}, {
"name" : "Customers"
}, {
"name" : "Invoices"
}, {
"name" : "Payments"
}, {
"name" : "File Imports"
}, {
"name" : "Webhooks",
"description" : "VersaPay uses the [Webhook](http://www.webhooks.org/) 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.\n\nYou can view details for the latest notifications sent to your application by visiting `/developers/webhook_responses` in [demo](https://demo.versapay.com//developers/webhook_responses) or [production](https://secure.versapay.com//developers/webhook_responses).\n\nWebhooks can receive updates for the following:\n\n* 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}`.\n\n* 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}`.\n\nVersaPay will append a [HMAC-SHA256](https://en.wikipedia.org/wiki/HMAC) signature attribute to all webhook notifications. For instance:\n\n```\nPOST http://your.domain.com/your/webhook/url\n{\n \"to_account\":\"Example user\",\n \"token\":\"5TH3ACC3AU21\",\n \"transaction_reference\":\"\",\n \"from_account\":\"First1 Last1\",\n \"from_fund\":\"THE TORONTO-DOMINION BANK\",\n \"transaction_type\":\"send_money\",\n \"amount_in_cents\":500,\n \"type\":\"transaction\",\n \"created_by_user\":\"699cMPe6BAyqvVsZA5mo\",\n \"message\":\"\",\n \"state\":\"completed\",\n \"link_url\":\"\",\n \"email\":\"user@example.com\",\n \"signature\":\"USYpBfZFQQHa2%2BT6UtDPUVFfUPP0aobWpXe5DE9hPOY%3D%0A\"\n}\n```\n\nTo verify the authenticity of received webhook notifications:\n\n1. Generate a single line request string concatenated with new line from:\n \n - The upper cased HTTP verb/method<br>\n - The webhook URL<br>\n - The attribute key/value pairs (without spaces) sorted ascending by key (**excluding the signature attribute**)<br>\n2. 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](https://en.wikipedia.org/wiki/Base64) the result.\n3. [URL Encode](https://www.w3schools.com/tags/ref_urlencode.asp) the HMAC and compare to the value of the `signature` attribute for a match.\n\n```ruby\n# Example of HMAC-SHA256 signature calculation - using Rails/Sinatra our POST payload is accessible via params\n\nrequire 'openssl'\nrequire 'base64'\nrequire 'erb'\n\nwebhook_url = 'http://your.domain.com/your/webhook/url';\nwebhook_signing_key = 'v7aJHjbbxASKiwDW5wq6';\n\noriginal_signature = params.delete(:signature)\nsorted_key_values = params.keys.sort.map{ |key| \"#{key}#{params[key]}\" }.join\n\nrequest_string = \"POST\\n#{webhook_url}\\n#{sorted_key_values}\"\n\nexpected_signature = ERB::Util.url_encode( Base64.encode64( OpenSSL::HMAC.digest(\nOpenSSL::Digest::SHA256.new, webhook_signing_key, request_string\n) ) )\n\nputs \"\\nexpected signature: #{expected_signature}\"\nputs \"\\noriginal signature: #{original_signature}\"\nputs \"\\nauthentic? #{expected_signature == original_signature}\"\n```\n",
"x-traitTag" : true
} ],
"schemes" : [ "https" ],
"consumes" : [ "application/json" ],
"produces" : [ "application/json" ],
"security" : [ {
"basicAuth" : [ ]
} ],
"paths" : {
"/api/funds" : {
"get" : {
"tags" : [ "Fund Sources" ],
"summary" : "View Your Fund Sources",
"operationId" : "getFundSources",
"parameters" : [ ],
"responses" : {
"200" : {
"description" : "Successful Operation",
"schema" : {
"type" : "array",
"example" : [ {
"type" : "bank_account",
"token" : "BA7YQ5881W8Q",
"name" : "TD Canada Trust (2929)",
"state" : "verified"
}, {
"type" : "credit_card",
"token" : "CC7HPKMIUP2D",
"name" : "VISA **2224"
}, {
"type" : "balance",
"token" : "VPB2VJ7W9UVW",
"name" : "VersaPay Account"
} ],
"items" : {
"$ref" : "#/definitions/FundSource"
}
}
},
"401" : {
"description" : "Unauthorized",
"schema" : {
"$ref" : "#/definitions/inline_response_401"
}
}
}
}
},
"/api/transactions" : {
"get" : {
"tags" : [ "Transactions" ],
"summary" : "View Transactions",
"operationId" : "viewAllTransactions",
"parameters" : [ {
"name" : "page",
"in" : "query",
"description" : "50 items are displayed per page.",
"required" : false,
"type" : "integer"
} ],
"responses" : {
"200" : {
"description" : "Successful Operation",
"schema" : {
"type" : "array",
"items" : {
"$ref" : "#/definitions/TransactionResponse"
}
}
},
"401" : {
"description" : "Unauthorized",
"schema" : {
"$ref" : "#/definitions/inline_response_401"
}
}
}
},
"post" : {
"tags" : [ "Transactions" ],
"summary" : "Create Transactions",
"description" : "",
"operationId" : "createTransaction",
"parameters" : [ {
"in" : "body",
"name" : "body",
"description" : "Transaction to create.",
"required" : true,
"schema" : {
"$ref" : "#/definitions/Transaction"
}
} ],
"responses" : {
"201" : {
"description" : "Created",
"schema" : {
"$ref" : "#/definitions/TransactionResponse"
}
},
"401" : {
"description" : "Unauthorized",
"schema" : {
"$ref" : "#/definitions/inline_response_401"
}
},
"412" : {
"description" : "Precondition Failed",
"schema" : {
"type" : "object",
"example" : {
"email" : "can't be blank\n"
},
"additionalProperties" : {
"type" : "string",
"description" : "Error message"
}
}
}
}
}
},
"/api/transactions/{token}" : {
"get" : {
"tags" : [ "Transactions" ],
"summary" : "View a Transaction",
"operationId" : "viewTransaction",
"parameters" : [ {
"name" : "token",
"in" : "path",
"description" : "The transaction identifier.",
"required" : true,
"type" : "string"
} ],
"responses" : {
"200" : {
"description" : "Successful Operation",
"schema" : {
"$ref" : "#/definitions/TransactionResponse"
}
},
"401" : {
"description" : "Unauthorized",
"schema" : {
"$ref" : "#/definitions/inline_response_401"
}
}
}
}
},
"/api/transactions/{token}/approve" : {
"post" : {
"tags" : [ "Transactions" ],
"summary" : "Approve a Transaction",
"description" : "Approve a `new` or `wait_for_request_approval` transaction.<br>\nAn API key with administrative access is required to approve a transaction.\n",
"operationId" : "approveTransaction",
"parameters" : [ {
"name" : "token",
"in" : "path",
"description" : "The transaction identifier.",
"required" : true,
"type" : "string"
}, {
"in" : "body",
"name" : "fund_token",
"required" : false,
"schema" : {
"$ref" : "#/definitions/fund_token"
}
} ],
"responses" : {
"200" : {
"description" : "Successful Operation",
"schema" : {
"$ref" : "#/definitions/TransactionResponse"
}
},
"401" : {
"description" : "Unauthorized",
"schema" : {
"$ref" : "#/definitions/inline_response_401"
}
},
"412" : {
"description" : "Precondition Failed",
"schema" : {
"$ref" : "#/definitions/inline_response_412"
}
}
}
}
},
"/api/transactions/{token}/cancel" : {
"post" : {
"tags" : [ "Transactions" ],
"summary" : "Cancel a Transaction",
"description" : "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`.<br>\nAn API key with administrative access is required to approve a transaction.\n",
"operationId" : "cancelTransaction",
"parameters" : [ {
"name" : "token",
"in" : "path",
"description" : "The transaction identifier.",
"required" : true,
"type" : "string"
} ],
"responses" : {
"200" : {
"description" : "Successful Operation",
"schema" : {
"$ref" : "#/definitions/TransactionResponse"
}
},
"412" : {
"description" : "Precondition Failed",
"schema" : {
"$ref" : "#/definitions/inline_response_412"
}
}
}
}
},
"/api/debit_agreements" : {
"post" : {
"tags" : [ "Agreements" ],
"summary" : "Create an Agreement",
"description" : "",
"operationId" : "createAgreement",
"parameters" : [ {
"in" : "body",
"name" : "body",
"required" : true,
"schema" : {
"$ref" : "#/definitions/body"
}
} ],
"responses" : {
"201" : {
"description" : "Created",
"schema" : {
"$ref" : "#/definitions/Agreement"
}
},
"401" : {
"description" : "Unauthorized",
"schema" : {
"$ref" : "#/definitions/inline_response_401"
}
},
"412" : {
"description" : "Precondition Failed",
"schema" : {
"type" : "object",
"example" : {
"email" : "can't be blank\n"
},
"additionalProperties" : {
"type" : "string",
"description" : "Error message"
}
}
}
}
}
},
"/api/debit_agreements/sent" : {
"get" : {
"tags" : [ "Agreements" ],
"summary" : "View Sent Agreements",
"operationId" : "viewSentAgreements",
"parameters" : [ {
"name" : "page",
"in" : "query",
"description" : "50 items are displayed per page.",
"required" : false,
"type" : "integer"
} ],
"responses" : {
"200" : {
"description" : "Successful Operation",
"schema" : {
"type" : "array",
"items" : {
"$ref" : "#/definitions/Agreement"
}
}
},
"401" : {
"description" : "Unauthorized",
"schema" : {
"$ref" : "#/definitions/inline_response_401"
}
}
}
}
},
"/api/debit_agreements/received" : {
"get" : {
"tags" : [ "Agreements" ],
"summary" : "View Received Agreements",
"operationId" : "viewReceivedAgreements",
"parameters" : [ {
"name" : "page",
"in" : "query",
"description" : "50 items are displayed per page.",
"required" : false,
"type" : "integer"
} ],
"responses" : {
"200" : {
"description" : "Successful Operation",
"schema" : {
"type" : "array",
"items" : {
"$ref" : "#/definitions/Agreement"
}
}
},
"401" : {
"description" : "Unauthorized",
"schema" : {
"$ref" : "#/definitions/inline_response_401"
}
}
}
}
},
"/api/debit_agreements/{token}/approve" : {
"post" : {
"tags" : [ "Agreements" ],
"summary" : "Approve an Agreement",
"operationId" : "approveAgreement",
"parameters" : [ {
"name" : "token",
"in" : "path",
"description" : "The agreement identifier.",
"required" : true,
"type" : "string"
}, {
"in" : "body",
"name" : "fund_token",
"required" : false,
"schema" : {
"$ref" : "#/definitions/fund_token_1"
}
} ],
"responses" : {
"201" : {
"description" : "Created",
"schema" : {
"$ref" : "#/definitions/Agreement"
}
},
"401" : {
"description" : "Unauthorized",
"schema" : {
"$ref" : "#/definitions/inline_response_401"
}
},
"412" : {
"description" : "Precondition Failed",
"schema" : {
"type" : "object",
"example" : {
"error" : "API token does not have permission for this request. Please contact your account administrator.\n"
},
"additionalProperties" : {
"type" : "string",
"description" : "Error message"
}
}
}
}
}
},
"/api/debit_agreements/{token}/cancel" : {
"post" : {
"tags" : [ "Agreements" ],
"summary" : "Cancel an Agreement",
"operationId" : "cancelAgreement",
"parameters" : [ {
"name" : "token",
"in" : "path",
"description" : "The agreement identifier.",
"required" : true,
"type" : "string"
} ],
"responses" : {
"200" : {
"description" : "Successful Operation",
"schema" : {
"$ref" : "#/definitions/Agreement"
}
},
"401" : {
"description" : "Unauthorized",
"schema" : {
"$ref" : "#/definitions/inline_response_401"
}
}
}
}
},
"/api/debit_agreements/{token}/reject" : {
"post" : {
"tags" : [ "Agreements" ],
"summary" : "Reject an Agreement",
"description" : "Reject a *pending* agreement by supplying an agreement's *token* attribute and providing a *rejection_reason*.\n",
"operationId" : "rejectAgreement",
"parameters" : [ {
"name" : "token",
"in" : "path",
"description" : "The agreement identifier.",
"required" : true,
"type" : "string"
} ],
"responses" : {
"200" : {
"description" : "Successful Operation",
"schema" : {
"$ref" : "#/definitions/Agreement"
}
},
"401" : {
"description" : "Unauthorized",
"schema" : {
"$ref" : "#/definitions/inline_response_401"
}
}
}
}
},
"/api/debit_agreements/{token}/revoke" : {
"post" : {
"tags" : [ "Agreements" ],
"summary" : "Revoke an Agreement",
"description" : "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.\n",
"operationId" : "revokeAgreement",
"parameters" : [ {
"name" : "token",
"in" : "path",
"description" : "The agreement identifier.",
"required" : true,
"type" : "string"
} ],
"responses" : {
"200" : {
"description" : "Successful Operation",
"schema" : {
"$ref" : "#/definitions/Agreement"
}
}
}
}
},
"/send_money" : {
"get" : {
"tags" : [ "Hosted Checkout" ],
"summary" : "Single Payment Hosted Checkout",
"description" : "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:\n<br>\n`https://secure.versapay.com/send_money?api_token={your_api_token}&amount={dollar_amount_for_customer_to_pay}`\n<br>\nFunds 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.\n",
"operationId" : "hostedCheckout",
"parameters" : [ {
"name" : "api_token",
"in" : "query",
"description" : "A valid API token generated from your account.",
"required" : true,
"type" : "string"
}, {
"name" : "amount",
"in" : "query",
"description" : "The amount in dollars that the transaction is for.",
"required" : true,
"type" : "number"
}, {
"name" : "message",
"in" : "query",
"description" : "A message which will be stored with the transaction.",
"required" : false,
"type" : "string"
}, {
"name" : "return_to",
"in" : "query",
"description" : "A url which will displayed to the user to return to your website after they finish the Signup and Confirmation.",
"required" : false,
"type" : "string"
}, {
"name" : "link_url",
"in" : "query",
"description" : "A url that gets stored and displayed on the transaction for an invoice.",
"required" : false,
"type" : "string"
}, {
"name" : "pref",
"in" : "query",
"description" : "The preferred payment type either `ba` or `cc` for bank or credit card respectively.",
"required" : false,
"type" : "string"
}, {
"name" : "to_fund",
"in" : "query",
"description" : "The token of the bank account or balance where the funds should go to.",
"required" : false,
"type" : "string"
}, {
"name" : "reference",
"in" : "query",
"description" : "Extra data (max 255 characters). Great for storing internal order or account number.",
"required" : false,
"type" : "string"
}, {
"name" : "locale",
"in" : "query",
"description" : "Set the default language of the checkout, either `en` or `fr`. Users will still be able to switch to their preferred language.",
"required" : false,
"type" : "string"
} ],
"responses" : {
"200" : {
"description" : "Successful Operation"
}
}
}
},
"/authorize" : {
"get" : {
"tags" : [ "Hosted Checkout" ],
"summary" : "Debit Agreement Hosted Checkout",
"description" : "Clients, customers, or donors, for instance, can initiate a pre-authorized debit agreement by clicking a link on your website or in an email.\n<br>\n`https://secure.versapay.com/authorize?api_token={your_api_token}&message={explanation_of_what_this_is_for}`\n<br>\n",
"parameters" : [ {
"name" : "api_token",
"in" : "query",
"description" : "A valid API token generated from your account.",
"required" : true,
"type" : "string"
}, {
"name" : "message",
"in" : "query",
"description" : "A message for the user describing the pre-authorized debit agreement.",
"required" : true,
"type" : "string"
}, {
"name" : "return_to",
"in" : "query",
"description" : "A url which will displayed to the user to return to your website after they finish the Signup and Confirmation.",
"required" : false,
"type" : "string"
}, {
"name" : "reference",
"in" : "query",
"description" : "Extra data (max 255 characters). Great for storing internal order or account number.",
"required" : false,
"type" : "string"
} ],
"responses" : {
"200" : {
"description" : "Successful Operation"
}
}
}
},
"/api/imports/customer" : {
"post" : {
"tags" : [ "Customers" ],
"summary" : "Create and Update Customer",
"description" : "Create a customer in ARC using the following attributes (at minimum by providing values for required attributes). If providing an identifier for an existing customer, its information is updated.<br><br>\n*Note: Any additional non-standard attribute will be stored with customer record and available for presentment rendering.*\n",
"operationId" : "createCustomer",
"parameters" : [ {
"in" : "body",
"name" : "body",
"required" : true,
"schema" : {
"$ref" : "#/definitions/Customer"
}
} ],
"responses" : {
"201" : {
"description" : "Created",
"schema" : {
"$ref" : "#/definitions/inline_response_201"
}
},
"401" : {
"description" : "Unauthorized",
"schema" : {
"$ref" : "#/definitions/inline_response_401"
}
},
"412" : {
"description" : "Precondition Failed",
"schema" : {
"type" : "object",
"example" : {
"email" : "can't be blank\n"
},
"additionalProperties" : {
"type" : "string",
"description" : "Error message"
}
}
}
}
}
},
"/api/imports/invoice" : {
"post" : {
"tags" : [ "Invoices" ],
"summary" : "Create and Update Invoice",
"description" : "Create and update invoices in ARC. If the invoice already exists when a request is processed, it will be updated.<br><br>\nThe set of attributes to send in the request body may vary based on the account configuration. Please contact the implementation specialist for more information.<br><br>\n*Note:*\n * *Customer will be created/updated using the customer_* attributes if necessary at time of invoice import.*\n * *Any additional non-standard attribute will be stored with invoice record and available for presentment rendering.*\n",
"operationId" : "createInvoice",
"parameters" : [ {
"in" : "body",
"name" : "body",
"required" : true,
"schema" : {
"$ref" : "#/definitions/Invoice"
}
} ],
"responses" : {
"201" : {
"description" : "Created",
"schema" : {
"$ref" : "#/definitions/inline_response_201_1"
}
},
"401" : {
"description" : "Unauthorized",
"schema" : {
"$ref" : "#/definitions/inline_response_401"
}
},
"412" : {
"description" : "Precondition Failed",
"schema" : {
"type" : "object",
"example" : {
"email" : "can't be blank\n"
},
"additionalProperties" : {
"type" : "string",
"description" : "Error message"
}
}
}
}
}
},
"/api/imports/payment" : {
"post" : {
"tags" : [ "Payments" ],
"summary" : "Create a Payment",
"description" : "Create and update external payment records in ARC.<br><br>The set of attributes to send in the request body may vary based on the account configuration. Please contact the implementation specialist for more information.<br><br>\nThe request schema for posting a payment for a single invoice is slightly different than that for posting a payment for multiple invoices.\n\nFor instance, sample request for posting payment for a single invoice looks like:\n```\n{\n \"identifier\": \"PMT0010-05\",\n \"invoice_number\": \"INV1234-01\",\n \"amount\": 10000,\n \"currency\": \"usd\",\n \"date\": \"2018-01-10\",\n \"customer_identifier\": \"C1234\",\n \"customer_name\": \"Acme Inc.\",\n \"notes\": \"Notes\",\n \"ref1\": \"1234\",\n \"ref2\": \"PO# 84767\"\n}\n```\n\n*Note: Customer will be created using the customer_* attributes if it doesn’t already exist at the time of payment import.*\n",
"operationId" : "createPayment",
"parameters" : [ {
"in" : "body",
"name" : "body",
"required" : true,
"schema" : {
"$ref" : "#/definitions/PaymentImport"
}
} ],
"responses" : {
"201" : {
"description" : "Created",
"schema" : {
"$ref" : "#/definitions/inline_response_201_2"
}
},
"401" : {
"description" : "Unauthorized",
"schema" : {
"$ref" : "#/definitions/inline_response_401"
}
},
"412" : {
"description" : "Precondition Failed",
"schema" : {
"type" : "object",
"example" : {
"email" : "can't be blank\n"
},
"additionalProperties" : {
"type" : "string",
"description" : "Error message"
}
}
}
}
}
},
"/api/imports" : {
"get" : {
"tags" : [ "File Imports" ],
"summary" : "View In-Progress & Completed Batches",
"description" : "View recent in-progress and completed import batches.",
"operationId" : "viewAllBatches",
"parameters" : [ {
"name" : "page",
"in" : "query",
"description" : "50 items are displayed per page.",
"required" : false,
"type" : "integer"
} ],
"responses" : {
"200" : {
"description" : "Successful Operation",
"schema" : {
"type" : "array",
"items" : {
"$ref" : "#/definitions/FileImport"
}
}
},
"401" : {
"description" : "Unauthorized",
"schema" : {
"$ref" : "#/definitions/inline_response_401"
}
}
}
},
"post" : {
"tags" : [ "File Imports" ],
"summary" : "Import a CSV File",
"description" : "When uploading a CSV-formatted file it’s helpful to use your language/framework tooling to simplify the [multipart/form-data](https://www.ietf.org/rfc/rfc2388.txt) file upload.\n### Size Limit\nThe file cannot exceed 25MB.\n### Layouts\nPlease contact support@versapay.com or reach out to your implementation specialist for standard inbound CSV file layouts.\n",
"operationId" : "importBatchFile",
"consumes" : [ "multipart/form-data" ],
"parameters" : [ {
"name" : "file",
"in" : "formData",
"description" : "The file to upload.",
"required" : true,
"type" : "file"
}, {
"name" : "filename",
"in" : "formData",
"description" : "Name of original file.",
"required" : false,
"type" : "string"
} ],
"responses" : {
"201" : {
"description" : "Created",
"schema" : {
"$ref" : "#/definitions/FileImport"
}
},
"401" : {
"description" : "Unauthorized",
"schema" : {
"$ref" : "#/definitions/inline_response_401"
}
}
},
"x-code-samples" : [ {
"lang" : "cURL",
"source" : "curl \\\n-u \"Nvax...:UN0I...\" \\\n-F \"filename=data.csv\" \\\n-F \"file=@/home/user/Desktop/data.csv\" \\\nhttps://secure.versapay.com/api/imports/\n"
}, {
"lang" : "Ruby",
"source" : "file = { :file => File.new('/home/user/Desktop/data.csv') }\nauth = { :basic_auth => { :username => 'Nvax...', :password => 'UN0I...' } }\nHTTMultiParty.post('https://secure.versapay.com/api/imports/', auth.merge( :query => file ))\n"
} ]
}
},
"/api/imports/processing" : {
"get" : {
"tags" : [ "File Imports" ],
"summary" : "View In-Progress Batches",
"description" : "View only recent in-progress import batches.",
"operationId" : "viewInProgressBatches",
"parameters" : [ {
"name" : "page",
"in" : "query",
"description" : "50 items are displayed per page.",
"required" : false,
"type" : "integer"
} ],
"responses" : {
"200" : {
"description" : "Successful Operation",
"schema" : {
"type" : "array",
"items" : {
"$ref" : "#/definitions/FileImport"
}
}
},
"401" : {
"description" : "Unauthorized",
"schema" : {
"$ref" : "#/definitions/inline_response_401"
}
}
}
}
},
"/api/imports/completed" : {
"get" : {
"tags" : [ "File Imports" ],
"summary" : "View Completed Batches",
"description" : "View only recent completed import batches.",
"operationId" : "viewCompletedBatches",
"parameters" : [ {
"name" : "page",
"in" : "query",
"description" : "50 items are displayed per page.",
"required" : false,
"type" : "integer"
} ],
"responses" : {
"200" : {
"description" : "Successful Operation",
"schema" : {
"type" : "array",
"items" : {
"$ref" : "#/definitions/FileImport"
}
}
},
"401" : {
"description" : "Unauthorized",
"schema" : {
"$ref" : "#/definitions/inline_response_401"
}
}
}
}
},
"/api/imports/{id}" : {
"get" : {
"tags" : [ "File Imports" ],
"summary" : "View Batch Details",
"operationId" : "viewBatchDetail",
"parameters" : [ {
"name" : "id",
"in" : "path",
"description" : "The import batch identifier.",
"required" : true,
"type" : "string"
} ],
"responses" : {
"200" : {
"description" : "Successful Operation",
"schema" : {
"$ref" : "#/definitions/FileImport"
}
},
"401" : {
"description" : "Unauthorized",
"schema" : {
"$ref" : "#/definitions/inline_response_401"
}
}
}
}
},
"/api/exports/payment_amounts" : {
"get" : {
"tags" : [ "Payments" ],
"summary" : "Payments made in ARC",
"description" : "Payments made to your supplier account from your customers since watermark, limited to 100 payment amounts at a time.<br><br>A consumer should store the last `id` value of each response and include it as the watermark parameter for a subsequent calls.\n",
"operationId" : "getARCPayments",
"parameters" : [ {
"name" : "watermark",
"in" : "query",
"description" : "The `id` value to base a subsequent extract of the next 100 payment amounts.",
"required" : false,
"type" : "integer"
} ],
"responses" : {
"200" : {
"description" : "Successful Operation",
"schema" : {
"$ref" : "#/definitions/inline_response_200"
},
"examples" : {
"application/json" : "{\n \"payment_amounts\": {\n \"1591737\": {\n \"payment_reference\": \"4TQRLRCHY7TT\",\n \"invoice_number\": \"INV001\",\n \"date\": \"2017-12-16\",\n \"amount\": \"10.00\",\n \"plan_fee\": \"0.00\",\n \"payment_amount\": \"10.00\",\n \"payment_transaction_amount\": \"10.00\",\n \"payment_method\": \" (6567)\",\n \"payment_from_bank_account\": true,\n \"payment_from_credit_card\": false,\n \"payment_institution_name\": null,\n \"payment_credit_card_brand\": null,\n \"short_pay_indicator\": \"Y\",\n \"payment_note\": \"short payment\",\n \"auto_debit_indicator\": \"N\",\n \"invoice_balance\": \"140.00\",\n \"payment_timestamp\": \"2017-12-16T20:18:30-05:00\",\n \"invoice_division\": null,\n \"invoice_division_number\": null,\n \"invoice_division_name\": null,\n \"pay_to_bank_account\": \"300987898\",\n \"pay_to_bank_account_name\": \" (7898)\",\n \"customer_identifier\": \"CUS001\",\n \"customer_name\": \"Acme Inc.\",\n \"status\": \"PAID\",\n \"payment_source\": \"ARC\",\n \"payment_code\": null,\n \"payment_description\": null,\n \"gateway_authorization_code\": \"TM0FED\",\n \"purchase_order_number\": null,\n \"ref1\": null,\n \"ref2\": null,\n \"ref3\": null,\n \"short_pay_reason_identifier\": null,\n \"short_pay_reason\": null,\n \"invoice_amount_paid\": \"30.00\",\n \"invoice_identifier\": \"supplier|INV001\",\n \"invoice_date\": \"2017-11-01\",\n \"invoice_external_id\": null,\n \"invoice_currency\": \"usd\",\n \"invoice_purchase_order_number\": \"PO-3847\",\n \"invoice_ref1\": null,\n \"invoice_ref2\": null,\n \"invoice_ref3\": null,\n \"cumulative_customer_amount\": \"10.00\"\n }\n }\n}\n"
}
},
"401" : {
"description" : "Unauthorized",
"schema" : {
"$ref" : "#/definitions/inline_response_401"
}
}
}
}
},
"/api/exports/disputes" : {
"get" : {
"tags" : [ "Invoices" ],
"summary" : "Open and Closed Disputes",
"description" : "Open and closed disputes since watermark, limited to 100 disputes at a time.",
"operationId" : "getDisputes",
"parameters" : [ {
"name" : "watermark",
"in" : "query",
"description" : "The date value to base a subsequent extract of the next 100 disputes.",
"required" : false,
"type" : "string"
} ],
"responses" : {
"200" : {
"description" : "Successful Operation",
"schema" : {
"$ref" : "#/definitions/Dispute"
},
"examples" : {
"application/json" : "{ \"disputes\":\n { \"518\": { \n \"closed_at\": \"2018-01-01T13:06:56-05:00\",\n \"opened_at\": \"2017-12-16T20:44:37-05:00\",\n \"opener\": \"customer@example.com\",\n \"closer\": \"supplier@example.com\",\n \"opening_comment_text\": \"Damaged goods. Please correct the amount.\",\n \"closing_comment_text\": \"Invoice will be credited. Please pay the rest.\",\n \"invoice_number\": \"INV001\",\n \"invoice_balance\": {\n \"usd\": 12000\n },\n \"dispute_reason_identifier\": null,\n \"dispute_reason_label_en\": \"\",\n \"dispute_reason_label_fr\": \"\",\n \"opening_comment_users_notified\": [],\n \"closing_comment_user_notified\": [],\n \"creator_business_name\": \"Acme Inc.\",\n \"closer_business_name\": \"Supplier Corp.\",\n \"invoice_amount_paid\": \"30.00\",\n \"invoice_identifier\":\"supplier|INV001\",\n \"invoice_external_id\": null\n }\n }\n}\n"
}
},
"401" : {
"description" : "Unauthorized",
"schema" : {
"$ref" : "#/definitions/inline_response_401"
}
}
}
}
}
},
"securityDefinitions" : {
"basicAuth" : {
"type" : "basic"
}
},
"definitions" : {
"FundSource" : {
"type" : "object",
"properties" : {
"type" : {
"type" : "string",
"description" : "Type of fund:\n * `bank_account` - Bank Account\n * `credit_card` - Credit Card\n * `balance` - VersaPay Account\n",
"enum" : [ "bank_account", "credit_card", "balance" ]
},
"token" : {
"type" : "string",
"description" : "Fund's unique identifier used to identify fund when using other API calls."
},
"name" : {
"type" : "string",
"description" : "Masked display name of the fund source."
},
"state" : {
"type" : "string",
"description" : "Returned for bank accounts only.",
"enum" : [ "verified", "unverified", "invalid" ]
}
}
},
"Transaction" : {
"type" : "object",
"required" : [ "amount_in_cents", "email", "transaction_type" ],
"properties" : {
"transaction_type" : {
"type" : "string"
},
"amount_in_cents" : {
"type" : "integer",
"description" : "Transaction amount in cents."
},
"email" : {
"type" : "string",
"format" : "email",
"description" : "Recipient email address."
},
"message" : {
"type" : "string",
"description" : "A message describing the transaction."
},
"transaction_reference" : {
"type" : "string",
"description" : "Extra useful data to help link transactions to other systems e.g. PO numbers, account numbers etc."
},
"unique_reference" : {
"type" : "string",
"description" : "Similar to transaction_reference, except it must be unique. Can be used as a duplicate transaction check."
},
"process_on" : {
"type" : "string",
"format" : "date",
"description" : "The date `YYYY-MM-DD` when this transaction should be started."
},
"auto_withdraw" : {
"type" : "boolean",
"description" : "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."
}
},
"example" : {
"transaction_type" : "send",
"amount_in_cents" : 20000,
"email" : "bob@example.com",
"message" : "Thank you",
"transaction_reference" : "Order 3487",
"process_on" : "2018-01-05",
"fund_token" : "BA9G329DNFPK"
},
"x-extendedDiscriminator" : "transaction_type"
},
"SendTransaction" : {
"allOf" : [ {
"$ref" : "#/definitions/Transaction"
}, {
"properties" : {
"transaction_type" : {
"type" : "string",
"enum" : [ "send" ]
},
"debit_agreement_token" : {
"type" : "string",
"description" : "The token that represents a pre-authorized agreement, see Agreements."
},
"fund_token" : {
"type" : "string",
"description" : "Token of fund to use as the source."
},
"credit" : {
"type" : "boolean",
"description" : "Set `true` to send money with VersaPay credit. Your account must be credit enabled."
},
"link_url" : {
"type" : "string",
"description" : "A specified url associated with transaction for instance linking to an invoice."
}
}
} ]
},
"RequestTransaction" : {
"allOf" : [ {
"$ref" : "#/definitions/Transaction"
}, {
"properties" : {
"transaction_type" : {
"type" : "string",
"enum" : [ "request" ]
},
"debit_agreement_token" : {
"type" : "string",
"description" : "The token that represents a pre-authorized agreement, see Agreements."
},
"fund_token" : {
"type" : "string",
"description" : "Token of fund to use as the destination."
},
"link_url" : {
"type" : "string",
"description" : "A specified url associated with transaction for instance linking to an invoice."
}
}
} ]
},
"DirectDebitTransaction" : {
"allOf" : [ {
"$ref" : "#/definitions/Transaction"
}, {
"properties" : {
"transaction_type" : {
"type" : "string",
"enum" : [ "direct_debit" ]
},
"fund_token" : {
"type" : "string",
"description" : "Token of fund to use as the destination direct_debit."
},
"memo" : {
"type" : "string",
"description" : "Memo displayed on customer banking statement."
},
"business_name" : {
"type" : "string",
"description" : "Required if first_name and last_name are omitted."
},
"first_name" : {
"type" : "string",
"description" : "First name of recipient."
},
"last_name" : {
"type" : "string",
"description" : "Last name of recipient."
},
"to_fund_token" : {
"type" : "string",
"description" : "May be provided instead of destination bank numbers on subsequent transactions when `transaction_type` is `direct_credit`."
},
"from_fund_token" : {
"type" : "string",
"description" : "May be provided instead of source bank numbers on subsequent transactions when `transaction_type` is `direct_debit`."
},
"institution_number" : {
"type" : "string",
"description" : "Canadian Bank Account institution number. 3 digits. Required for new funding sources. Omitted if using `to_fund_token`/`from_fund_token` instead.",
"minLength" : 3,
"maxLength" : 3
},
"branch_number" : {
"type" : "string",
"description" : "Canadian Bank Account branch number. Between 4-5 digits. Required for new funding sources. Omitted if using `to_fund_token`/`from_fund_token` instead.",
"minLength" : 4,
"maxLength" : 5
},
"account_number" : {
"type" : "string",
"description" : "US or Canadian Bank Account number. Between 1-12 digits Required for new funding sources. Omitted if using `to_fund_token`/`from_fund_token` instead.",
"minLength" : 1,
"maxLength" : 12
},
"routing_number" : {
"type" : "string",
"description" : "US Bank Account routing number. Required for new funding sources. Omitted if using `to_fund_token`/`from_fund_token` instead."
},
"account_type" : {
"type" : "string",
"description" : "US Bank Account type `checking` or `savings`. Required for new funding sources. Omitted if using `to_fund_token`/`from_fund_token` instead.",
"enum" : [ "checking", "savings" ]
}
}
} ]
},
"DirectCreditTransaction" : {
"allOf" : [ {
"$ref" : "#/definitions/Transaction"
}, {
"properties" : {
"transaction_type" : {
"type" : "string",
"enum" : [ "direct_credit" ]
},
"fund_token" : {
"type" : "string",
"description" : "Token of fund to use as the source direct_credit."
},
"memo" : {
"type" : "string",
"description" : "Memo displayed on customer banking statement."
},
"business_name" : {
"type" : "string",
"description" : "Required if first_name and last_name are omitted."
},
"first_name" : {
"type" : "string",
"description" : "First name of recipient."
},
"last_name" : {
"type" : "string",
"description" : "Last name of recipient."
},
"to_fund_token" : {
"type" : "string",
"description" : "May be provided instead of destination bank numbers on subsequent transactions when `transaction_type` is `direct_credit`."
},
"from_fund_token" : {
"type" : "string",
"description" : "May be provided instead of source bank numbers on subsequent transactions when `transaction_type` is `direct_debit`."
},
"routing_number" : {
"type" : "string",
"description" : "US Bank Account routing number. Required for new funding sources. Omitted if using `to_fund_token`/`from_fund_token` instead."
},
"account_type" : {
"type" : "string",
"description" : "US Bank Account type `checking` or `savings`. Required for new funding sources. Omitted if using `to_fund_token`/`from_fund_token` instead.",
"enum" : [ "checking", "savings" ]
},
"institution_number" : {
"type" : "string",
"description" : "Canadian Bank Account institution number. 3 digits. Required for new funding sources. Omitted if using `to_fund_token`/`from_fund_token` instead.",
"minLength" : 3,
"maxLength" : 3
},
"branch_number" : {
"type" : "string",
"description" : "Canadian Bank Account branch number. Between 4-5 digits. Required for new funding sources. Omitted if using `to_fund_token`/`from_fund_token` instead.",
"minLength" : 4,
"maxLength" : 5
},
"account_number" : {
"type" : "string",
"description" : "US or Canadian Bank Account number. Between 1-12 digits Required for new funding sources. Omitted if using `to_fund_token`/`from_fund_token` instead.",
"minLength" : 1,
"maxLength" : 12
}
}
} ]
},
"TransactionResponse" : {
"type" : "object",
"properties" : {
"token" : {
"type" : "string",
"description" : "The transaction identifier."
},
"amount_in_cents" : {
"type" : "integer",
"description" : "Transaction amount in cents."
},
"email" : {
"type" : "string",
"description" : "Recipient email address."
},
"message" : {
"type" : "string",
"description" : "A message describing the transaction."
},
"state" : {
"type" : "string",
"description" : "Transactions current state, see Transaction Lifecycle.",
"enum" : [ "new", "wait_for_claim", "wait_for_request_approval", "wait_for_bank_account_verification", "rejected", "in_progress", "error", "nsfed", "cancelled", "completed", "completed_but_nsfed" ]
},
"from_account" : {
"type" : "string",
"description" : "Name of the originating account."
},
"to_account" : {
"type" : "string",
"description" : "Name of the recipient account."
},
"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"
},
"transaction_reference" : {
"type" : "string",
"description" : "Reference value associated with the transaction."
},
"unique_reference" : {
"type" : "string",
"description" : "Similar to transaction_reference, except it must be unique. Can be used as a duplicate transaction check."
},
"link_url" : {
"type" : "string",
"description" : "A specified url associated with transaction."
},
"process_on" : {
"type" : "string",
"description" : "The YYYY-MM-DD date when this transaction will be started."
},
"created_by_user" : {
"type" : "string",
"format" : "uuid"
},
"auto_withdraw" : {
"type" : "boolean",
"description" : "If `true` then the transaction will be auto withdrawn the night of completion.\n"
},
"auto_withdrawal_token" : {
"type" : "string"
}
},
"example" : {
"token" : "79VMZNLXCBL9",
"amount_in_cents" : 15000,
"message" : "Thank you for doing business",
"link_url" : "http://a.link.to/your/invoice",
"type" : "transaction",
"transaction_type" : "send_money",
"email" : "bob.smith@example.com",
"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"
}
},
"Agreement" : {
"type" : "object",
"properties" : {
"token" : {
"type" : "string",
"description" : "The agreement identifier."
},
"state" : {
"type" : "string",
"description" : "Transaction's current state, see Transaction Lifecycle."
},
"email" : {
"type" : "string",
"description" : "Recipient email address."
},
"name" : {
"type" : "string",
"description" : "Recipient name."
},
"created_by_user" : {
"type" : "string",
"description" : "Name of the user otherwise the API token appears if the transaction was created with the api."
},
"created_by_account" : {
"type" : "string",
"description" : "Account name of the user otherwise the API token appears if the transaction was created with the api."
},
"reference" : {
"type" : "string",
"description" : "An optional reference."
},
"message" : {
"type" : "string",
"description" : "A message describing the agreement."
},
"rejection_reason" : {
"type" : "string",
"description" : "Message for the creator of an agreement. Set when state is `rejected`.\n"
},
"type" : {
"type" : "string",
"description" : "Type of agreement - `debit_agreement`.\n"
}
},
"example" : {
"token" : "3TJWJB36M973",
"state" : "pending",
"name" : "John Doe",
"email" : "user@example.com",
"reference" : "Ad 123",
"message" : "Thank you for your business",
"type" : "debit_agreement",
"created_by_user" : "Uf6TaxzBMBBT_rXjsrN7",
"created_by_account" : "Central Media News"
}
},
"Customer" : {
"type" : "object",
"required" : [ "identifier", "name" ],
"properties" : {
"identifier" : {
"type" : "string",
"example" : "C1234",
"description" : "Customer number, must be unique within supplier. Alphanumeric."
},
"name" : {
"type" : "string",
"example" : "Acme Inc.",
"description" : "Customer name."
},
"email" : {
"type" : "string",
"format" : "email",
"example" : "bob.smith@example.com",
"description" : "Email address of the primary contact."
},
"first_name" : {
"type" : "string",
"example" : "Bob",
"description" : "First name of the primary contact."
},
"last_name" : {
"type" : "string",
"example" : "Smith",
"description" : "Last name of the primary contact."
},
"notes" : {
"type" : "string",
"example" : "Payment terms will be revised next year.",
"description" : "Optional text field up to 64K."
},
"address_1" : {
"type" : "string",
"example" : "200 Main Street",
"description" : "Billing address line 1."
},
"address_2" : {
"type" : "string",
"example" : "Suite 250",
"description" : "Billing address line 2."
},
"city" : {
"type" : "string",
"example" : "Toronto",
"description" : "Billing address - city."
},
"province" : {
"type" : "string",
"example" : "ON",
"description" : "Billing address - state or province."
},
"postal_code" : {
"type" : "string",
"example" : "M5M 5M5",
"description" : "Billing address - zip or postal code."
},
"country" : {
"type" : "string",
"example" : "CA",
"description" : "Billing address - country."
},
"telephone" : {
"type" : "string",
"example" : "(416) 123-4567",
"description" : "Customer phone number."
},
"fax" : {
"type" : "string",
"example" : "(416) 100-1020",
"description" : "Customer fax number."
},
"url" : {
"type" : "string",
"format" : "uri",
"example" : "www.acmeinc.com",
"description" : "Customer web site."
},
"business_number" : {
"type" : "string",
"example" : "GS324587987",
"description" : "Customer EIN or Business Number. 20-character alphanumeric."
},
"locale" : {
"type" : "string",
"description" : "Customer language, based on ISO 639-1 standard.",
"enum" : [ "en", "fr" ]
},
"parent_identifier" : {
"type" : "string",
"example" : "P3212",
"description" : "Required if the customer is part of a hierarchy, and this customer has a level (parent) above it. This is the identifier of the customer immediately above this customer in the tree."
},
"pdf_attachment_opt_in" : {
"type" : "boolean",
"description" : "If `true`, the customer will receive PDFs of invoices and attachments with all invoice notifications.",
"default" : false
},
"account_status" : {
"type" : "string",
"description" : "The status of the customer's account with the supplier.",
"enum" : [ "open", "closed", "on_hold" ],
"default" : "open"
},
"last_contact_date" : {
"type" : "string",
"format" : "date",
"example" : "2017-12-04",
"description" : "The last time the customer was contacted. It is ignored if the customer already has a last contact date and it is more recent than this one."
},
"next_contact_date" : {
"type" : "string",
"format" : "date",
"example" : "2018-02-15",
"description" : "The date of the next planned contact with the customer. This always overwrites what is on the customer."
},
"credit_limit_cents" : {
"type" : "integer",
"example" : 2000000,
"description" : "The customer's credit limit. This is the maximum value of outstanding invoices before the supplier is alerted, if supplier is configured to monitor this. If the customer is a multi-currency customer, this is the total credit limit converted to a single currency (see next field.)"
},
"credit_limit_currency" : {
"type" : "string",
"example" : "CAD",
"description" : "Currency of the credit limit. If blank, defaults to the currency of the majority of the customer's invoices. If there are no invoices, defaults to the supplier’s default currency."
},
"credit_rating" : {
"type" : "string",
"example" : "AA",
"description" : "Credit rating for the customer."
},
"terms_type" : {
"type" : "string",
"description" : "This field and `terms_value` specify how to set a customer's due date.",
"enum" : [ "date", "day" ]
},
"terms_value" : {
"type" : "integer",
"example" : 15,
"description" : "This field and `terms_type` specify how to set a customer's invoice due date.\n\nIf terms_type is 'day':\n\n* It means the due date should be <terms_value> days after invoice date.\n* E.g. if terms_value is 30, the due date must be 30 days after the invoice date.\n* It must be a whole number between 0 and 100.\n\nIf terms_type is 'date':\n\n* It means the due date is on a fixed day (terms_value) of the month.\n* E.g. if terms_value is 15, it means the due date should be on the 15th of the month after invoice date.\n* It must be an integer between 1 and 27 inclusive, or -1 to specify the last day of the month, or -2 to specify the second-last day of the month.\n"
},
"company_bio" : {
"type" : "string",
"example" : "Acme Inc. sells cutting-edge widgets.",
"description" : "Short description of products and services that the customer offers."
},
"ignores_cc_payment_rules" : {
"type" : "boolean",
"example" : false,
"description" : "If this is `true`, it means that the customer is not subject to any credit card payment rules, and is free to use credit cards any time.",
"default" : false
},
"tags" : {
"type" : "string",
"example" : "Blue;Green;Yellow",
"description" : "One or more tags separated by semi-colons."
},
"line_item_attributes" : {
"type" : "array",
"example" : [ {
"email" : "jane.smith@example.com",
"first_name" : "Jane",
"last_name" : "Smith",
"telephone" : "809-888-1234",
"title" : "Buyer"
}, {
"email" : "bob.smith@example.com",
"first_name" : "Bob",
"last_name" : "Smith",
"title" : "Manager",
"department" : "Accounts Payable",
"telephone" : "809-345-9833"
}, {
"email" : "steve.jobs@example.com",
"first_name" : "Steve",
"last_name" : "Jobs",
"title" : "CEO"
} ],
"items" : {
"$ref" : "#/definitions/Contact"
}
}
},
"example" : {
"country" : "CA",
"notes" : "Payment terms will be revised next year.",
"city" : "Toronto",
"address_1" : "200 Main Street",
"ignores_cc_payment_rules" : false,
"address_2" : "Suite 250",
"account_status" : "open",
"locale" : "en",
"credit_limit_currency" : "CAD",
"terms_value" : 15,
"province" : "ON",
"fax" : "(416) 100-1020",
"first_name" : "Bob",
"email" : "bob.smith@example.com",
"next_contact_date" : "2018-02-15",
"parent_identifier" : "P3212",
"identifier" : "C1234",
"line_item_attributes" : [ {
"email" : "jane.smith@example.com",
"first_name" : "Jane",
"last_name" : "Smith",
"telephone" : "809-888-1234",
"title" : "Buyer"
}, {
"email" : "bob.smith@example.com",
"first_name" : "Bob",
"last_name" : "Smith",
"title" : "Manager",
"department" : "Accounts Payable",
"telephone" : "809-345-9833"
}, {
"email" : "steve.jobs@example.com",
"first_name" : "Steve",
"last_name" : "Jobs",
"title" : "CEO"
} ],
"business_number" : "GS324587987",
"last_name" : "Smith",
"telephone" : "(416) 123-4567",
"url" : "www.acmeinc.com",
"pdf_attachment_opt_in" : false,
"tags" : "Blue;Green;Yellow",
"terms_type" : "date",
"company_bio" : "Acme Inc. sells cutting-edge widgets.",
"credit_rating" : "AA",
"last_contact_date" : "2017-12-04",
"name" : "Acme Inc.",
"postal_code" : "M5M 5M5",
"credit_limit_cents" : 2000000
}
},
"Contact" : {
"type" : "object",
"required" : [ "email" ],
"properties" : {
"email" : {
"type" : "string",
"format" : "email",
"description" : "Email address of the contact."
},
"first_name" : {
"type" : "string",
"description" : "First name of the contact."
},
"last_name" : {
"type" : "string",
"description" : "Last name of the contact."
},
"title" : {
"type" : "string",
"description" : "Title of the contact."
},
"department" : {
"type" : "string",
"description" : "Department of the contact."
},
"telephone" : {
"type" : "string",
"description" : "Phone number of the contact."
}
}
},
"Invoice" : {
"type" : "object",
"required" : [ "customer_identifier", "number" ],
"properties" : {
"number" : {
"type" : "string",
"description" : "Invoice number, must be unique within supplier."
},
"display_number" : {
"type" : "string",
"description" : "Invoice number as displayed to customers. Optional if this is the same as `number`.\n"
},
"currency" : {
"type" : "string",
"description" : "Currency code, based on ISO-4217. E.g. `CAD`, `USD`, `AUD`"
},
"amount" : {
"type" : "integer",
"description" : "The invoice amount in cents."
},
"subtotal_tax1" : {
"type" : "integer",
"description" : "Tax amount in cents."
},
"subtotal_tax2" : {
"type" : "integer",
"description" : "Additional field to carry tax amount (in cents). For example, when invoice shows state (provincial) and federal taxes."
},
"customer_identifier" : {
"type" : "string",
"description" : "Unique identifier for customer."
},
"date" : {
"type" : "string",
"format" : "date",
"description" : "Invoice date, YYYY-MM-DD, based on ISO-8601."
},
"order_date" : {
"type" : "string",
"format" : "date",
"description" : "Order date, YYYY-MM-DD."
},
"due_date" : {
"type" : "string",
"format" : "date",
"description" : "Invoice due date, YYYY-MM-DD."
},
"purchase_order_number" : {
"type" : "string",
"description" : "Purchase order number."
},
"notes" : {
"type" : "string",
"description" : "Optional text field up to 64K."
},
"shipping_name" : {
"type" : "string",
"description" : "Shipping address: recipient name"
},
"shipping_address_1" : {
"type" : "string",
"description" : "Shipping address: line 1"
},
"shipping_address_2" : {
"type" : "string",
"description" : "Shipping address: line 2"
},
"shipping_city" : {
"type" : "string",
"description" : "Shipping address: city"
},
"shipping_province" : {
"type" : "string",
"description" : "Shipping address: state or province. Based on the second part (after hyphen) of codes in ISO 3166-2 standard. E.g. \"ON\" for Ontario, \"CA\" for California"
},
"shipping_postal_code" : {
"type" : "string",
"description" : "Shipping address: zip or postal code"
},
"line_item_attributes" : {
"type" : "array",
"description" : "Details of each line-item for the invoice. Any additional non-standard attribute will be stored with the line-item record and available for presentment rendering.",
"items" : {
"$ref" : "#/definitions/LineItem"
}
},
"auto_debit" : {
"type" : "string",
"description" : "`Y` (invoice is to be auto-paid if customer has pre-authorized payment) or `N` (invoice is to be paid manually by customer)\n",
"enum" : [ "Y", "N" ]
},
"division" : {
"type" : "string",
"description" : "Division Code. Required only if supplier supports divisions."
},
"auto_pay_reference" : {
"type" : "string",
"description" : "For AutoPay agreements that reference a policy# or contract#, etc., specify that number."
},
"owing_cents" : {
"type" : "integer",
"description" : "Balance remaining on this invoice or credit memo.\n\nRequired if supplier is configured for Balance Sync, otherwise ignored.\n"
},
"ref1" : {
"type" : "string",
"description" : "A reference that is meaningful to the customer, e.g. Policy number, contract number, etc."
},
"ref2" : {
"type" : "string",
"description" : "As above."
},
"ref3" : {
"type" : "string",
"description" : "As above."
},
"adjustments_attributes" : {
"type" : "array",
"description" : "Adjustments such as Fuel Surcharge or Discount.",
"items" : {
"$ref" : "#/definitions/Invoice_adjustments_attributes"
}
},
"plan_identifier" : {
"type" : "string",
"description" : "Payment plan template identifier. If populated, this puts the invoice on a payment plan.\n\nRequired if supplier is configured for payment plans.\n"
},
"plan_start_date" : {
"type" : "string",
"format" : "date",
"description" : "Payment plan start date. Required if supplier is configured for payment plans."
},
"plan_end_date" : {
"type" : "string",
"format" : "date",
"description" : "Payment plan end date. Required if supplier is configured for payment plans."
},
"plan_payment_amount" : {
"type" : "integer",
"description" : "Payment plan recurring payment amount. Required if supplier is configured for payment plans."
},
"annualized_amount" : {
"type" : "integer",
"description" : "The annual invoice amount. When this is populated, the importer will calculate a pro-rated invoice amount based on the next two dates.\n\nRequired if the supplier is configured for payment plans.\n"
},
"annualized_effective_date" : {
"type" : "string",
"format" : "date",
"description" : "The date that the annualized_amount takes effect. Mandatory if annualized_amount is populated."
},
"annualized_expiry_date" : {
"type" : "string",
"format" : "date",
"description" : "The end date of the period for which the annualized_amount is in effect.\n\nMandatory if annualized_amount is populated. The difference between this date and the effective date (inclusive) is used to pro-rate the invoice amount or any adjustments to the amount.\n"
},
"external_id" : {
"type" : "string",
"description" : "Optional external identifier for the invoice to be included in payment exports."
}
},
"example" : {
"number" : "sh763-h3454-dh3432",
"display_number" : "INV1234",
"customer_identifier" : "CUS001",
"purchase_order_number" : "PO-3847",
"amount" : 40000,
"currency" : "usd",
"date" : "2017-11-01",
"due_date" : "2017-12-15",
"notes_text" : "Thank you for your business",
"shipping_name" : "Acme Inc.",
"shipping_address_1" : "1 Main Street",
"shipping_address_2" : "Suite 600",
"shipping_postal_code" : "90210",
"shipping_city" : "New York",
"shipping_province" : "NY",
"owing_cents" : 30000,
"line_item_attributes" : [ {
"number" : "1",
"item_number" : "A3947C9878",
"description" : "Modems",
"quantity" : 40,
"unit_cost_cents" : 1000,
"amount" : 40000
} ]
}
},
"LineItem" : {
"type" : "object",
"properties" : {
"number" : {
"type" : "string",
"description" : "Invoice line-item number"
},
"description" : {
"type" : "string",
"description" : "Invoice line-item description"
},
"quantity" : {
"type" : "number",
"description" : "Invoice line-item quantity"
},
"unit_cost_cents" : {
"type" : "integer",
"description" : "Invoice line-item unit price in cents."
},
"amount" : {
"type" : "integer",
"description" : "Invoice line-item total in cents."
},
"balance_cents" : {
"type" : "integer",
"description" : "Line-item balance in cents. Applicable if accepting short payments at line-item level."
}
}
},
"PaymentImport" : {
"type" : "object",
"required" : [ "identifier" ],
"properties" : {
"identifier" : {
"type" : "string",
"description" : "Payment identifier; must be unique within supplier. May appear multiple times in a single file if payment was applied to multiple invoices.\n"
},
"amount" : {
"type" : "integer",
"description" : "The amount of total payment, in cents."
},
"date" : {
"type" : "string",
"format" : "date",
"description" : "Payment date, in the format YYYY-MM-DD."
},
"currency" : {
"type" : "string",
"description" : "Currency code, based on ISO-4217."
},
"invoice_number" : {
"type" : "string",
"description" : "Invoice number associated with this payment (if payment covers single invoice).\nIf payment covers multiple invoices, provide `payment_amount_attributes` instead.\n"
},
"payment_code" : {
"type" : "string",
"description" : "Payment code"
},
"payment_description" : {
"type" : "string",
"description" : "Description corresponding to payment code."
},
"payment_amount_attributes" : {
"type" : "array",
"description" : "Applicable only when payment covers multiple invoices.",
"items" : {
"$ref" : "#/definitions/PaymentImport_payment_amount_attributes"
}
},
"division" : {
"type" : "string",
"description" : "Division code, if divisions are set up."
},
"customer_identifier" : {
"type" : "string",
"description" : "Customer identifier."
},
"customer_name" : {
"type" : "string",
"description" : "Customer name."
}
},
"example" : {
"identifier" : "PMT001-05",
"amount" : 10000,
"currency" : "usd",
"date" : "2017-12-02",
"customer_identifier" : "CUS001",
"payment_amounts_attributes" : [ {
"invoice_number" : "INV004",
"amount" : 8000
}, {
"invoice_number" : "INV010",
"amount" : 2000
} ]
}
},
"FileImport" : {
"type" : "object",
"properties" : {
"id" : {
"type" : "string",
"example" : "21877",
"description" : "The import batch identifier."
},
"file_name" : {
"type" : "string",
"example" : "invoices.csv",
"description" : "The original filename of the raw file."
},
"file_size" : {
"type" : "integer",
"example" : 1024,
"description" : "The original size of the raw file in bytes."
},
"file_content_type" : {
"type" : "string",
"example" : "text/plain",
"description" : "The MIME/content-type of the raw file."
},
"file_fingerprint" : {
"type" : "string",
"example" : "bf817b5548d69f6a3a49b6bb872fb906",
"description" : "The fingerprint/hash representing the raw file contents."
},
"error" : {
"type" : "string",
"example" : "",
"description" : "The error message corresponding to a failed import."
},
"result_message" : {
"type" : "string",
"example" : "5487 invoices",
"description" : "Result of batch import."
},
"complete_at" : {
"type" : "string",
"example" : "2016-08-30T15:39:30-04:00",
"description" : "The ISO8601 timestamp corresponding to completion of the import."
}
},
"example" : {
"result_message" : "5487 invoices",
"complete_at" : "2016-08-30T15:39:30-04:00",
"file_name" : "invoices.csv",
"file_fingerprint" : "bf817b5548d69f6a3a49b6bb872fb906",
"id" : "21877",
"file_content_type" : "text/plain",
"error" : "",
"file_size" : 1024
}
},
"PaymentExport" : {
"type" : "object",
"properties" : {
"payment_reference" : {
"type" : "string",
"description" : "The payment identifier"
},
"invoice_number" : {
"type" : "string",
"description" : "The display number of the invoice for which the payment was made."
},
"date" : {
"type" : "string",
"format" : "date",
"description" : "The payment date, in YYYY-MM-DD format."
},
"amount" : {
"type" : "string",
"description" : "The amount of the payment applied to the invoice, in dollars and cents."
},
"plan_fee" : {
"type" : "string",
"description" : "Payment plan fee amount, in dollars and cents, associated to this invoice."
},
"payment_amount" : {
"type" : "string",
"description" : "The amount of the total payment."
},
"payment_transaction_amount" : {
"type" : "string",
"description" : "The amount of the total payment."
},
"payment_method" : {
"type" : "string",
"description" : "The method used to make payment."
},
"payment_from_bank_account" : {
"type" : "string",
"description" : "`true` if the payment was made using a bank account.\n"
},
"payment_from_credit_card" : {
"type" : "string",
"description" : "`true` if the payment was made using a credit card.\n"
},
"payment_institution_name" : {
"type" : "string",
"description" : "Institution name, if the payment was made using a bank account."
},
"payment_credit_card_brand" : {
"type" : "string",
"description" : "Credit card \"association brand\", if the payment was made using a credit card. Example: VISA, MASTER\n"
},
"short_pay_indicator" : {
"type" : "string",
"description" : "`Y` if a short payment was made.\n"
},
"payment_note" : {
"type" : "string",
"description" : "Note accompanying the payment."
},
"auto_debit_indicator" : {
"type" : "string",
"description" : "`Y` if the payment was made via AutoPay agreement.\n"
},
"invoice_balance" : {
"type" : "string",
"description" : "Remaining balance on the invoice (after the payment is processed)."
},
"payment_timestamp" : {
"type" : "string",
"description" : "The ISO8601 timestamp corresponding to payment."
},
"invoice_division" : {
"type" : "string",
"description" : "The division code if any associated with the invoice."
},
"invoice_division_number" : {
"type" : "string",
"description" : "The external division identifier if any associated with the invoice."
},
"invoice_division_name" : {
"type" : "string",
"description" : "The division name if any associated with the invoice."
},
"pay_to_bank_account" : {
"type" : "string",
"description" : "The GL number of the settlement account receiving the payment."
},
"pay_to_bank_account_name" : {
"type" : "string",
"description" : "The display name of the settlement account receiving the payment."
},
"customer_identifier" : {
"type" : "string",
"description" : "The invoice customer identifier."
},
"customer_name" : {
"type" : "string",
"description" : "The invoice customer name."
},
"status" : {
"type" : "string",
"description" : "The payment status."
},
"payment_source" : {
"type" : "string",
"description" : "The source of the payment."
},
"payment_code" : {
"type" : "string",
"description" : "The back office payment code (applicable to externally sourced payments)."
},
"payment_description" : {
"type" : "string",
"description" : "The back office payment description (applicable to externally sourced payments)."
},
"gateway_authorization_code" : {
"type" : "string",
"description" : "The underlying gateway authorization code."
},
"purchase_order_number" : {
"type" : "string",
"description" : "The purchase order number entered at the time of making a prepayment."
},
"ref1" : {
"type" : "string",
"description" : "The reference number or string entered at the time of making a prepayment."
},
"ref2" : {
"type" : "string",
"description" : "Same as above."
},
"ref3" : {
"type" : "string",
"description" : "Same as above."
},
"short_pay_reason_identifier" : {
"type" : "string",
"description" : "Short pay reason code, if set up."
},
"short_pay_reason" : {
"type" : "string",
"description" : "Short pay reason description, if set up."
},
"invoice_amount_paid" : {
"type" : "string",
"description" : "The total amount of payments, in dollars and cents, made to date via ARC towards this invoice."
},
"invoice_identifier" : {
"type" : "string",
"description" : "The identifier of the invoice for which the payment was made."
},
"invoice_date" : {
"type" : "string",
"format" : "date",
"description" : "Invoice date, in the format YYYY-MM-DD."
},
"invoice_external_id" : {
"type" : "string",
"description" : "The external identifier/reference, if any, of the invoice for which the payment was made."
},
"invoice_currency" : {
"type" : "string",
"description" : "The currency of the invoice for which the payment was made."
},
"invoice_purchase_order_number" : {
"type" : "string",
"description" : "The purchase order number associated to the invoice."
},
"invoice_ref1" : {
"type" : "string",
"description" : "Reference number or string associated to the invoice."
},
"invoice_ref2" : {
"type" : "string",
"description" : "Same as above."
},
"invoice_ref3" : {
"type" : "string",
"description" : "Same as above."
},
"cumulative_customer_amount" : {
"type" : "string",
"description" : "The total payment processed for *this* customer under *this* `payment_reference`.\n"
}
}
},
"Dispute" : {
"type" : "object",
"properties" : {
"closed_at" : {
"type" : "string",
"format" : "date-time",
"description" : "Date and time when dispute was closed."
},
"opened_at" : {
"type" : "string",
"format" : "date-time",
"description" : "Date and time when dispute was opened."
},
"opener" : {
"type" : "string",
"description" : "Name or email address of the user who opened the dispute."
},
"closer" : {
"type" : "string",
"description" : "Name or email address of the user who closed the dispute."
},
"opening_comment_text" : {
"type" : "string",
"description" : "Comment text when the dispute was opened."
},
"closing_comment_text" : {
"type" : "string",
"description" : "Comment text when the dispute was closed."
},
"invoice_number" : {
"type" : "string",
"description" : "Invoice number against which dispute was opened."
},
"invoice_amount_paid" : {
"type" : "string",
"description" : "The total amount of payments, in dollars and cents, made to date via ARC towards this invoice."
},
"invoice_balance" : {
"type" : "object",
"description" : "Invoice balance, in cents.",
"additionalProperties" : {
"type" : "integer"
}
},
"dispute_reason_identifier" : {
"type" : "string",
"description" : "Dispute reason code, if set up."
},
"dispute_reason_label_en" : {
"type" : "string",
"description" : "Dispute reason label in English. Applicable when dispute reason codes are set up in the account."
},
"dispute_reason_label_fr" : {
"type" : "string",
"description" : "Dispute reason label in French. Applicable when dispute reason codes are set up in the account."
},
"opening_comment_users_notified" : {
"type" : "array",
"description" : "Names or email addresses of users notified when opening dispute.",
"items" : {
"type" : "string"
}
},
"closing_comment_user_notified" : {
"type" : "string",
"description" : "Name or email address of users notified when closing dispute."
},
"creator_business_name" : {
"type" : "string",
"description" : "Business name of the organization that `opener` represents."
},
"closer_business_name" : {
"type" : "string",
"description" : "Business name of the organization that `closer` represents."
},
"invoice_identifier" : {
"type" : "string",
"description" : "Internal unique identifier for the invoice record."
},
"invoice_external_id" : {
"type" : "string",
"description" : "External identifier for the invoice record."
}
}
},
"inline_response_401" : {
"properties" : {
"error" : {
"type" : "string",
"example" : "You need to sign in or create an account before continuing.",
"description" : "Error message"
}
}
},
"fund_token" : {
"type" : "object",
"properties" : {
"fund_token" : {
"type" : "string",
"example" : "5TH3ACC3AU21",
"description" : "Your bank account or balance's **token** attribute. Omitting this option will approve the transaction using your default bank account.\n"
}
}
},
"inline_response_412" : {
"properties" : {
"error" : {
"type" : "string",
"description" : "Error message."
}
},
"example" : "{\"error\":\"API token does not have permission for this request. Please contact your account administrator.\"}"
},
"body" : {
"type" : "object",
"required" : [ "email" ],
"properties" : {
"email" : {
"type" : "string",
"example" : "bob.smith@example.com",
"description" : "Recipient email address."
},
"reference" : {
"type" : "string",
"example" : "87769089",
"description" : "Extra useful data to help link transactions to other systems e.g. PO numbers, account numbers etc."
},
"message" : {
"type" : "string",
"example" : "Debit agreement for order number - 87769089",
"description" : "A message describing what the agreement is for."
}
}
},
"fund_token_1" : {
"type" : "object",
"properties" : {
"fund_token" : {
"type" : "string",
"example" : "5TH3ACC3AU21",
"description" : "Your bank account or balance's token attribute. Omitting this option will approve the agreement using your default bank account.\n"
}
}
},
"inline_response_201" : {
"properties" : {
"identifier" : {
"type" : "string",
"example" : "C1234"
},
"message" : {
"type" : "string",
"example" : "1 customer with 3 contacts"
}
},
"example" : {
"identifier" : "C1234",
"message" : "1 customer with 3 contacts"
}
},
"inline_response_201_1" : {
"properties" : {
"identifier" : {
"type" : "string",
"example" : "INV002"
},
"message" : {
"type" : "string",
"example" : "1 invoice 1 line items"
}
},
"example" : {
"identifier" : "INV002",
"message" : "1 invoice 1 line items"
}
},
"inline_response_201_2" : {
"properties" : {
"identifier" : {
"type" : "string",
"example" : "PMT123"
},
"message" : {
"type" : "string",
"example" : "1 payment 1 invoice amounts"
}
},
"example" : {
"identifier" : "PMT123",
"message" : "1 payment 1 invoice amounts"
}
},
"inline_response_200" : {
"properties" : {
"payment_amounts" : {
"type" : "object",
"additionalProperties" : {
"$ref" : "#/definitions/PaymentExport"
}
}
}
},
"Invoice_adjustments_attributes" : {
"properties" : {
"label" : {
"type" : "string",
"description" : "Label for adjustment amount."
},
"amount" : {
"type" : "integer",
"description" : "Adjustment amount in cents."
}
}
},
"PaymentImport_payment_amount_attributes" : {
"properties" : {
"invoice_number" : {
"type" : "string",
"description" : "Invoice number associated with this payment."
},
"amount" : {
"type" : "integer",
"description" : "Amount paid towards this invoice."
},
"notes" : {
"type" : "string",
"description" : "Payment note"
},
"purchase_order_number" : {
"type" : "string",
"description" : "Purchase order number to link this payment to an invoice."
},
"ref1" : {
"type" : "string",
"description" : "An additional reference number that could link this payment to an invoice. E.g. policy number, contract number, etc."
},
"ref2" : {
"type" : "string",
"description" : "Same as above."
},
"ref3" : {
"type" : "string",
"description" : "Same as above."
}
}
}
},
"responses" : {
"PreconditionFailed" : {
"description" : "Precondition Failed",
"schema" : {
"type" : "object",
"example" : {
"email" : "can't be blank\n"
},
"additionalProperties" : {
"type" : "string",
"description" : "Error message"
}
}
},
"UnauthorizedError" : {
"description" : "Unauthorized",
"schema" : {
"type" : "object",
"properties" : {
"error" : {
"type" : "string",
"example" : "You need to sign in or create an account before continuing.",
"description" : "Error message"
}
}
}
}
},
"x-servers" : [ {
"url" : "https://secure.versapay.com",
"description" : "Production"
}, {
"url" : "https://demo.versapay.com",
"description" : "Demo"
} ],
"x-tagGroups" : [ {
"name" : "PayPort",
"description" : "Operations available for PayPort integration.",
"tags" : [ "Fund Sources", "Webhooks", "Transactions", "Agreements", "Hosted Checkout" ]
}, {
"name" : "ARC",
"description" : "Operations available for ARC integration.",
"tags" : [ "Customers", "Invoices", "Payments", "File Imports" ]
} ]
}