Terms and Definitions

Throughout this document and the Velo platform the following terms are used:

  • Payor. An entity (typically a corporation) which wishes to pay funds to one or more payees via a payout.

  • Payee. The recipient of funds paid out by a payor.

  • Payment. A single transfer of funds from a payor to a payee.

  • Payout. A batch of Payments, typically used by a payor to logically group payments (e.g. by business day). Technically there need be no relationship between the payments in a payout - a single payout can contain payments to multiple payees and/or multiple payments to a single payee.

  • Sandbox. An integration environment provided by Velo Payments which offers a similar API experience to the production environment, but all funding and payment events are simulated, along with many other services such as OFAC sanctions list checking.

Overview

The Velo Payments API allows a payor to perform a number of operations. The following is a list of the main capabilities in a natural order of execution:

  • Authenticate with the Velo platform

  • Maintain a collection of payees

  • Query the payor’s current balance of funds within the platform and perform additional funding

  • Issue payments to payees

  • Query the platform for a history of those payments

This document describes the main concepts and APIs required to get up and running with the Velo Payments platform. It is not an exhaustive API reference. For that, please see the separate Velo Payments API Reference.

Notice

This document, including all contents herein, and the Velo Payments API are the confidential information and the intellectual property of Velo and are not to be distributed or otherwise made available to any third party. The Velo Payment API, and your use of the Velo Payment API, is governed by and subject to the Velo Services Terms of Use.

API Considerations

The Velo Payments API is REST based and uses the JSON format for requests and responses.

Most calls are secured using OAuth 2 security and require a valid authentication access token for successful operation. See the Authentication section for details.

Where a dynamic value is required in the examples below, the {token} format is used, suggesting that the caller needs to supply the appropriate value of the token in question (without including the { or } characters).

Where curl examples are given, the –d @filename.json approach is used, indicating that the request body should be placed into a file named filename.json in the current directory. Each of the curl examples in this document should be considered a single line on the command-line, regardless of how they appear in print.

Authenticating with the Velo Platform

Once Velo backoffice staff have added your organization as a payor within the Velo platform sandbox, they will create you a payor Id, an API key and an API secret and share these with you in a secure manner.

You will need to use these values to authenticate with the Velo platform in order to gain access to the APIs. The steps to take are explained in the following:

create a string comprising the API key (e.g. abcdef) and API secret (e.g. 123456) with a colon between them. E.g. abcdef:123456

base64 encode this string. E.g.: YWJjZGVmOjEyMzQ1Ngo=

create an HTTP Authorization header with the value set to e.g. Basic YWJjZGVmOjEyMzQ1Ngo=

perform the Velo authentication REST call using the HTTP header created above e.g. via curl:

curl -X POST \
-H "Content-Type: application/json" \
-H "Authorization: Basic YWJjZGVmOjEyMzQ1Ngo=" \
'https://api.sandbox.velopayments.com/v1/authenticate?grant_type=client_credentials'

If successful, this call will result in a 200 HTTP status code and a response body such as:

{
   "access_token":"19f6bafd-93fd-4747-b229-00507bbc991f",
   "token_type":"bearer",
   "expires_in":1799,
   "scope":"..."
}

If the authenticate API call is unsuccessful, you will receive a 401 HTTP status indicating that the credentials are incorrect.

API access following authentication

Following successful authentication, the value of the access_token field in the response should then be presented with all subsequent API calls to allow the Velo platform to validate that the caller is authenticated.

This is achieved by setting the HTTP Authorization header with the value set to e.g. Bearer 19f6bafd-93fd-4747-b229-00507bbc991f such as the curl example below:

-H "Authorization: Bearer 19f6bafd-93fd-4747-b229-00507bbc991f "

If you make other Velo API calls which require authorization but the Authorization header is missing or invalid then you will get a 401 HTTP status response.

Payor Service Public API endpoints

Get Payor

GET /v1/payors/{payorId}

Get a Single Payor by Id (200 - OK, 404 - payor not found).

Authorization

User access token required.

Path parameters

Parameter Type Optional Description

payorId

Object

false

The payor id (UUID).

Query parameters

No parameters.

Request fields

No request body.

Response fields

Path Type Optional Description

payorId

String

false

The payor id (UUID).

payorName

String

false

The name of the payor.

address

Object

false

The address of the payor.

address.line1

String

false

Size must be between 2 and 255 inclusive.

address.line2

String

true

Size must be between 0 and 255 inclusive.

address.line3

String

true

Size must be between 0 and 255 inclusive.

address.line4

String

true

Size must be between 0 and 255 inclusive.

address.city

String

false

Size must be between 2 and 100 inclusive.

address.countyOrProvince

String

true

Size must be between 2 and 100 inclusive.

address.zipOrPostcode

String

true

Size must be between 2 and 30 inclusive.

address.country

String

false

Size must be between 2 and 50 inclusive.

primaryContactName

String

false

Name of primary contact for the payor.

primaryContactPhone

String

false

Primary contact phone number for the payor.

primaryContactEmail

String

false

Primary contact email for the payor.

fundingAccountRoutingNumber

String

true

The funding account routing number to be used for the payor.

fundingAccountAccountNumber

String

true

The funding account number to be used for the payor.

fundingAccountAccountName

String

true

The funding account name to be used for the payor.

kycState

String

true

The kyc state of the payor.

Must be one of [FAILED_KYC, PASSED_KYC, REQUIRES_KYC].

manualLockout

Boolean

true

Whether or not the payor has been manually locked by the backoffice.

payeeGracePeriodProcessingEnabled

Boolean

true

Whether grace period processing is enabled.

payeeGracePeriodDays

Integer

true

The grace period for paying payees in days.

collectiveAlias

String

true

How the payor has chosen to refer to payees.

supportContact

String

true

The payor’s support contact address.

dbaName

String

true

The payor’s 'Doing Business As' name.

allowsLanguageChoice

Boolean

true

Whether or not the payor allows language choice in the UI.

reminderEmailsOptOut

Boolean

true

Whether or not the payor has opted-out of reminder emails being sent.

language

String

false

The payor’s language preference.

Must be one of [EN, FR].

includesReports

Boolean

true

Example request

$ curl 'https://api.sandbox.velopayments.com/v1/payors/c66a1b03-23e2-4fa8-9197-840f98f8d205' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer d0866ee5-2759-4402-8d9b-104347fc8537'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 727

{
  "payorId" : "c66a1b03-23e2-4fa8-9197-840f98f8d205",
  "payorName" : "Payor1",
  "address" : {
    "line1" : "101 California Street",
    "line2" : null,
    "line3" : null,
    "line4" : null,
    "city" : "San Francisco",
    "countyOrProvince" : "California",
    "zipOrPostcode" : "94111",
    "country" : "US"
  },
  "primaryContactName" : "Foo Name",
  "primaryContactPhone" : "+1234567890",
  "primaryContactEmail" : "foo@example.com",
  "kycState" : "REQUIRES_KYC",
  "manualLockout" : false,
  "payeeGracePeriodProcessingEnabled" : true,
  "payeeGracePeriodDays" : 90,
  "dbaName" : "Payor1 DBA",
  "allowsLanguageChoice" : false,
  "reminderEmailsOptOut" : false,
  "language" : "FR",
  "includesReports" : false
}

Set Payor Funding Bank Details

POST /v1/payors/{payorId}/payorFundingBankDetailsUpdate

Update the Funding bank details of the Payor (202 - accepted, 400 - invalid request body, 404 - payor not found).

Authorization

User access token required.

Path parameters

Parameter Type Optional Description

payorId

Object

false

Query parameters

No parameters.

Request fields

Path Type Optional Description

routingNumber

String

false

Routing number for the payor’s bank.

Size must be between 9 and 9 inclusive.

accountNumber

String

false

Payor’s bank account number.

Size must be between 4 and 17 inclusive.

accountName

String

false

Payor’s bank account name.

Size must be between 1 and 22 inclusive.

Response fields

No response body.

Example request

$ curl 'https://api.sandbox.velopayments.com/v1/payors/9989ee5d-136b-43c0-9c1c-7dd9ac3aeb40/payorFundingBankDetailsUpdate' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer 2163f38c-a37d-48ce-99d9-e415d7f231d4' \
    -d '{"routingNumber":"123456789","accountNumber":"12345","accountName":"Bob"}'

Example response

HTTP/1.1 202 Accepted

Create Application

POST /v1/payors/{payorId}/applications

Create an Application for the Payor (201 - created, 400 - invalid request body, 404 - payor not found, 409 - application name conflict).

Authorization

User access token required.

Path parameters

Parameter Type Optional Description

payorId

Object

false

The ID (UUID) of the payor.

Query parameters

No parameters.

Request fields

Path Type Optional Description

name

String

false

The name of the application.

Size must be between 2 and 100 inclusive.

description

String

true

Description of the application.

Size must be between 2 and 1024 inclusive.

Response fields

No response body.

Example request

$ curl 'https://api.sandbox.velopayments.com/v1/payors/f6157f52-9b3d-47fb-b48b-30f624e0e00e/applications' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer 754949f0-188c-4736-b056-dd1590df0cde' \
    -d '{"name":"foo","description":"a foo application"}'

Example response

HTTP/1.1 201 Created
Location: https://api.sandbox.velopayments.com/v1/payors/f6157f52-9b3d-47fb-b48b-30f624e0e00e/applications/cf66fa70-99ca-4ac3-9e8c-305a9dba4ab3

Create Key

POST /v1/payors/{payorId}/applications/{applicationId}/keys

Create an ApiKey for the Payor (201 - created, 400 - invalid request body / payor in invalid state, 404 - payor not found / application not found).

Authorization

User access token required.

Path parameters

Parameter Type Optional Description

payorId

Object

false

The id (UUID) of the payor.

applicationId

Object

false

The id (UUID) of the application.

Query parameters

No parameters.

Request fields

Path Type Optional Description

name

String

false

A name for the key.

Size must be between 2 and 100 inclusive.

description

String

true

Description of the key.

Size must be between 2 and 1024 inclusive.

roles

Array[String]

false

A list of roles to assign to the key.

Size must be between 1 and 2147483647 inclusive.

Response fields

Path Type Optional Description

apiKey

String

true

API key (UUID).

apiSecret

String

true

API secret (UUID).

Example request

$ curl 'https://api.sandbox.velopayments.com/v1/payors/f6157f52-9b3d-47fb-b48b-30f624e0e00e/applications/0606c437-99fe-4200-b16d-03b1dd18de88/keys' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer 748647dd-ac16-4635-851b-a9035cc5f254' \
    -d '{"name":"foo","description":"a foo key","roles":["foo.role"]}'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 111

{
  "apiKey" : "f77e5c08-43d0-4fd9-b8c4-b62f5cc1c51b",
  "apiSecret" : "7d038331-ca5c-40c8-a29a-b11fe33d7a43"
}

Payee Service APIs

Get Payees

GET /v1/payees

Get a paginated response listing the payees for a payor (200 - OK, 400 - Request parameters validation errors ).

Authorization

User access token required.

Path parameters

No parameters.

Query parameters

Parameter Type Optional Description

payorId

Object

true

Payor id (only mandatory if the payor is making the request).

ofacStatus

Object

true

Filter by the ofacStatus of the payees.

onboardedStatus

Object

true

Filter by the onboardedStatus of the payees.

email

String

true

Filter by email. This filters via a case insensitive substring match.

displayName

String

true

Filter by displayName. This filters via a case insensitive substring match.

page

Integer

true

Page number. Default is 1.

pageSize

Integer

true

Page size. Default is 25. Max allowable is 100.

sort

String

true

List of sort fields (e.g. ?sort=onboardedStatus:asc,displayName:asc)
Default is displayName:asc
'displayName' is treated as:

- company name for companies - lastName + ', ' + firstName for individuals

The supported sort fields are: payeeId, displayName, ofacStatus, onboardedStatus, email.

Must match the regular expression ([a-zA-Z]+[:desc|:asc]).

requestParams

Object

false

Must match the regular expression ([a-zA-Z]+[:desc|:asc]).

Request fields

No request body.

Response fields

Path Type Optional Description

links

Array[Object]

true

links[].rel

String

true

links[].href

String

true

page

Object

true

page.numberOfElements

Integer

true

page.totalElements

Integer

true

page.totalPages

Integer

true

page.page

Integer

true

page.pageSize

Integer

true

content

Array[Object]

true

Example request

$ curl 'https://api.sandbox.velopayments.com/v1/payees?pageSize=2&page=8&payorId=07d549f3-9f49-4fcc-a4e5-a82779e7d78f&ofacStatus=PASSED&onboardedStatus=INVITED&email=foo@example.com&displayName=Bar' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer 3c077fec-9bd1-4927-956a-15927a83ea91'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 1623

{
  "page" : {
    "numberOfElements" : 2,
    "totalElements" : 45,
    "totalPages" : 23,
    "page" : 9,
    "pageSize" : 2
  },
  "summary" : {
    "totalPayeesCount" : 123,
    "totalInvitedCount" : 3,
    "totalRegisteredCount" : 20,
    "totalOnboardedCount" : 70,
    "totalOfacFailedCount" : 30
  },
  "links" : [ {
    "rel" : "first",
    "href" : "https://api.sandbox.velopayments.com/v1/payees?payorId=07d549f3-9f49-4fcc-a4e5-a82779e7d78f&ofacStatus=PASSED&onboardedStatus=INVITED&email=foo@example.com&displayName=Bar&page=1&pageSize=2&sort=displayName:asc"
  }, {
    "rel" : "last",
    "href" : "https://api.sandbox.velopayments.com/v1/payees?payorId=07d549f3-9f49-4fcc-a4e5-a82779e7d78f&ofacStatus=PASSED&onboardedStatus=INVITED&email=foo@example.com&displayName=Bar&page=23&pageSize=2&sort=displayName:asc"
  }, {
    "rel" : "self",
    "href" : "https://api.sandbox.velopayments.com/v1/payees?payorId=07d549f3-9f49-4fcc-a4e5-a82779e7d78f&ofacStatus=PASSED&onboardedStatus=INVITED&email=foo@example.com&displayName=Bar&page=9&pageSize=2&sort=displayName:asc"
  }, {
    "rel" : "prev",
    "href" : "https://api.sandbox.velopayments.com/v1/payees?payorId=07d549f3-9f49-4fcc-a4e5-a82779e7d78f&ofacStatus=PASSED&onboardedStatus=INVITED&email=foo@example.com&displayName=Bar&page=8&pageSize=2&sort=displayName:asc"
  }, {
    "rel" : "next",
    "href" : "https://api.sandbox.velopayments.com/v1/payees?payorId=07d549f3-9f49-4fcc-a4e5-a82779e7d78f&ofacStatus=PASSED&onboardedStatus=INVITED&email=foo@example.com&displayName=Bar&page=10&pageSize=2&sort=displayName:asc"
  } ],
  "content" : [ null, null ]
}

Initiate Payee Creation

POST /v2/payees

Initiate the process of creating 1 to 2000 payees in a batch Use the response location header to query for status (201 - Created, 400 - invalid request body, 409 - if there is a duplicate remote id within the batch / if there is a duplicate email within the batch).

Authorization

User access token required.

Path parameters

No parameters.

Query parameters

No parameters.

Request fields

Path Type Optional Description

payorId

String

false

payees

Array[Object]

false

Size must be between 1 and 2000 inclusive.

payees[].type

String

false

Must be one of [Individual, Company].

payees[].remoteId

String

false

Size must be between 1 and 100 inclusive.

payees[].email

String

false

Must be a well-formed email address.
Size must be between 3 and 255 inclusive.

payees[].address

Object

false

payees[].address.line1

String

false

Size must be between 1 and 100 inclusive.

payees[].address.line2

String

true

Size must be between 1 and 100 inclusive.

payees[].address.line3

String

true

Size must be between 1 and 100 inclusive.

payees[].address.line4

String

true

Size must be between 1 and 100 inclusive.

payees[].address.city

String

false

Size must be between 1 and 50 inclusive.

payees[].address.countyOrProvince

String

true

Size must be between 1 and 50 inclusive.

payees[].address.zipOrPostcode

String

false

Size must be between 3 and 15 inclusive.

payees[].address.country

String

false

Size must be between 1 and 60 inclusive.

payees[].paymentChannel

Object

true

payees[].paymentChannel.paymentChannelName

String

true

payees[].paymentChannel.iban

String

true

Must match the regular expression ^[A-Za-z0-9]+$.
Size must be between 15 and 34 inclusive.

payees[].paymentChannel.accountNumber

String

true

Size must be between 6 and 17 inclusive.

payees[].paymentChannel.routingNumber

String

true

Must be a combination of 9 numeric digits, separated optionally by hyphens or spaces.

payees[].paymentChannel.countryCode

String

false

Size must be between 2 and 2 inclusive.

payees[].paymentChannel.currency

String

false

Must be a 3 character currency code e.g. USD, GBP, EUR.

payees[].paymentChannel.accountName

String

false

Size must be between 1 and 100 inclusive.

payees[].individual

Object

true

payees[].individual.name

Object

false

payees[].individual.name.title

String

true

Size must be between 1 and 10 inclusive.

payees[].individual.name.firstName

String

false

Size must be between 1 and 40 inclusive.

payees[].individual.name.otherNames

String

true

Size must be between 1 and 40 inclusive.

payees[].individual.name.lastName

String

false

Size must be between 1 and 40 inclusive.

payees[].individual.nationalIdentification

String

true

payees[].individual.dateOfBirth

String

false

payees[].company

Object

true

payees[].company.name

String

false

Size must be between 1 and 40 inclusive.

payees[].company.taxId

String

true

Must match the regular expression [\d]{9}.

payees[].social

Object

true

payees[].social.twitterId

String

true

Size must be between 1 and 256 inclusive.

payees[].social.facebookId

String

true

Size must be between 1 and 256 inclusive.

payees[].social.linkedInId

String

true

Size must be between 1 and 256 inclusive.

payees[].challenge

Object

true

payees[].challenge.value

String

false

Size must be between 3 and 20 inclusive.

payees[].challenge.description

String

false

Size must be between 1 and 255 inclusive.

payees[].language

String

true

Must be one of [AR, EN, ES, FR, HE, HI, JA, PT, RU, UR, ZH].

Response fields

No response body.

Example request

$ curl 'https://api.sandbox.velopayments.com/v2/payees' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer 8b7c36e8-241c-4dd8-97c3-06d891cb2ee6' \
    -d '{"payorId":"dbea47bf-af9b-4089-98df-ffe733a0847b","payees":[{"type":"Individual","remoteId":"remoteId","email":"bob@example.com","address":{"line1":"100 Battery Street","line2":"line2","line3":"line3","line4":"line4","city":"San Francisco","countyOrProvince":"California","zipOrPostcode":"94018","country":"US"},"paymentChannel":{"paymentChannelName":"My Payment Channel","accountNumber":"12345678","routingNumber":"123456789","countryCode":"US","currency":"USD","accountName":"Foo Account"},"individual":{"name":{"title":"Mr","firstName":"Barney","otherNames":"Grubb","lastName":"Cuthbert"},"nationalIdentification":"987654321","dateOfBirth":"1970-05-20"},"language":"FR"},{"type":"Company","remoteId":"remoteId","email":"bob@example.com","address":{"line1":"100 Battery Street","line2":"line2","line3":"line3","line4":"line4","city":"San Francisco","countyOrProvince":"California","zipOrPostcode":"94018","country":"US"},"paymentChannel":{"paymentChannelName":"My Payment Channel","accountNumber":"12345678","routingNumber":"123456789","countryCode":"US","currency":"USD","accountName":"Foo Account"},"company":{"name":"ABC Payee Corp","taxId":"223344556"},"language":"FR"}]}'

Example response

HTTP/1.1 201 Created
Location: https://api.sandbox.velopayments.com/v2/payees/batch/1326e3c9-0b2f-452e-a73c-2236701d6674

Query Batch Status

GET /v2/payees/batch/{batchId}

Fetch the status of a specific batch of payees. The batch is fully processed when status is ACCEPTED and pendingCount is 0 ( 200 - OK, 404 - batch not found ).

Authorization

User access token required.

Path parameters

Parameter Type Optional Description

batchId

Object

false

Query parameters

No parameters.

Request fields

No request body.

Response fields

Path Type Optional Description

status

String

true

Must be one of [SUBMITTED, ACCEPTED].

failureCount

Integer

true

pendingCount

Integer

true

failures

Array[Object]

true

failures[].failedSubmission

Object

true

failures[].failedSubmission.type

String

false

Must be one of [Individual, Company].

failures[].failedSubmission.remoteId

String

false

Size must be between 1 and 100 inclusive.

failures[].failedSubmission.email

String

false

Must be a well-formed email address.
Size must be between 3 and 255 inclusive.

failures[].failedSubmission.address

Object

false

failures[].failedSubmission.address.line1

String

false

Size must be between 1 and 100 inclusive.

failures[].failedSubmission.address.line2

String

true

Size must be between 1 and 100 inclusive.

failures[].failedSubmission.address.line3

String

true

Size must be between 1 and 100 inclusive.

failures[].failedSubmission.address.line4

String

true

Size must be between 1 and 100 inclusive.

failures[].failedSubmission.address.city

String

false

Size must be between 1 and 50 inclusive.

failures[].failedSubmission.address.countyOrProvince

String

true

Size must be between 1 and 50 inclusive.

failures[].failedSubmission.address.zipOrPostcode

String

false

Size must be between 3 and 15 inclusive.

failures[].failedSubmission.address.country

String

false

Size must be between 1 and 60 inclusive.

failures[].failedSubmission.paymentChannel

Object

true

failures[].failedSubmission.paymentChannel.paymentChannelName

String

true

failures[].failedSubmission.paymentChannel.iban

String

true

Must match the regular expression ^[A-Za-z0-9]+$.
Size must be between 15 and 34 inclusive.

failures[].failedSubmission.paymentChannel.accountNumber

String

true

Size must be between 6 and 17 inclusive.

failures[].failedSubmission.paymentChannel.routingNumber

String

true

Must be a combination of 9 numeric digits, separated optionally by hyphens or spaces.

failures[].failedSubmission.paymentChannel.countryCode

String

false

Size must be between 2 and 2 inclusive.

failures[].failedSubmission.paymentChannel.currency

String

false

Must be a 3 character currency code e.g. USD, GBP, EUR.

failures[].failedSubmission.paymentChannel.accountName

String

false

Size must be between 1 and 100 inclusive.

failures[].failedSubmission.individual

Object

true

failures[].failedSubmission.individual.name

Object

false

failures[].failedSubmission.individual.name.title

String

true

Size must be between 1 and 10 inclusive.

failures[].failedSubmission.individual.name.firstName

String

false

Size must be between 1 and 40 inclusive.

failures[].failedSubmission.individual.name.otherNames

String

true

Size must be between 1 and 40 inclusive.

failures[].failedSubmission.individual.name.lastName

String

false

Size must be between 1 and 40 inclusive.

failures[].failedSubmission.individual.nationalIdentification

String

true

failures[].failedSubmission.individual.dateOfBirth

String

false

failures[].failedSubmission.company

Object

true

failures[].failedSubmission.company.name

String

false

Size must be between 1 and 40 inclusive.

failures[].failedSubmission.company.taxId

String

true

Must match the regular expression [\d]{9}.

failures[].failedSubmission.social

Object

true

failures[].failedSubmission.social.twitterId

String

true

Size must be between 1 and 256 inclusive.

failures[].failedSubmission.social.facebookId

String

true

Size must be between 1 and 256 inclusive.

failures[].failedSubmission.social.linkedInId

String

true

Size must be between 1 and 256 inclusive.

failures[].failedSubmission.challenge

Object

true

failures[].failedSubmission.challenge.value

String

false

Size must be between 3 and 20 inclusive.

failures[].failedSubmission.challenge.description

String

false

Size must be between 1 and 255 inclusive.

failures[].failedSubmission.language

String

true

Must be one of [AR, EN, ES, FR, HE, HI, JA, PT, RU, UR, ZH].

failures[].failureMessage

String

true

Example request

$ curl 'https://api.sandbox.velopayments.com/v2/payees/batch/e2c99767-4320-46a6-9649-bb9cca832a2c' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer 899d9b7e-3516-439e-8998-124fa5b9d5af'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 649

{
  "status" : "ACCEPTED",
  "failureCount" : 1,
  "pendingCount" : 0,
  "failures" : [ {
    "failedSubmission" : {
      "type" : "Company",
      "remoteId" : "remoteId",
      "email" : "bob@example.com",
      "paymentChannel" : {
        "paymentChannelName" : "My Payment Channel",
        "accountNumber" : "12345678",
        "routingNumber" : "123456789",
        "countryCode" : "US",
        "currency" : "USD",
        "accountName" : "Foo Account"
      },
      "company" : {
        "name" : "ABC Payee Corp",
        "taxId" : "223344556"
      },
      "language" : "FR"
    },
    "failureMessage" : "Address is mandatory"
  } ]
}

Initiate Csv Batch Creation

POST /v2/payees

Add Payees from a CSV source file and return a location header with a link to the batch( 201 - CREATED, 409 CONFLICT - if there is a duplicate remote id within the batch / if there is a duplicate email within the batch).

Authorization

User access token required.

Path parameters

No parameters.

Query parameters

Parameter Type Optional Description

payorId

Object

false

file

Object

false

Csv Structure

Field Name Type Optional Description

type

String

false

Must be one of [Individual, Company].

remoteId

String

false

Size must be between 1 and 100 inclusive.

email

String

false

Must be a well-formed email address.

addressLine1

String

false

Size must be between 1 and 100 inclusive.

addressLine2

String

true

Size must be between 1 and 100 inclusive.

addressLine3

String

true

Size must be between 1 and 100 inclusive.

addressLine4

String

true

Size must be between 1 and 100 inclusive.

addressCity

String

false

Size must be between 1 and 50 inclusive.

addressCountyOrProvince

String

true

Size must be between 1 and 50 inclusive.

addressZipOrPostcode

String

false

Size must be between 3 and 15 inclusive.

addressCountry

String

false

Size must be between 1 and 60 inclusive.

individualNationalIdentification

String

true

Must be 9 digits.

individualDateOfBirth

String

false for individual payee

Must not be in the future.

individualTitle

String

true

Size must be between 1 and 10 inclusive.

individualFirstName

String

false for individual payee

Size must be between 1 and 40 inclusive.

individualOtherNames

String

true

Size must be between 1 and 40 inclusive.

individualLastName

String

false for individual payee

Size must be between 1 and 40 inclusive.

companyName

String

false for company payee

Size must be between 1 and 40 inclusive.

companyEIN

String

true

Must match the regular expression [\d]{9}.

paymentChannelAccountNumber

String

true

Size must be between 6 and 17 inclusive.

paymentChannelRoutingNumber

String

true

Must be a combination of 9 numeric digits, separated optionally by hyphens or spaces.

paymentChannelAccountName

String

false if other payment channel information is provided

Size must be between 1 and 100 inclusive.

paymentChannelIban

String

true

Must match the regular expression ^[A-Za-z0-9]+$.Size must be between 15 and 34 inclusive.

paymentChannelCountryCode

String

false if other payment channel information is provided

Size must be 2 characters.

paymentChannelCurrency

String

false if other payment channel information is provided

Must be a 3 character currency code e.g. USD, GBP, EUR.

challengeDescription

String

false if custom challenge is being provided

Size must be between 1 and 255 inclusive.

challengeValue

String

false if custom challenge is being provided

Size must be between 3 and 20 inclusive.

payeeLanguage

String

true

Must be one of [AR, EN, ES, FR, HE, HI, JA, PT, RU, UR, ZH].

Response fields

No response body.

Example request

$ curl 'https://api.sandbox.velopayments.com/v2/payees?payorId=1913aecc-00b2-4731-9c0f-c3227a48f66c' -i -X POST \
    -H 'Content-Type: multipart/form-data' \
    -H 'Authorization: Bearer 8acf490e-56c0-4c8f-a9b3-2b6374492b0a' \
    -F 'file=@test.csv;type=text/plain' \
    -F 'payorId=1913aecc-00b2-4731-9c0f-c3227a48f66c'

Example response

HTTP/1.1 201 Created
Location: https://api.sandbox.velopayments.com/v2/payees/batch/9fdb7e6c-4bd2-4eb6-beae-39fbc467bd6c
Content-Type: application/json;charset=UTF-8
Content-Length: 83

{
  "batchId" : "9fdb7e6c-4bd2-4eb6-beae-39fbc467bd6c",
  "rejectedCsvRows" : [ ]
}

Funding Manager APIs

Get Source Account

GET /v1/sourceAccounts/{sourceAccountId}

Get the source account (200 - success, 400 - invalid path parameter, 404 - account not found).

Authorization

User access token required.

Path parameters

Parameter Type Optional Description

sourceAccountId

Object

false

Query parameters

No parameters.

Request fields

No request body.

Response fields

No response body.

Example request

$ curl 'https://api.sandbox.velopayments.com/v1/sourceAccounts/0189c019-c489-4c84-853e-8223e5283b49' -i -X GET \
    -H 'Authorization: Bearer fd297745-0e19-41a4-b594-a16d98c903d9'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 356

{
  "id" : "a6abda2b-370e-4d98-8900-c9ef3818ad31",
  "balance" : 1203489,
  "currency" : "USD",
  "fundingRef" : "a1b2c3d4",
  "physicalAccountName" : "VELO_FBO_MYBANKA_USD",
  "railsId" : "SIM",
  "payorId" : "d1659552-5167-4c3e-974e-6e994a66a301",
  "name" : "mySourceAccount",
  "pooled" : true,
  "balanceVisible" : true,
  "customerId" : "123456789"
}

Get Source Accounts

GET /v1/sourceAccounts

Get the source accounts. (200 - success, 400 - invalid request parameters).

Authorization

User access token required.

Path parameters

No parameters.

Query parameters

Parameter Type Optional Description

physicalAccountName

String

true

payorId

Object

true

page

Integer

true

pageSize

Integer

true

sort

String

true

requestParams

Object

false

Request fields

No request body.

Response fields

No response body.

Example request

$ curl 'https://api.sandbox.velopayments.com/v1/sourceAccounts?payorId=d1659552-5167-4c3e-974e-6e994a66a301' -i -X GET \
    -H 'Authorization: Bearer a26abaf8-d7cb-4639-bb05-27120abe3389'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 1455

{
  "page" : {
    "numberOfElements" : 2,
    "totalElements" : 2,
    "totalPages" : 1,
    "page" : 1,
    "pageSize" : 0
  },
  "links" : [ {
    "rel" : "first",
    "href" : "https://api.sandbox.velopayments.com/v1/sourceAccounts?payorId=d1659552-5167-4c3e-974e-6e994a66a301&page=1&pageSize=0&sort=fundingRef:asc"
  }, {
    "rel" : "last",
    "href" : "https://api.sandbox.velopayments.com/v1/sourceAccounts?payorId=d1659552-5167-4c3e-974e-6e994a66a301&page=1&pageSize=0&sort=fundingRef:asc"
  }, {
    "rel" : "self",
    "href" : "https://api.sandbox.velopayments.com/v1/sourceAccounts?payorId=d1659552-5167-4c3e-974e-6e994a66a301&page=1&pageSize=0&sort=fundingRef:asc"
  } ],
  "content" : [ {
    "id" : "0a881c75-61cb-4bcb-bafd-9506c88cda71",
    "balance" : 1203489,
    "currency" : "USD",
    "fundingRef" : "a1b2c3d4",
    "physicalAccountName" : "VELO_FBO_MYBANKA_USD",
    "railsId" : "SIM",
    "payorId" : "d1659552-5167-4c3e-974e-6e994a66a301",
    "name" : "mySourceAccount",
    "pooled" : true,
    "balanceVisible" : true,
    "customerId" : null
  }, {
    "id" : "420f3aac-6118-49c2-98bc-1005d5fd6858",
    "balance" : 1203489,
    "currency" : "USD",
    "fundingRef" : "a1b2c3d4",
    "physicalAccountName" : "VELO_FBO_MYBANKA_USD",
    "railsId" : "SIM",
    "payorId" : "d1659552-5167-4c3e-974e-6e994a66a301",
    "name" : "mySourceAccount",
    "pooled" : true,
    "balanceVisible" : true,
    "customerId" : null
  } ]
}

Request Ach Funding

POST /v1/sourceAccounts/{sourceAccountId}/achFundingRequest

Instruct an ACH funding request to transfer funds from the payor’s funding bank to the payor’s balance held within Velo (202 - accepted, 400 - invalid request body, 404 - source account not found).

Authorization

User access token required.

Path parameters

Parameter Type Optional Description

sourceAccountId

Object

false

Query parameters

No parameters.

Request fields

Path Type Optional Description

amount

Integer

false

Must be at least 1.
Must be at most 9999999999.

Response fields

No response body.

Example request

$ curl 'https://api.sandbox.velopayments.com/v1/sourceAccounts/3daf5ca5-9539-49e7-9262-23073d50fac2/achFundingRequest' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer a8d8e4ec-8dce-4558-a2d4-13d8e84fe6bb' \
    -d '{"amount":999990}'

Example response

HTTP/1.1 202 Accepted

Payment Audit Service APIs

Get Payouts For Payor

GET /v3/paymentaudit/payouts

Get a list of Payouts for a payor

(200 - OK, 400 - invalid request parameter)
.

Authorization

User access token required.

Path parameters

No parameters.

Query parameters

Parameter Type Optional Description

payorId

Object

false

The id (UUID) of the payor.

payoutMemo

String

true

The payout memo filter. This filters via a case insensitive substring match.

status

Object

true

The payout status filter. The filters based on an exact match on payout status.

submittedDateFrom

Object

true

The submitted date from range filter. Format is yyyy-MM-dd. Filters for submittedDateTime >= submittedDateFrom 00:00:00.000.

submittedDateTo

Object

true

The submitted date to range filter. Format is yyyy-MM-dd. Filters for submittedDateTime ⇐ submittedDateTo 23:59:59.999.

page

Integer

true

Page number. Default is 1.

pageSize

Integer

true

Page size. Default is 25. Max allowable is 100.

sort

String

true

List of sort fields (e.g. ?sort=submittedDateTime:asc,instructedDateTime:asc,status:asc)
Default is submittedDateTime:asc
The supported sort fields are: submittedDateTime, instructedDateTime, status, totalPayments.

requestParams

Object

false

Request fields

No request body.

Response fields

Path Type Optional Description

links

Array[Object]

true

links[].rel

String

true

links[].href

String

true

page

Object

true

page.numberOfElements

Integer

true

page.totalElements

Integer

true

page.totalPages

Integer

true

page.page

Integer

true

page.pageSize

Integer

true

content

Array[Object]

true

content[].payoutId

String

false

content[].payorId

String

false

content[].status

String

false

Must be one of [ACCEPTED, REJECTED, SUBMITTED, QUOTED, INSTRUCTED, COMPLETED, INCOMPLETE, CONFIRMED, WITHDRAWN].

content[].submittedDateTime

String

false

content[].instructedDateTime

String

true

content[].withdrawnDateTime

String

true

content[].totalPayments

Integer

true

content[].totalIncompletePayments

Integer

true

content[].totalFailedPayments

Integer

true

content[].sourceAccountSummary

Array[Object]

true

content[].sourceAccountSummary[].sourceAccountId

String

false

content[].sourceAccountSummary[].totalCost

Integer

false

content[].sourceAccountSummary[].currency

String

false

content[].fxSummaries

Array[Object]

true

content[].fxSummaries[].quoteId

String

false

content[].fxSummaries[].creationDateTime

String

false

content[].fxSummaries[].rate

Decimal

false

content[].fxSummaries[].invertedRate

Decimal

false

content[].fxSummaries[].totalCost

Integer

false

content[].fxSummaries[].totalPaymentAmount

Integer

false

content[].fxSummaries[].sourceCurrency

String

false

content[].fxSummaries[].paymentCurrency

String

false

content[].fxSummaries[].status

String

false

Must be one of [UNQUOTED, QUOTED, EXPIRED, EXECUTED].

content[].fxSummaries[].fundingStatus

String

false

Must be one of [FUNDED, INSTRUCTED, UNFUNDED].

content[].payoutMemo

String

true

Example request

$ curl 'https://api.sandbox.velopayments.com/v3/paymentaudit/payouts?payorId=b127a327-6eb2-4c6e-8ed7-f2b0e0f42172&payoutMemo=mymemo&status=CONFIRMED&submittedDateFrom=2018-04-20&submittedDateTo=2019-12-21' -i -X GET \
    -H 'Authorization: Bearer 9bbe8db5-e51f-4b05-8c33-c1e1bda57d8a'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 2764

{
  "links" : [ {
    "rel" : "first",
    "href" : "https://api.sandbox.velopayments.com/v3/paymentaudit/payouts?payorId=b127a327-6eb2-4c6e-8ed7-f2b0e0f42172&payoutMemo=mymemo&status=CONFIRMED&submittedDateFrom=2018-04-20&submittedDateTo=2019-12-21&page=1&pageSize=25&sort=submittedDateTime:asc"
  }, {
    "rel" : "last",
    "href" : "https://api.sandbox.velopayments.com/v3/paymentaudit/payouts?payorId=b127a327-6eb2-4c6e-8ed7-f2b0e0f42172&payoutMemo=mymemo&status=CONFIRMED&submittedDateFrom=2018-04-20&submittedDateTo=2019-12-21&page=1&pageSize=25&sort=submittedDateTime:asc"
  }, {
    "rel" : "self",
    "href" : "https://api.sandbox.velopayments.com/v3/paymentaudit/payouts?payorId=b127a327-6eb2-4c6e-8ed7-f2b0e0f42172&payoutMemo=mymemo&status=CONFIRMED&submittedDateFrom=2018-04-20&submittedDateTo=2019-12-21&page=1&pageSize=25&sort=submittedDateTime:asc"
  } ],
  "page" : {
    "numberOfElements" : 1,
    "totalElements" : 1,
    "totalPages" : 1,
    "page" : 1,
    "pageSize" : 25
  },
  "content" : [ {
    "payoutId" : "5d53761e-81c5-4544-9500-217cb27389e9",
    "payorId" : "4a32f5da-d271-4b68-89d8-45f3ec645c1d",
    "status" : "INCOMPLETE",
    "submittedDateTime" : "2017-07-23T01:01:31.1110009Z",
    "instructedDateTime" : "2017-07-23T01:01:31.111Z",
    "totalPayments" : 4,
    "totalIncompletePayments" : 1,
    "totalFailedPayments" : 1,
    "sourceAccountSummary" : [ {
      "sourceAccountId" : "403a3896-83fb-4b0a-a173-068b0856d790",
      "totalCost" : 1794,
      "currency" : "USD"
    }, {
      "sourceAccountId" : "9e6bdc53-acb8-4868-a287-ea23d8692de2",
      "totalCost" : 2274,
      "currency" : "EUR"
    } ],
    "fxSummaries" : [ {
      "quoteId" : "687c6d62-8c8d-4e85-8e96-b0b780acfbd4",
      "creationDateTime" : "2018-12-17T12:31:55.353Z",
      "rate" : 1.1693,
      "invertedRate" : 0.86,
      "totalCost" : 468,
      "totalPaymentAmount" : 400,
      "sourceCurrency" : "USD",
      "paymentCurrency" : "EUR",
      "status" : "EXECUTED",
      "fundingStatus" : "FUNDED"
    }, {
      "quoteId" : "4e018563-28df-4510-b9de-413128470202",
      "creationDateTime" : "2018-12-17T12:31:55.362Z",
      "rate" : 1.326,
      "invertedRate" : 0.75,
      "totalCost" : 1326,
      "totalPaymentAmount" : 1000,
      "sourceCurrency" : "USD",
      "paymentCurrency" : "GBP",
      "status" : "EXECUTED",
      "fundingStatus" : "FUNDED"
    }, {
      "quoteId" : "74c3c16e-5642-4d0c-af2f-12e4e91b120d",
      "creationDateTime" : "2018-12-17T12:31:55.362Z",
      "rate" : 1.137,
      "invertedRate" : 0.88,
      "totalCost" : 2274,
      "totalPaymentAmount" : 2000,
      "sourceCurrency" : "EUR",
      "paymentCurrency" : "GBP",
      "status" : "QUOTED",
      "fundingStatus" : "UNFUNDED"
    } ]
  } ]
}

Get Payments For Payout

GET /v3/paymentaudit/payouts/{payoutId}

List (paginated) the payments within a payout

Supported sort fields: sourceAmount, sourceCurrency, paymentAmount, paymentCurrency, routingNumber, accountNumber, remoteId, submittedDateTime, status
Default sort: remoteId
(200 - OK, 400 - invalid request parameter, 404 - payout not found).

Authorization

User access token required.

Path parameters

Parameter Type Optional Description

payoutId

Object

false

The id (UUID) of the payout.

Query parameters

Parameter Type Optional Description

remoteId

String

true

The remote id filter. This filters via a case insensitive substring match.

status

Object

true

The payment status filter. The filters based on an exact match on payment status.

sourceAmountFrom

Integer

true

The source amount from range filter. Filters for sourceAmount >= sourceAmountFrom.

sourceAmountTo

Integer

true

The source amount to range filter. Filters for sourceAmount ⇐ sourceAmountTo.

paymentAmountFrom

Integer

true

The payment amount from range filter. Filters for paymentAmount >= paymentAmountFrom.

paymentAmountTo

Integer

true

The payment amount to range filter. Filters for paymentAmount ⇐ paymentAmountTo.

submittedDateFrom

Object

true

The submitted date from range filter. Format is yyyy-MM-dd. Filters for submittedDateTime >= submittedDateFrom 00:00:00.000.

submittedDateTo

Object

true

The submitted date to range filter. Format is yyyy-MM-dd. Filters for submittedDateTime ⇐ submittedDateTo 23:59:59.999.

page

Integer

true

Page number. Default is 1.

pageSize

Integer

true

Page size. Default is 25. Max allowable is 100.

sort

String

true

List of sort fields (e.g. ?sort=submittedDateTime:asc,status:asc)
Default is sort by remoteId
The supported sort fields are: sourceAmount, sourceCurrency, paymentAmount, paymentCurrency, routingNumber, accountNumber, remoteId, submittedDateTime and status.

sensitive

Boolean

true

requestParams

Object

false

Request fields

No request body.

Response fields

Path Type Optional Description

links

Array[Object]

true

links[].rel

String

true

links[].href

String

true

page

Object

true

page.numberOfElements

Integer

true

page.totalElements

Integer

true

page.totalPages

Integer

true

page.page

Integer

true

page.pageSize

Integer

true

summary

Object

true

summary.payoutStatus

String

false

Must be one of [ACCEPTED, REJECTED, SUBMITTED, QUOTED, INSTRUCTED, COMPLETED, INCOMPLETE, CONFIRMED, WITHDRAWN].

summary.submittedDateTime

String

false

summary.instructedDateTime

String

true

summary.withdrawnDateTime

String

true

summary.payoutMemo

String

true

summary.totalPayments

Integer

true

summary.confirmedPayments

Integer

true

summary.releasedPayments

Integer

true

summary.incompletePayments

Integer

true

summary.failedPayments

Integer

true

content

Array[Object]

true

content[].paymentId

String

false

content[].payeeId

String

false

content[].payorId

String

false

content[].quoteId

String

false

content[].sourceAccountId

String

false

content[].remoteId

String

false

content[].sourceAmount

Integer

true

content[].sourceCurrency

String

true

Must be a 3 character currency code e.g. USD, GBP, EUR.

content[].paymentAmount

Integer

false

content[].paymentCurrency

String

false

Must be a 3 character currency code e.g. USD, GBP, EUR.

content[].rate

Decimal

true

content[].invertedRate

Decimal

true

content[].submittedDateTime

String

false

content[].status

String

false

Must be one of [ACCEPTED, AWAITING_FUNDS, FUNDED, UNFUNDED, BANK_PAYMENT_REQUESTED, REJECTED, ACCEPTED_BY_RAILS, CONFIRMED, FAILED, WITHDRAWN].

content[].fundingStatus

String

false

Must be one of [FUNDED, INSTRUCTED, UNFUNDED].

content[].routingNumber

String

true

content[].accountNumber

String

true

content[].iban

String

true

content[].paymentMemo

String

true

content[].filenameReference

String

true

content[].individualIdentificationNumber

String

true

content[].traceNumber

String

true

content[].payorPaymentId

String

true

content[].paymentChannelId

String

true

content[].paymentChannelName

String

true

content[].accountName

String

true

content[].events

Array[Object]

false

Size must be between 1 and 2147483647 inclusive.

content[].events[].eventId

String

false

content[].events[].eventDateTime

String

false

content[].events[].eventType

String

false

Must be one of [PAYOUT_SUBMITTED, PAYOUT_COMPLETED, PAYOUT_INSTRUCTED_V3, BANK_PAYMENT_REQUESTED, SOURCE_AMOUNT_CONFIRMED, PAYMENT_SUBMITTED, PAYMENT_SUBMITTED_ACCEPTED, PAYMENT_SUBMITTED_REJECTED, PAYMENT_CONFIRMED, PAYMENT_AWAITING_FUNDS, PAYMENT_FUNDED, PAYMENT_UNFUNDED, PAYMENT_FAILED, ACH_SUBMITTED_TO_ODFI, PAYMENT_ACCEPTED_BY_RAILS, ACH_RETURN_RECEIVED, RETURN_PAYMENT_FUNDING_REQUESTED, PAYOUT_BATCH_EXECUTED, PAYOUT_BATCH_QUOTE_EXPIRED, PAYOUT_BATCH_FUNDED, PAYOUT_BATCH_FUNDS_RETURN_REQUEST, PAYOUT_BATCH_FUNDS_RETURNED, PAYOUT_FUNDS_REQUEST, PAYOUT_FUNDS_GRANTED, PAYOUT_FUNDS_DENIED, PAYOUT_BATCH_QUOTED, PAYOUT_QUOTED, ACH_PAYMENT_RETURN_CANCELLED, RETURN_PAYMENT_CANCELLATION_REQUESTED, PAYOUT_WITHDRAWN].

content[].events[].sourceCurrency

String

true

Must be a 3 character currency code e.g. USD, GBP, EUR.

content[].events[].sourceAmount

Integer

true

content[].events[].paymentCurrency

String

true

Must be a 3 character currency code e.g. USD, GBP, EUR.

content[].events[].paymentAmount

Integer

true

content[].events[].accountNumber

String

true

content[].events[].iban

String

true

content[].events[].routingNumber

String

true

content[].events[].accountName

String

true

content[].events[].principal

String

true

Example request

$ curl 'https://api.sandbox.velopayments.com/v3/paymentaudit/payouts/466a685e-31e5-4991-8003-e576e16fa3a2?remoteId=abcd%20efghijklm&status=CONFIRMED&sourceAmountFrom=1000&sourceAmountTo=2000&paymentAmountFrom=500&paymentAmountTo=800&submittedDateFrom=2018-04-20&submittedDateTo=2019-12-21' -i -X GET \
    -H 'Authorization: Bearer da0e8d33-922f-40fb-b7f0-f36dbadc4c10'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 5004

{
  "links" : [ {
    "rel" : "first",
    "href" : "https://api.sandbox.velopayments.com/v3/paymentaudit/payouts/466a685e-31e5-4991-8003-e576e16fa3a2?remoteId=abcd%20efghijklm&status=CONFIRMED&sourceAmountFrom=1000&sourceAmountTo=2000&paymentAmountFrom=500&paymentAmountTo=800&submittedDateFrom=2018-04-20&submittedDateTo=2019-12-21&page=1&pageSize=25&sort=remoteId"
  }, {
    "rel" : "last",
    "href" : "https://api.sandbox.velopayments.com/v3/paymentaudit/payouts/466a685e-31e5-4991-8003-e576e16fa3a2?remoteId=abcd%20efghijklm&status=CONFIRMED&sourceAmountFrom=1000&sourceAmountTo=2000&paymentAmountFrom=500&paymentAmountTo=800&submittedDateFrom=2018-04-20&submittedDateTo=2019-12-21&page=1&pageSize=25&sort=remoteId"
  }, {
    "rel" : "self",
    "href" : "https://api.sandbox.velopayments.com/v3/paymentaudit/payouts/466a685e-31e5-4991-8003-e576e16fa3a2?remoteId=abcd%20efghijklm&status=CONFIRMED&sourceAmountFrom=1000&sourceAmountTo=2000&paymentAmountFrom=500&paymentAmountTo=800&submittedDateFrom=2018-04-20&submittedDateTo=2019-12-21&page=1&pageSize=25&sort=remoteId"
  } ],
  "page" : {
    "numberOfElements" : 4,
    "totalElements" : 4,
    "totalPages" : 1,
    "page" : 1,
    "pageSize" : 25
  },
  "summary" : {
    "payoutStatus" : "INCOMPLETE",
    "submittedDateTime" : "2017-07-23T01:01:31.1110009Z",
    "instructedDateTime" : "2017-07-23T01:01:31.111Z",
    "totalPayments" : 5,
    "confirmedPayments" : 3,
    "releasedPayments" : 3,
    "incompletePayments" : 1,
    "failedPayments" : 1
  },
  "content" : [ {
    "paymentId" : "b8b5ac5d-54e2-41c0-9109-9754437515a1",
    "payeeId" : "a8d679bd-5240-428b-ae92-74527b8ebafb",
    "payorId" : "aaba9c7b-9667-4745-adfa-17f42322e530",
    "quoteId" : "03316773-07cb-4a5c-9fe7-6b7092a1b60f",
    "sourceAccountId" : "3fdc58db-d75a-4f78-9e22-7e4d2414c7f5",
    "remoteId" : "abcd efghijklm",
    "sourceAmount" : 468,
    "sourceCurrency" : "USD",
    "paymentAmount" : 400,
    "paymentCurrency" : "EUR",
    "rate" : 1.1693,
    "invertedRate" : 0.86,
    "submittedDateTime" : "2017-09-13T13:28:29Z",
    "status" : "CONFIRMED",
    "fundingStatus" : "FUNDED",
    "routingNumber" : "XXXXX6789",
    "accountNumber" : "XXXXXX4321",
    "paymentMemo" : "Memo with Spaces",
    "payorPaymentId" : "1234567abc",
    "paymentChannelId" : "8080f22f-aa26-462f-bf20-31e63f277d7c",
    "paymentChannelName" : "PaymentChannel Bank"
  }, {
    "paymentId" : "70d6b9fb-62b5-452f-8b46-ab416326f767",
    "payeeId" : "01d63154-9c7f-4f18-9745-f2997bf65e8f",
    "payorId" : "de701647-779b-41b0-97c9-7ee25edbac13",
    "quoteId" : "82185ded-1ebc-48e6-9bdc-f29d572ecafb",
    "sourceAccountId" : "6fbba8c6-4b6f-4d03-bf7d-2c6d8ef0151a",
    "remoteId" : "abcd efghijklm",
    "sourceAmount" : 398,
    "sourceCurrency" : "USD",
    "paymentAmount" : 300,
    "paymentCurrency" : "GBP",
    "rate" : 1.326,
    "invertedRate" : 0.75,
    "submittedDateTime" : "2017-09-13T12:59:24Z",
    "status" : "CONFIRMED",
    "fundingStatus" : "FUNDED",
    "routingNumber" : "XXXXX6789",
    "accountNumber" : "XXXXXX4321",
    "paymentMemo" : "Memo with Spaces",
    "payorPaymentId" : "1234567abc",
    "paymentChannelId" : "8080f22f-aa26-462f-bf20-31e63f277d7c",
    "paymentChannelName" : "PaymentChannel Bank"
  }, {
    "paymentId" : "3e5891ef-d1de-4f6d-92bf-63e939d59948",
    "payeeId" : "63090238-6a91-4408-afe5-b09a8b437cda",
    "payorId" : "2ea0dddb-bfaa-4fd5-92e7-48e7f82d5157",
    "quoteId" : "f0babb7b-db11-47aa-ba14-348971a5b872",
    "sourceAccountId" : "046d270c-bddc-4064-b3be-85ecfd446085",
    "remoteId" : "abcd efghijklm",
    "sourceAmount" : 928,
    "sourceCurrency" : "USD",
    "paymentAmount" : 700,
    "paymentCurrency" : "GBP",
    "rate" : 1.326,
    "invertedRate" : 0.75,
    "submittedDateTime" : "2017-09-13T11:39:56Z",
    "status" : "CONFIRMED",
    "fundingStatus" : "FUNDED",
    "routingNumber" : "XXXXX6789",
    "accountNumber" : "XXXXXX4321",
    "paymentMemo" : "Memo with Spaces",
    "payorPaymentId" : "1234567abc",
    "paymentChannelId" : "8080f22f-aa26-462f-bf20-31e63f277d7c",
    "paymentChannelName" : "PaymentChannel Bank"
  }, {
    "paymentId" : "0a4bda23-926b-465a-9a3a-f864e1f28399",
    "payeeId" : "d69e6f33-6d66-4ff5-b56b-51fc5e9e29a8",
    "payorId" : "bc9b27d7-c4b4-4d1d-b6d1-9310ae77e3db",
    "quoteId" : "41a74945-0662-4872-b502-0aa31a250786",
    "sourceAccountId" : "29c76ef3-21d6-4930-a74a-25a0a47310e2",
    "remoteId" : "abcd efghijklm",
    "sourceAmount" : 2274,
    "sourceCurrency" : "EUR",
    "paymentAmount" : 2000,
    "paymentCurrency" : "GBP",
    "rate" : 1.137,
    "invertedRate" : 0.88,
    "submittedDateTime" : "2017-09-13T13:11:18Z",
    "status" : "UNFUNDED",
    "fundingStatus" : "UNFUNDED",
    "routingNumber" : "XXXXX6789",
    "accountNumber" : "XXXXXX4321",
    "paymentMemo" : "Memo with Spaces",
    "payorPaymentId" : "1234567abc",
    "paymentChannelId" : "8080f22f-aa26-462f-bf20-31e63f277d7c",
    "paymentChannelName" : "PaymentChannel Bank"
  } ]
}

List Payments

GET /v3/paymentaudit/payments

Get the payments for a given payee id. The payments do not contain the payment history.

Supported fields for sorting are: remoteId, sourceCurrency, sourceAmount, paymentCurrency, paymentAmount, submittedDateTime, status

(200 - OK, 400 - invalid request parameter).

Authorization

User access token required.

Path parameters

No parameters.

Query parameters

Parameter Type Optional Description

payeeId

Object

true

The payee id. Must be supplied if caller is a PAYEE user. BACKOFFICE user must supply this or payorId.

payorId

Object

true

The payor id. Must be supplied if caller is a PAYOR user. BACKOFFICE user must supply this or payeeId.

remoteId

String

true

The remote id filter. This filters via a case insensitive substring match.

status

Object

true

The payment status filter. Filters based on an exact match on payment status.

sourceAmountFrom

Integer

true

The source amount from range filter. Filters for sourceAmount >= sourceAmountFrom.

sourceAmountTo

Integer

true

The source amount to range filter. Filters for sourceAmount ⇐ sourceAmountTo.

sourceCurrency

Object

true

The source currency filter. Filters based on an exact match on the currency.

paymentAmountFrom

Integer

true

The payment amount from range filter. Filters for paymentAmount >= paymentAmountFrom.

paymentAmountTo

Integer

true

The payment amount to range filter. Filters for paymentAmount ⇐ paymentAmountTo.

paymentCurrency

Object

true

The payment currency filter. Filters based on an exact match on the currency.

submittedDateFrom

Object

true

The submitted date from range filter. Format is yyyy-MM-dd. Filters for submittedDateTime >= submittedDateFrom 00:00:00.000.

submittedDateTo

Object

true

The submitted date to range filter. Format is yyyy-MM-dd. Filters for submittedDateTime ⇐ submittedDateTo 23:59:59.999.

paymentMemo

String

true

The payment memo filter. This filters via a case insensitive substring match.

page

Integer

true

Page number. Default is 1.

pageSize

Integer

true

Page size. Default is 25. Max allowable is 100.

sort

String

true

List of sort fields (e.g. ?sort=paymentCurrency:asc,paymentAmount:asc)
Default is no sort
The supported sort fields are: remoteId, sourceCurrency, sourceAmount, paymentCurrency, paymentAmount, submittedDateTime, status.

sensitive

Boolean

true

Optional. If omitted or set to false, any Personal Identifiable Information (PII) values are returned masked. If set to true, and you have permission, the PII values will be returned as their original unmasked values.

requestParams

Object

false

Request fields

No request body.

Response fields

Path Type Optional Description

links

Array[Object]

true

links[].rel

String

true

links[].href

String

true

page

Object

true

page.numberOfElements

Integer

true

page.totalElements

Integer

true

page.totalPages

Integer

true

page.page

Integer

true

page.pageSize

Integer

true

content

Array[Object]

true

content[].paymentId

String

false

content[].payeeId

String

false

content[].payorId

String

false

content[].quoteId

String

false

content[].sourceAccountId

String

false

content[].remoteId

String

false

content[].sourceAmount

Integer

true

content[].sourceCurrency

String

true

Must be a 3 character currency code e.g. USD, GBP, EUR.

content[].paymentAmount

Integer

false

content[].paymentCurrency

String

false

Must be a 3 character currency code e.g. USD, GBP, EUR.

content[].rate

Decimal

true

content[].invertedRate

Decimal

true

content[].submittedDateTime

String

false

content[].status

String

false

Must be one of [ACCEPTED, AWAITING_FUNDS, FUNDED, UNFUNDED, BANK_PAYMENT_REQUESTED, REJECTED, ACCEPTED_BY_RAILS, CONFIRMED, FAILED, WITHDRAWN].

content[].fundingStatus

String

false

Must be one of [FUNDED, INSTRUCTED, UNFUNDED].

content[].routingNumber

String

true

content[].accountNumber

String

true

content[].iban

String

true

content[].paymentMemo

String

true

content[].filenameReference

String

true

content[].individualIdentificationNumber

String

true

content[].traceNumber

String

true

content[].payorPaymentId

String

true

content[].paymentChannelId

String

true

content[].paymentChannelName

String

true

content[].accountName

String

true

content[].events

Array[Object]

false

Size must be between 1 and 2147483647 inclusive.

content[].events[].eventId

String

false

content[].events[].eventDateTime

String

false

content[].events[].eventType

String

false

Must be one of [PAYOUT_SUBMITTED, PAYOUT_COMPLETED, PAYOUT_INSTRUCTED_V3, BANK_PAYMENT_REQUESTED, SOURCE_AMOUNT_CONFIRMED, PAYMENT_SUBMITTED, PAYMENT_SUBMITTED_ACCEPTED, PAYMENT_SUBMITTED_REJECTED, PAYMENT_CONFIRMED, PAYMENT_AWAITING_FUNDS, PAYMENT_FUNDED, PAYMENT_UNFUNDED, PAYMENT_FAILED, ACH_SUBMITTED_TO_ODFI, PAYMENT_ACCEPTED_BY_RAILS, ACH_RETURN_RECEIVED, RETURN_PAYMENT_FUNDING_REQUESTED, PAYOUT_BATCH_EXECUTED, PAYOUT_BATCH_QUOTE_EXPIRED, PAYOUT_BATCH_FUNDED, PAYOUT_BATCH_FUNDS_RETURN_REQUEST, PAYOUT_BATCH_FUNDS_RETURNED, PAYOUT_FUNDS_REQUEST, PAYOUT_FUNDS_GRANTED, PAYOUT_FUNDS_DENIED, PAYOUT_BATCH_QUOTED, PAYOUT_QUOTED, ACH_PAYMENT_RETURN_CANCELLED, RETURN_PAYMENT_CANCELLATION_REQUESTED, PAYOUT_WITHDRAWN].

content[].events[].sourceCurrency

String

true

Must be a 3 character currency code e.g. USD, GBP, EUR.

content[].events[].sourceAmount

Integer

true

content[].events[].paymentCurrency

String

true

Must be a 3 character currency code e.g. USD, GBP, EUR.

content[].events[].paymentAmount

Integer

true

content[].events[].accountNumber

String

true

content[].events[].iban

String

true

content[].events[].routingNumber

String

true

content[].events[].accountName

String

true

content[].events[].principal

String

true

Example request

$ curl 'https://api.sandbox.velopayments.com/v3/paymentaudit/payments?payeeId=c7ee61c4-aacb-4435-b19f-c6d10870fdc6&payorId=4a32f5da-d271-4b68-89d8-45f3ec645c1d&remoteId=abcd%20efghijklm&status=CONFIRMED&sourceAmountFrom=1000&sourceAmountTo=2000&sourceCurrency=USD&paymentAmountFrom=500&paymentAmountTo=800&paymentCurrency=EUR&submittedDateFrom=2018-04-20&submittedDateTo=2019-12-21&paymentMemo=Memo%20with%20Spaces' -i -X GET \
    -H 'Authorization: Bearer 6b24a94c-c365-4dcc-8930-522f7ae2f6ac'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 2520

{
  "links" : [ {
    "rel" : "first",
    "href" : "https://api.sandbox.velopayments.com/v3/paymentaudit/payments?payeeId=c7ee61c4-aacb-4435-b19f-c6d10870fdc6&payorId=4a32f5da-d271-4b68-89d8-45f3ec645c1d&remoteId=abcd%20efghijklm&status=CONFIRMED&sourceAmountFrom=1000&sourceAmountTo=2000&sourceCurrency=USD&paymentAmountFrom=500&paymentAmountTo=800&paymentCurrency=EUR&submittedDateFrom=2018-04-20&submittedDateTo=2019-12-21&paymentMemo=Memo%20with%20Spaces&page=1&pageSize=25&sort=submittedDateTime:desc"
  }, {
    "rel" : "last",
    "href" : "https://api.sandbox.velopayments.com/v3/paymentaudit/payments?payeeId=c7ee61c4-aacb-4435-b19f-c6d10870fdc6&payorId=4a32f5da-d271-4b68-89d8-45f3ec645c1d&remoteId=abcd%20efghijklm&status=CONFIRMED&sourceAmountFrom=1000&sourceAmountTo=2000&sourceCurrency=USD&paymentAmountFrom=500&paymentAmountTo=800&paymentCurrency=EUR&submittedDateFrom=2018-04-20&submittedDateTo=2019-12-21&paymentMemo=Memo%20with%20Spaces&page=1&pageSize=25&sort=submittedDateTime:desc"
  }, {
    "rel" : "self",
    "href" : "https://api.sandbox.velopayments.com/v3/paymentaudit/payments?payeeId=c7ee61c4-aacb-4435-b19f-c6d10870fdc6&payorId=4a32f5da-d271-4b68-89d8-45f3ec645c1d&remoteId=abcd%20efghijklm&status=CONFIRMED&sourceAmountFrom=1000&sourceAmountTo=2000&sourceCurrency=USD&paymentAmountFrom=500&paymentAmountTo=800&paymentCurrency=EUR&submittedDateFrom=2018-04-20&submittedDateTo=2019-12-21&paymentMemo=Memo%20with%20Spaces&page=1&pageSize=25&sort=submittedDateTime:desc"
  } ],
  "page" : {
    "numberOfElements" : 1,
    "totalElements" : 1,
    "totalPages" : 1,
    "page" : 1,
    "pageSize" : 25
  },
  "content" : [ {
    "paymentId" : "cd5a03e1-89cf-472f-83bf-99c8558ae353",
    "payeeId" : "c7ee61c4-aacb-4435-b19f-c6d10870fdc6",
    "payorId" : "4a32f5da-d271-4b68-89d8-45f3ec645c1d",
    "quoteId" : "94a0bcce-fb77-4215-8a25-fda7a4797db3",
    "sourceAccountId" : "6471099f-4c21-4e4b-b410-3e7b9480336c",
    "remoteId" : "abcd efghijklm",
    "sourceAmount" : 468,
    "sourceCurrency" : "USD",
    "paymentAmount" : 400,
    "paymentCurrency" : "EUR",
    "rate" : 1.1693,
    "invertedRate" : 0.86,
    "submittedDateTime" : "2017-09-13T14:53:48Z",
    "status" : "CONFIRMED",
    "fundingStatus" : "FUNDED",
    "routingNumber" : "XXXXX6789",
    "accountNumber" : "XXXXXX4321",
    "paymentMemo" : "Memo with Spaces",
    "payorPaymentId" : "1234567abc",
    "paymentChannelId" : "8080f22f-aa26-462f-bf20-31e63f277d7c",
    "paymentChannelName" : "PaymentChannel Bank"
  } ]
}

Get Payment

GET /v3/paymentaudit/payments/{paymentId}

Get the payment with the given id. This contains the payment history.

(200 - OK, 404 - payment not found).

Authorization

User access token required.

Path parameters

Parameter Type Optional Description

paymentId

Object

false

The payment id (UUID).

Query parameters

Parameter Type Optional Description

sensitive

Boolean

true

Optional. If omitted or set to false, any Personal Identifiable Information (PII) values are returned masked. If set to true, and you have permission, the PII values will be returned as their original unmasked values.

Request fields

No request body.

Response fields

Path Type Optional Description

paymentId

String

false

payeeId

String

false

payorId

String

false

quoteId

String

false

sourceAccountId

String

false

remoteId

String

false

sourceAmount

Integer

true

sourceCurrency

String

true

Must be a 3 character currency code e.g. USD, GBP, EUR.

paymentAmount

Integer

false

paymentCurrency

String

false

Must be a 3 character currency code e.g. USD, GBP, EUR.

rate

Decimal

true

invertedRate

Decimal

true

submittedDateTime

String

false

status

String

false

Must be one of [ACCEPTED, AWAITING_FUNDS, FUNDED, UNFUNDED, BANK_PAYMENT_REQUESTED, REJECTED, ACCEPTED_BY_RAILS, CONFIRMED, FAILED, WITHDRAWN].

fundingStatus

String

false

Must be one of [FUNDED, INSTRUCTED, UNFUNDED].

routingNumber

String

true

accountNumber

String

true

iban

String

true

paymentMemo

String

true

filenameReference

String

true

individualIdentificationNumber

String

true

traceNumber

String

true

payorPaymentId

String

true

paymentChannelId

String

true

paymentChannelName

String

true

accountName

String

true

events

Array[Object]

false

Size must be between 1 and 2147483647 inclusive.

events[].eventId

String

false

events[].eventDateTime

String

false

events[].eventType

String

false

Must be one of [PAYOUT_SUBMITTED, PAYOUT_COMPLETED, PAYOUT_INSTRUCTED_V3, BANK_PAYMENT_REQUESTED, SOURCE_AMOUNT_CONFIRMED, PAYMENT_SUBMITTED, PAYMENT_SUBMITTED_ACCEPTED, PAYMENT_SUBMITTED_REJECTED, PAYMENT_CONFIRMED, PAYMENT_AWAITING_FUNDS, PAYMENT_FUNDED, PAYMENT_UNFUNDED, PAYMENT_FAILED, ACH_SUBMITTED_TO_ODFI, PAYMENT_ACCEPTED_BY_RAILS, ACH_RETURN_RECEIVED, RETURN_PAYMENT_FUNDING_REQUESTED, PAYOUT_BATCH_EXECUTED, PAYOUT_BATCH_QUOTE_EXPIRED, PAYOUT_BATCH_FUNDED, PAYOUT_BATCH_FUNDS_RETURN_REQUEST, PAYOUT_BATCH_FUNDS_RETURNED, PAYOUT_FUNDS_REQUEST, PAYOUT_FUNDS_GRANTED, PAYOUT_FUNDS_DENIED, PAYOUT_BATCH_QUOTED, PAYOUT_QUOTED, ACH_PAYMENT_RETURN_CANCELLED, RETURN_PAYMENT_CANCELLATION_REQUESTED, PAYOUT_WITHDRAWN].

events[].sourceCurrency

String

true

Must be a 3 character currency code e.g. USD, GBP, EUR.

events[].sourceAmount

Integer

true

events[].paymentCurrency

String

true

Must be a 3 character currency code e.g. USD, GBP, EUR.

events[].paymentAmount

Integer

true

events[].accountNumber

String

true

events[].iban

String

true

events[].routingNumber

String

true

events[].accountName

String

true

events[].principal

String

true

Example request

$ curl 'https://api.sandbox.velopayments.com/v3/paymentaudit/payments/95e05572-580c-4a58-bf1c-e13134fa9d19' -i -X GET \
    -H 'Authorization: Bearer 1e83e76f-dfee-4dff-b6f2-156bf769569e'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 1965

{
  "paymentId" : "e242a1a2-2894-453d-a1b6-3d56701820bd",
  "payeeId" : "43663cde-9390-4f68-a605-7965bf6907ec",
  "payorId" : "5397ce8a-5bcc-404c-9e3b-cf7cfdb3f084",
  "quoteId" : "425d58f7-38cd-46fc-8e76-46b32497cf0f",
  "sourceAccountId" : "b89a3009-e1cd-4c6f-a283-293ba2e858a7",
  "remoteId" : "abcd efghijklm",
  "sourceAmount" : 468,
  "sourceCurrency" : "USD",
  "paymentAmount" : 400,
  "paymentCurrency" : "EUR",
  "rate" : 1.1693,
  "invertedRate" : 0.86,
  "submittedDateTime" : "2017-09-13T11:41:30Z",
  "status" : "CONFIRMED",
  "fundingStatus" : "FUNDED",
  "routingNumber" : "XXXXX6789",
  "accountNumber" : "XXXXXX4321",
  "paymentMemo" : "Memo with Spaces",
  "payorPaymentId" : "1234567abc",
  "paymentChannelId" : "8080f22f-aa26-462f-bf20-31e63f277d7c",
  "paymentChannelName" : "PaymentChannel Bank",
  "events" : [ {
    "eventId" : "e5cc9237-647b-4521-be88-e7c4a9d0b6ec",
    "eventDateTime" : "2017-08-14T09:03:11.113Z",
    "eventType" : "PAYMENT_ACCEPTED_BY_RAILS",
    "principal" : "e542f1f5-e978-4515-a975-eaf283b211df"
  }, {
    "eventId" : "79402c9f-07ad-4f17-9b07-55b19edd6b1c",
    "eventDateTime" : "2017-07-23T04:01:33.111Z",
    "eventType" : "BANK_PAYMENT_REQUESTED",
    "paymentCurrency" : "EUR",
    "paymentAmount" : 400,
    "accountNumber" : "XXXXXX4321",
    "routingNumber" : "XXXXX6789",
    "principal" : "e542f1f5-e978-4515-a975-eaf283b211df"
  }, {
    "eventId" : "aa05966c-abfc-41b0-ac41-99fc939321e6",
    "eventDateTime" : "2017-07-23T01:01:32.111000902Z",
    "eventType" : "PAYMENT_SUBMITTED_ACCEPTED",
    "principal" : "e542f1f5-e978-4515-a975-eaf283b211df"
  }, {
    "eventId" : "9ab6203a-40c9-43bc-ab97-1a0bbea2dc62",
    "eventDateTime" : "2017-07-23T01:01:31.111000901Z",
    "eventType" : "PAYMENT_SUBMITTED",
    "paymentCurrency" : "EUR",
    "paymentAmount" : 400,
    "accountNumber" : "XXXXXX4321",
    "routingNumber" : "XXXXX6789",
    "principal" : "e542f1f5-e978-4515-a975-eaf283b211df"
  } ]
}

Get Payout Statistics

GET /v1/paymentaudit/payoutStatistics

Get payout statistics for a payor.

Authorization

User access token required.

Path parameters

No parameters.

Query parameters

Parameter Type Optional Description

payorId

Object

false

The id of the payor.

Request fields

No request body.

Response fields

Path Type Optional Description

thisMonthPayoutsCount

Integer

false

thisMonthFailedPaymentsCount

Integer

false

Example request

$ curl 'https://api.sandbox.velopayments.com/v1/paymentaudit/payoutStatistics?payorId=4a32f5da-d271-4b68-89d8-45f3ec645c1d' -i -X GET \
    -H 'Authorization: Bearer 01d807b1-aecd-4e3f-8cfb-a828d2520d37'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 71

{
  "thisMonthPayoutsCount" : 3,
  "thisMonthFailedPaymentsCount" : 2
}

Get Fundings For Payor

GET /v1/paymentaudit/fundings

Get a list of Fundings for a payor

(200 - OK, 400 - invalid request parameter).

Authorization

User access token required.

Path parameters

No parameters.

Query parameters

Parameter Type Optional Description

payorId

Object

false

The id of the payor.

page

Integer

true

Page number. Default is 1.

pageSize

Integer

true

Page size. Default is 25. Max allowable is 100.

sort

String

true

List of sort fields (e.g. ?sort=sourceAccountName:asc,amount:desc)
Default is no sort
The supported sort fields are: dateTime, amount, sourceAccountName, fundingType, fundingAccountName.

requestParams

Object

false

Request fields

No request body.

Response fields

Path Type Optional Description

links

Array[Object]

true

links[].rel

String

true

links[].href

String

true

page

Object

true

page.numberOfElements

Integer

true

page.totalElements

Integer

true

page.totalPages

Integer

true

page.page

Integer

true

page.pageSize

Integer

true

content

Array[Object]

true

Example request

$ curl 'https://api.sandbox.velopayments.com/v1/paymentaudit/fundings?payorId=7e2628af-3c0b-4f69-8a1d-3ea0df356a46' -i -X GET \
    -H 'Authorization: Bearer 84908cef-6de5-48ef-ad2e-8f1217fb55c3'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 1283

{
  "links" : [ {
    "rel" : "first",
    "href" : "https://api.sandbox.velopayments.com/v1/paymentaudit/fundings?payorId=7e2628af-3c0b-4f69-8a1d-3ea0df356a46&page=1&pageSize=25"
  }, {
    "rel" : "last",
    "href" : "https://api.sandbox.velopayments.com/v1/paymentaudit/fundings?payorId=7e2628af-3c0b-4f69-8a1d-3ea0df356a46&page=1&pageSize=25"
  }, {
    "rel" : "self",
    "href" : "https://api.sandbox.velopayments.com/v1/paymentaudit/fundings?payorId=7e2628af-3c0b-4f69-8a1d-3ea0df356a46&page=1&pageSize=25"
  } ],
  "page" : {
    "numberOfElements" : 1,
    "totalElements" : 1,
    "totalPages" : 1,
    "page" : 1,
    "pageSize" : 25
  },
  "content" : [ {
    "amount" : 10000,
    "dateTime" : "2018-12-17T12:31:48.406Z",
    "status" : "CREDIT",
    "currency" : "USD",
    "sourceAccountName" : "Payor Source account",
    "fundingAccountName" : "Payor funding account",
    "fundingType" : "ACH",
    "events" : [ {
      "eventId" : "ce18b87d-00f2-4f6c-bcd2-ac7cba476a77",
      "eventDateTime" : "2017-08-14T09:03:10.654Z",
      "fundingEventType" : "PAYOR_FUNDING_REQUESTED"
    }, {
      "eventId" : "467fb367-c81f-4d84-b705-153367f924da",
      "eventDateTime" : "2017-08-14T09:03:12.222Z",
      "fundingEventType" : "PAYOR_FUNDING_DETECTED"
    } ]
  } ]
}

Invite Service APIs

Validate Invite

GET /v1/invites/{inviteId}

Check if the link is still valid (204 - no content, 404 - invite not found).

Authorization

Resource is public.

Path parameters

Parameter Type Optional Description

inviteId

Object

false

A UUID value.

Query parameters

No parameters.

Request fields

No request body.

Response fields

No response body.

Example request

$ curl 'https://api.sandbox.velopayments.com/v1/invites/9558288a-0640-42ac-a96a-3d7eabe09475' -i -X GET \
    -H 'Content-Type: application/json'

Example response

HTTP/1.1 204 No Content

Validate Cellphone

POST /v1/invites/{inviteId}/smsTokens

Generate a OTP and send to the supplied phone number if valid (204 - no content, 400 - invalid request body, 404 - invite not found, 409 - password not set).

Authorization

Resource is public.

Path parameters

Parameter Type Optional Description

inviteId

Object

false

The Invite ID.

Query parameters

No parameters.

Request fields

Path Type Optional Description

cellphoneNumber

String

false

Must match the regular expression ^\+?[1-9]\d{1,14}$.

Response fields

No response body.

Example request

$ curl 'https://api.sandbox.velopayments.com/v1/invites/848e50b6-717f-4bd8-ad83-f2ecc6042aae/smsTokens' -i -X POST \
    -H 'Content-Type: application/json' \
    -d '{"cellphoneNumber": "4478009787464"}'

Example response

HTTP/1.1 204 No Content

Update Invite Options

POST /v1/invites/{inviteId}/optionsUpdate

Update the invite with acceptance of marketing options, plus terms and conditions (204 - no content, 400 - invalid request body, 404 - invite not found, 406 - invite in invalid state).

Authorization

Resource is public.

Path parameters

Parameter Type Optional Description

inviteId

Object

false

The inviteId.

Query parameters

No parameters.

Request fields

Path Type Optional Description

marketingOptIn

Boolean

false

acceptTermsAndConditions

Boolean

false

Response fields

No response body.

Example request

$ curl 'https://api.sandbox.velopayments.com/v1/invites/823eeeb4-d2a7-4774-98b7-4b003e4224d9/optionsUpdate' -i -X POST \
    -H 'Content-Type: application/json' \
    -d '{"marketingOptIn": true, "acceptTermsAndConditions": true}'

Example response

HTTP/1.1 204 No Content

Update

POST /v1/invites/{inviteId}

Update the invite with credentials needed for login (204 - no content, 404 - invite not found, 406 - Invite in invalid state).

Authorization

Resource is public.

Path parameters

Parameter Type Optional Description

inviteId

Object

false

The inviteId.

Query parameters

No parameters.

Request fields

Path Type Optional Description

password

String

true

Must be a string of 10 to 64 characters.
Must match the regular expression .*.

Response fields

No response body.

Example request

$ curl 'https://api.sandbox.velopayments.com/v1/invites/8d0cf254-80fc-4843-8ae2-d3424648b536' -i -X POST \
    -H 'Content-Type: application/json' \
    -d '{"password": "myPassword"}'

Example response

HTTP/1.1 204 No Content

Validate Sms Token

POST /v1/invites/{inviteId}/smsTokens/validate

Validate the OTP sent to the invited payee’s cellphone (204 - no content, 400 - OTP incorrect, 404 - invite not found).

Authorization

Resource is public.

Path parameters

Parameter Type Optional Description

inviteId

Object

false

A UUID.

Query parameters

No parameters.

Request fields

Path Type Optional Description

smsChallengeToken

String

false

Must match the regular expression [0-9]{6}+.

Response fields

No response body.

Example request

$ curl 'https://api.sandbox.velopayments.com/v1/invites/07056d0f-af93-487a-a9e4-138098440ce2/smsTokens/validate' -i -X POST \
    -H 'Content-Type: application/json' \
    -d '{"smsChallengeToken": "123456"}'

Example response

HTTP/1.1 204 No Content

Validate Password

POST /v1/invites/{inviteId}/passwords/validate

Check the password to ascertain if it satisfies validation criteria.

Authorization

Resource is public.

Path parameters

Parameter Type Optional Description

inviteId

Object

false

Query parameters

No parameters.

Request fields

Path Type Optional Description

password

String

false

Must match the regular expression .*.
Size must be between 1 and 128 inclusive.

Response fields

Path Type Optional Description

score

Integer

false

An integer score between 0 and 4 inclusive. More secure passwords are given a higher score. For a password to be acceptable for use in Velo, it must score at least 3.

valid

Boolean

true

True if the password is considered valid for use in Velo, for the payee.

warning

String

true

Any warning message as a reason for the given score.

suggestions

Array[String]

true

Any suggested changes to password text which would make the password more secure.

Example request

$ curl 'https://api.sandbox.velopayments.com/v1/invites/11d6e74f-e514-4aa0-bcfd-8b3ee2bbdace/passwords/validate' -i -X POST \
    -H 'Content-Type: application/json' \
    -d '{"password": "jamessmith"}'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 178

{
  "score" : 2,
  "valid" : false,
  "warning" : "Common names and surnames are easy to guess.",
  "suggestions" : [ "Add another word or two.", "Uncommon words are better." ]
}

Payout Service APIs

Submit Payout

POST /v3/payouts

Create a new payout and return a location header with a link to get the payout. Basic validation of the payout is performed before returning but more comprehensive validation is done asynchronously, the results of which can be obtained by issuing a HTTP GET to the URL returned in the location header. NOTE: amount values in payments must be in 'minor units' format. E.g. cents for USD, pence for GBP etc. with no decimal places.

Authorization

User access token required.

Path parameters

No parameters.

Query parameters

No parameters.

Request fields

Path Type Optional Description

payorId

String

false

payoutMemo

String

true

Size must be between 0 and 40 inclusive.

payments

Array[Object]

false

Size must be between 1 and 2000 inclusive.

payments[].remoteId

String

false

Size must be between 1 and 100 inclusive.

payments[].currency

String

false

Must be a 3 character currency code e.g. USD, GBP, EUR.

payments[].amount

Integer

false

Must be at least 1.

payments[].paymentMemo

String

true

Size must be between 0 and 40 inclusive.

payments[].sourceAccountName

String

false

Size must be between 1 and 64 inclusive.

payments[].payorPaymentId

String

true

Size must be between 0 and 40 inclusive.

Response fields

No response body.

Example request

$ curl 'https://api.sandbox.velopayments.com/v3/payouts' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer a0c4f656-ec75-4ae1-9855-12346e3a081d' \
    -d '{"payorId":"d7feffb6-56ee-4f0e-b61d-c7e2e877daa5","payments":[{"remoteId":"myRemoteId01","currency":"USD","amount":12345,"sourceAccountName":"PAYOR_SRC_ACCT","payorPaymentId":"1111"},{"remoteId":"myRemoteId02","currency":"USD","amount":23456,"sourceAccountName":"PAYOR_SRC_ACCT","payorPaymentId":"2222"},{"remoteId":"myRemoteId01","currency":"USD","amount":1020,"sourceAccountName":"PAYOR_SRC_ACCT","payorPaymentId":"3333"},{"remoteId":"myRemoteId03","currency":"USD","amount":3456,"sourceAccountName":"PAYOR_SRC_ACCT","payorPaymentId":"4444"},{"remoteId":"myRemoteId04","currency":"USD","amount":8765,"sourceAccountName":"PAYOR_SRC_ACCT","payorPaymentId":"5555"}]}'

Example response

HTTP/1.1 202 Accepted
Location: https://api.sandbox.velopayments.com/v3/payouts/497ab2e0-a443-407b-be78-75d7514dff0d

Submit Csv Payout

POST /v3/payouts

Create a new payout from a CSV source file and return a location header with a link to get the payout

Supported CSV fields are:

  • remoteId - mandatory - 100 chars max

  • currency - mandatory - 3 characters e.g. USD

  • amount - mandatory - expressed in minor units with no decimal point

  • payoutMemo - optional

  • sourceAccountName - mandatory - 64 characters max

  • payorPaymentId - optional - 40 characters max

If there are no valid payments in the csv file then no payout is created and a 400 (Bad Request) is returned.

Authorization

User access token required.

Path parameters

No parameters.

Query parameters

Parameter Type Optional Description

payorId

Object

false

payoutMemo

String

true

file

Object

false

Csv Structure

Field Name Type Optional Description

remoteId

String

false

Size must be between 1 and 100 inclusive.

currency

String

false

Must be a 3 character currency code e.g. USD, GBP, EUR.

amount

Long

false

Specified in minor units. Must be at least 1.

paymentMemo

String

true

Size must be between 0 and 40 inclusive.

sourceAccountName

String

false

Size must be between 1 and 64 inclusive.

payorPaymentId

String

true

Size must be between 0 and 40 inclusive.

Response fields

No response body.

Example request

$ curl 'https://api.sandbox.velopayments.com/v3/payouts?sourceCurrency=USD&payorId=30b09aaf-a56a-4363-b3e9-82115e612071&payoutMemo=this%20is%20the%20memo' -i -X POST \
    -H 'Content-Type: multipart/form-data' \
    -H 'Authorization: Bearer 5253daa7-5923-4b32-9c08-d03da3333d92' \
    -F 'file=@test.csv;type=text/plain' \
    -F 'sourceCurrency=USD' \
    -F 'payorId=30b09aaf-a56a-4363-b3e9-82115e612071' \
    -F 'payoutMemo=this is the memo'

Example response

HTTP/1.1 202 Accepted
Location: https://api.sandbox.velopayments.com/v3/payouts/acc4ec86-4c41-4c62-8440-2332d373a75c

Get Payout Summary

GET /v3/payouts/{payoutId}

Get payout summary - returns the current state of the payout.

Authorization

User access token required.

Path parameters

Parameter Type Optional Description

payoutId

Object

false

The id (UUID) of the payout.

Query parameters

No parameters.

Request fields

No request body.

Response fields

No response body.

Example request

$ curl 'https://api.sandbox.velopayments.com/v3/payouts/beb6da89-d4a2-4417-84ce-850477f1a25d' -i -X GET \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer 4227377a-0349-4645-b972-71745e57372c'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 1581

{
  "payoutId" : "beb6da89-d4a2-4417-84ce-850477f1a25d",
  "status" : "QUOTED",
  "paymentsSubmitted" : 5,
  "paymentsAccepted" : 3,
  "paymentsRejected" : 2,
  "fxSummaries" : [ {
    "quoteId" : "9fc99679-61e4-4eac-9cfc-dc2b5da412ec",
    "expiryTime" : "2019-01-02T19:07:41.194Z",
    "creationTime" : "2019-01-02T19:06:41.194Z",
    "rate" : 1.1599,
    "invertedRate" : 0.8621,
    "totalSourceAmount" : 1160,
    "totalPaymentAmount" : 1000,
    "sourceCurrency" : "USD",
    "paymentCurrency" : "EUR",
    "status" : "QUOTED",
    "fundingStatus" : "UNFUNDED"
  }, {
    "quoteId" : "9fc99679-61e4-4eac-9cfc-dc2b5da412ec",
    "expiryTime" : "2019-01-02T19:07:41.194Z",
    "creationTime" : "2019-01-02T19:06:41.194Z",
    "rate" : 1.3267,
    "invertedRate" : 0.7537,
    "totalSourceAmount" : 3980,
    "totalPaymentAmount" : 3000,
    "sourceCurrency" : "USD",
    "paymentCurrency" : "GBP",
    "status" : "QUOTED",
    "fundingStatus" : "UNFUNDED"
  } ],
  "accounts" : [ {
    "sourceAccountName" : "source account 1",
    "sourceAccountId" : "37fa813a-aa10-4cf1-853a-47005e97f437",
    "currency" : "USD",
    "totalPayoutCost" : 51
  } ],
  "rejectedPayments" : [ {
    "remoteId" : "myRemoteId03",
    "currencyType" : "EUR",
    "amount" : 1245,
    "sourceAccountName" : "source account 1",
    "payorPaymentId" : "Ref001",
    "reason" : "UNKNOWN_REMOTE_ID"
  }, {
    "remoteId" : "myRemoteId04",
    "currencyType" : "GBP",
    "amount" : 2999,
    "sourceAccountName" : "source account 1",
    "payorPaymentId" : "Ref001",
    "reason" : "OFAC_FAILED"
  } ]
}

Create Quote

POST /v3/payouts/{payoutId}/quote

Create a quote for the payout. Call this with an empty request body.

Authorization

User access token required.

Path parameters

Parameter Type Optional Description

payoutId

Object

false

Query parameters

No parameters.

Request fields

No request body.

Response fields

Path Type Optional Description

fxSummaries

Array[Object]

true

fxSummaries[].rate

Decimal

false

fxSummaries[].invertedRate

Decimal

false

fxSummaries[].creationTime

String

false

fxSummaries[].expiryTime

String

false

fxSummaries[].quoteId

String

false

fxSummaries[].totalSourceAmount

Integer

false

fxSummaries[].totalPaymentAmount

Integer

false

fxSummaries[].sourceCurrency

String

false

fxSummaries[].paymentCurrency

String

false

Example request

$ curl 'https://api.sandbox.velopayments.com/v3/payouts/b813710c-1f4f-4c57-b68e-32e1164e665d/quote' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer 5b1c5be5-0a05-43e7-9221-f04bc7894241'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 354

{
  "fxSummaries" : [ {
    "quoteId" : "3b39b426-9614-42e8-915b-03852bde34c6",
    "expiryTime" : "2019-01-02T19:07:40.795Z",
    "creationTime" : "2019-01-02T19:06:40.795Z",
    "rate" : 1.1599,
    "invertedRate" : 0.8621,
    "totalSourceAmount" : 11,
    "totalPaymentAmount" : 10,
    "sourceCurrency" : "USD",
    "paymentCurrency" : "EUR"
  } ]
}

Instruct Payout

POST /v3/payouts/{payoutId}

Instruct a payout to be made for the specified payoutId.

Authorization

User access token required.

Path parameters

Parameter Type Optional Description

payoutId

Object

false

The id (UUID) of the payout to instruct.

Query parameters

No parameters.

Request fields

No request body.

Response fields

No response body.

Example request

$ curl 'https://api.sandbox.velopayments.com/v3/payouts/7921e437-6dc8-4303-acf4-c57b29e429ea' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer 897e2e68-67df-42b9-a470-488c031285ac'

Example response

HTTP/1.1 202 Accepted

Withdraw Payout

DELETE /v3/payouts/{payoutId}

Withdraw Payout will delete payout details from payout service and rails services but will just move the status of the payout to WITHDRAWN in payment audit.

Authorization

User access token required.

Path parameters

Parameter Type Optional Description

payoutId

Object

false

Query parameters

No parameters.

Request fields

No request body.

Response fields

No response body.

Example request

$ curl 'https://api.sandbox.velopayments.com/v3/payouts/d2ebe556-2548-4c84-8d11-284323579f15' -i -X DELETE \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer f71cd117-f655-4261-a296-36078c4e88ab'

Example response

HTTP/1.1 202 Accepted

List Supported Countries

GET /v1/supportedCountries

List the supported countries.

Authorization

User access token required.

Path parameters

No parameters.

Query parameters

No parameters.

Request fields

No request body.

Response fields

Path Type Optional Description

countries

Array[Object]

true

countries[].isoCountryCode

String

true

countries[].currencies

Array[Object]

true

Example request

$ curl 'https://api.sandbox.velopayments.com/v1/supportedCountries' -i -X GET \
    -H 'Authorization: Bearer 89ad83a7-7c9f-412d-ac95-ad66a4c03223'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 347

{
  "countries" : [ {
    "isoCountryCode" : "US",
    "currencies" : [ "USD" ]
  }, {
    "isoCountryCode" : "GB",
    "currencies" : [ "GBP" ]
  }, {
    "isoCountryCode" : "FR",
    "currencies" : [ "EUR" ]
  }, {
    "isoCountryCode" : "CA",
    "currencies" : [ "CAD" ]
  }, {
    "isoCountryCode" : "JP",
    "currencies" : [ "JPY" ]
  } ]
}

List Supported Currencies

GET /v2/currencies

List the supported currencies.

Authorization

User access token required.

Path parameters

No parameters.

Query parameters

No parameters.

Request fields

No request body.

Response fields

Path Type Optional Description

currencies

Array[Object]

true

currencies[].currency

String

true

currencies[].maxPaymentAmount

Integer

true

Example request

$ curl 'https://api.sandbox.velopayments.com/v2/currencies' -i -X GET \
    -H 'Authorization: Bearer 43f7a557-715c-46de-81a2-c73057bca474'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 938

{
  "currencies" : [ {
    "currency" : "AUD",
    "maxPaymentAmount" : 1000
  }, {
    "currency" : "CAD",
    "maxPaymentAmount" : 1000
  }, {
    "currency" : "CHF",
    "maxPaymentAmount" : 1000
  }, {
    "currency" : "CNY",
    "maxPaymentAmount" : 1000
  }, {
    "currency" : "EUR",
    "maxPaymentAmount" : 1000
  }, {
    "currency" : "GBP",
    "maxPaymentAmount" : 1000
  }, {
    "currency" : "ILS",
    "maxPaymentAmount" : 1000
  }, {
    "currency" : "JPY",
    "maxPaymentAmount" : 1000
  }, {
    "currency" : "MXN",
    "maxPaymentAmount" : 1000
  }, {
    "currency" : "NOK",
    "maxPaymentAmount" : 1000
  }, {
    "currency" : "PHP",
    "maxPaymentAmount" : 1000
  }, {
    "currency" : "SGD",
    "maxPaymentAmount" : 1000
  }, {
    "currency" : "THB",
    "maxPaymentAmount" : 1000
  }, {
    "currency" : "USD",
    "maxPaymentAmount" : 1000
  }, {
    "currency" : "ZAR",
    "maxPaymentAmount" : 1000
  } ]
}

List Payment Channel Country Rules

GET /v1/paymentChannelRules

List the country specific payment channel rules.

Authorization

User access token required.

Path parameters

No parameters.

Query parameters

No parameters.

Request fields

No request body.

Response fields

Path Type Optional Description

bank

Array[Object]

true

bank[].isoCountryCode

String

true

bank[].rules

Array[Object]

true

bank[].rules[].element

String

true

bank[].rules[].required

Boolean

true

bank[].rules[].displayName

String

true

bank[].rules[].minLength

Integer

true

bank[].rules[].maxLength

Integer

true

bank[].rules[].validation

String

true

Example request

$ curl 'https://api.sandbox.velopayments.com/v1/paymentChannelRules' -i -X GET \
    -H 'Authorization: Bearer 2b0a083b-06d1-4c8c-af36-9f3b13d0b693'

Example response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 1254

{
  "bank" : [ {
    "isoCountryCode" : "US",
    "rules" : [ {
      "element" : "accountName",
      "required" : true,
      "displayName" : "Account Holder Name",
      "minLength" : 1,
      "maxLength" : 100,
      "validation" : "^.*$"
    }, {
      "element" : "accountNumber",
      "required" : true,
      "displayName" : "Account Number",
      "minLength" : 6,
      "maxLength" : 11,
      "validation" : "^[0-9]{6,11}$"
    }, {
      "element" : "routingNumber",
      "required" : true,
      "displayName" : "Routing Number",
      "minLength" : 9,
      "maxLength" : 9,
      "validation" : "^[0-9]{9}$"
    } ]
  }, {
    "isoCountryCode" : "GB",
    "rules" : [ {
      "element" : "accountName",
      "required" : true,
      "displayName" : "Account Holder Name",
      "minLength" : 1,
      "maxLength" : 100,
      "validation" : "^.*$"
    }, {
      "element" : "accountNumber",
      "required" : true,
      "displayName" : "Account Number",
      "minLength" : 8,
      "maxLength" : 8,
      "validation" : "^[0-9]{8}$"
    }, {
      "element" : "routingNumber",
      "required" : true,
      "displayName" : "Sort Code",
      "minLength" : 6,
      "maxLength" : 6,
      "validation" : "^[0-9]{6}$"
    } ]
  } ]
}
Velo secondary logo