Velo Payments APIs

OpenAPI apis-guru ecommerce

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.

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. 44a9537d-d55d-4b47-8082-14061c2bcdd8) and API secret (e.g. c396b26b-137a-44fd-87f5-34631f8fd529) with a colon between them. E.g. 44a9537d-d55d-4b47-8082-14061c2bcdd8:c396b26b-137a-44fd-87f5-34631f8fd529

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

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

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 NDRhOTUzN2QtZDU1ZC00YjQ3LTgwODItMTQwNjFjMmJjZGQ4OmMzOTZiMjZiLTEzN2EtNDRmZC04N2Y1LTM0NjMxZjhmZDUyOQ==" \  '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:

API access following authentication

Following successful authentication, the value of the access_token field in the response (indicated in green above) 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:

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.

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

Homepage: https://api.apis.guru/v2/specs/velopayments.com/2.34.63.json
Provider: velopayments.com
OpenAPI version: 3.0.2
Spec (JSON): https://api.apis.guru/v2/specs/velopayments.com/2.34.63/openapi.json
Spec (YAML): https://api.apis.guru/v2/specs/velopayments.com/2.34.63/openapi.yaml

Tools (102)

Extracted live via the executor SDK.

countries.listPaymentChannelRulesV1

List the country specific payment channel rules.
countries.listSupportedCountriesV1

List the supported countries.

This version will be retired in March 2020. Use /v2/supportedCountries
countries.listSupportedCountriesV2

List the supported countries.
currencies.listSupportedCurrenciesV2

List the supported currencies.
funding.createFundingRequestV2

Instruct a 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).
funding.createFundingRequestV3

Instruct a funding request to transfer funds from the payor’s funding bank to the payor’s balance held within Velo
funding.getFundingAccountsV2

Get the funding accounts.
funding.getFundingAccountV2

Get Funding Account by ID
funding.getFundingByIdV1

Get Funding by Id
funding.listFundingAuditDeltas

Get funding audit deltas for a payor
fundingManagerPrivate.createFundingAccountV2

Create Funding Account
fundingManagerPrivate.deleteSourceAccountV3

Mark a source account as deleted by ID
login.logout

Given a valid access token in the header then log out the authenticated user or client

Will revoke the token
login.resetPassword

Reset password

An email with an embedded link will be sent to the receipient of the email address

The link will contain a token to be used for resetting the password
login.validateAccessToken

The second part of login involves validating using an MFA device

An access token with PRE_AUTH authorities is required
login.veloAuth

Use this endpoint to obtain an access token for calling Velo Payments APIs.

You need your API key and API secret issued by Velo

To login and get an access token the API key and API secret must be Base64 encoded by concatenating them with a colon between them

e.g. Given an ApiKey: 44a9537d-d55d-4b47-8082-14061c2bcdd8 and ApiSecret: c396b26b-137a-44fd-87f5-34631f8fd529

Using a Base64 encode function Base64Encoder().encode("44a9537d-d55d-4b47-8082-14061c2bcdd8:c396b26b-137a-44fd-87f5-34631f8fd529")

Included as a Basic Authorization header: -H "Authorization: Basic NDRhOTUzN2QtZDU1ZC00YjQ3LTgwODItMTQwNjFjMmJjZGQ4OmMzOTZiMjZiLTEzN2EtNDRmZC04N2Y1LTM0NjMxZjhmZDUyOQ=="
payeeInvitation.createPayeeV3

Use v4 instead
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. In addition to standard semantic validations, a 400 will also result if there is a duplicate remote id within the batch / if there is a duplicate email within the batch, i.e. if there is a conflict between the data provided for one payee within the batch and that provided for another payee within the same batch). The validation at this stage is intra-batch only. Validation against payees who have already been invited occurs subsequently during processing of the batch.
payeeInvitation.getPayeesInvitationStatusV3

Use v4 instead

Returns a filtered, paginated list of payees associated with a payor, along with invitation status and grace period end date.
payeeInvitation.getPayeesInvitationStatusV4

Returns a filtered, paginated list of payees associated with a payor, along with invitation status and grace period end date.
payeeInvitation.queryBatchStatusV3

Use v4 instead
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 ).
payeeInvitation.queryBatchStatusV4

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 ).
payeeInvitation.resendPayeeInviteV3

Use v4 instead

Resend an invite to the Payee The payee must have already been invited by the payor and not yet accepted or declined

Any previous invites to the payee by this Payor will be invalidated
payeeInvitation.resendPayeeInviteV4

Resend an invite to the Payee The payee must have already been invited by the payor and not yet accepted or declined

Any previous invites to the payee by this Payor will be invalidated
payeeInvitation.v4CreatePayee
Initiate the process of creating 1 to 2000 payees in a batch

Use the batchId in the response to query for status.

In addition to standard semantic validations, a 400 will also result if:
- there is a duplicate remote id within the batch
- there is a duplicate email within the batch, i.e. if there is a conflict between the data provided for one payee within the batch and that provided for another payee within the same batch).
The validation at this stage is intra-batch only.

Validation against payees who have already been invited occurs subsequently during processing of the batch.
payees.deletePayeeByIdV3

Use v4 instead

This API will delete Payee by Id (UUID). Deletion by ID is not allowed if:

* Payee ID is not found

* If Payee has not been on-boarded

* If Payee is in grace period

* If Payee has existing payments
payees.deletePayeeByIdV4

This API will delete Payee by Id (UUID). Deletion by ID is not allowed if:

* Payee ID is not found

* If Payee has not been on-boarded

* If Payee is in grace period

* If Payee has existing payments
payees.getPayeeByIdV3

Use v4 instead

Get Payee by Id
payees.getPayeeByIdV4

Get Payee by Id
payees.listPayeeChangesV3

Use v4 instead

Get a paginated response listing payee changes.
payees.listPayeeChangesV4
Get a paginated response listing payee changes (updated since a particular time) to a limited set of fields:
- dbaName
- displayName
- email
- onboardedStatus
- payeeCountry
- payeeId
- remoteId
payees.listPayeesV3

Use v4 instead
Get a paginated response listing the payees for a payor.
payees.listPayeesV4

Get a paginated response listing the payees for a payor.
payees.payeeDetailsUpdateV3

Use v4 instead

Update payee details for the given Payee Id.
payees.payeeDetailsUpdateV4

Update payee details for the given Payee Id.

Payors may only update the payee details if the payee has not yet onboarded
payees.postV3PayeesPayeeIdRemoteIdUpdate

Use v4 instead

Update the remote Id for the given Payee Id.
payees.postV4PayeesPayeeIdRemoteIdUpdate

Update the remote Id for the given Payee Id.
paymentAuditService.exportTransactionsCsvV4

Download a CSV file containing payments in a date range. Uses Transfer-Encoding - chunked to stream to the client. Date range is inclusive of both the start and end dates.
paymentAuditService.getFundingsV4

Get a list of Fundings for a payor.
paymentAuditService.getPaymentDetailsV4

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

Get List of payments for Payout, allowing for RETURNED status
paymentAuditService.getPayoutsForPayorV4

Get List of payouts for payor
paymentAuditService.getPayoutStatsV4

Get payout statistics for a payor.
paymentAuditService.listPaymentChangesV4

Get a paginated response listing payment changes.
paymentAuditService.listPaymentsAuditV4

Get payments for the given payor Id
paymentAuditServiceDeprecated.exportTransactionsCsvV3

Deprecated (use /v4/paymentaudit/transactions instead)
paymentAuditServiceDeprecated.getFundingsV1

Deprecated (use /v4/paymentaudit/fundings)
paymentAuditServiceDeprecated.getPaymentDetailsV3

Deprecated (use /v4/paymentaudit/payments/ instead)
paymentAuditServiceDeprecated.getPaymentsForPayoutPaV3

Deprecated (use /v4/paymentaudit/payouts/ instead)
paymentAuditServiceDeprecated.getPayoutsForPayorV3

Deprecated (use /v4/paymentaudit/payouts instead)
paymentAuditServiceDeprecated.getPayoutStatsV1

Deprecated (Use /v4/paymentaudit/payoutStatistics)
paymentAuditServiceDeprecated.listPaymentChanges

Deprecated (use /v4/payments/deltas instead)
paymentAuditServiceDeprecated.listPaymentsAuditV3

Deprecated (use /v4/paymentaudit/payments instead)
payorHierarchy.payorLinksV1

If the payor is set up as part of a hierarchy you can use this API to traverse the hierarchy
payors.getPayorByIdV1

Get a Single Payor by Id.

deprecated since v2.10 - Use /v2/payors
payors.getPayorByIdV2

Get a Single Payor by Id.
payors.payorAddPayorLogoV1

Add Payor Logo

Logo file is used in your branding and emails sent to payees
payors.payorCreateApiKeyV1

Create an an API key for the given payor Id and application Id

You can create multiple API Keys for a given application

API Keys are programmatic users for integrating your application with the Velo platform
payors.payorCreateApplicationV1

Create an application for the given Payor ID.

Applications provide a means to group your API Keys

For example you might have an SAP application that you wish to integrate with Velo

You can create an application and then create one or more API keys for the application
payors.payorEmailOptOut

Update the emailRemindersOptOut field for a Payor. This API can be used to opt out or opt into Payor Reminder emails. These emails are typically around payee events such as payees registering and onboarding.
payors.payorGetBranding

Get the payor branding details.
payorsPrivate.createPayorLinks

This endpoint allows you to create a payor link.
payouts.createQuoteForPayoutV3

Create quote for a payout
payouts.deschedulePayout

Remove the schedule for a scheduled payout
payouts.getPaymentsForPayoutV3

Retrieve payments for a payout
payouts.getPayoutSummaryV3

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

Instruct a payout to be made for the specified payoutId.
payouts.scheduleForPayout

Schedule a payout for auto-instruction in the future or update existing payout schedule if the payout has been scheduled before.
payouts.submitPayoutV3

Create a new payout and return a location header with a link to the payout

Basic validation of the payout is performed before returning but more comprehensive validation is done asynchronously

The results 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
payouts.withdrawPayment
withdraw a payment

There are a variety of reasons why this can fail
- the payment must be in a state of 'accepted' or 'unfunded'
- the payout must not be in a state of 'instructed'
payouts.withdrawPayoutV3

Withdraw Payout will remove the payout details from the rails but the payout will still be accessible in payout service in WITHDRAWN status.
sourceAccounts.getSourceAccountsV2

List source accounts.
sourceAccounts.getSourceAccountsV3

List source accounts.
sourceAccounts.getSourceAccountV2

Get details about given source account.
sourceAccounts.getSourceAccountV3

Get details about given source account.
sourceAccounts.setNotificationsRequest

Set notifications for a given source account

deprecated since 2.34 (use v3 version)
sourceAccounts.setNotificationsRequestV3

Set notifications for a given source account

If the balance falls below the amount set in the request an email notification will be sent to the email address registered in the payor profile
sourceAccounts.transferFundsV2

Transfer funds between source accounts for a Payor. The 'from' source account is identified in the URL, and is the account which will be debited. The 'to' (destination) source account is in the body, and is the account which will be credited. Both source accounts must belong to the same Payor. There must be sufficient balance in the 'from' source account, otherwise the transfer attempt will fail.
sourceAccounts.transferFundsV3

Transfer funds between source accounts for a Payor. The 'from' source account is identified in the URL, and is the account which will be debited. The 'to' (destination) source account is in the body, and is the account which will be credited. Both source accounts must belong to the same Payor. There must be sufficient balance in the 'from' source account, otherwise the transfer attempt will fail.
tokens.resendToken

Resend the specified token

The token to resend must already exist for the user

It will be revoked and a new one issued
users.deleteUserByIdV2

Delete User by Id.
users.disableUserV2

If a user is enabled this endpoint will disable them

The invoker must have the appropriate permission

A user cannot disable themself

When a user is disabled any active access tokens will be revoked and the user will not be able to log in
users.enableUserV2

If a user has been disabled this endpoints will enable them

The invoker must have the appropriate permission

A user cannot enable themself

If the user is a payor user and the payor is disabled this operation is not allowed

If enabling a payor user would breach the limit for master admin payor users the request will be rejected
users.getSelf

Get the user's details
users.getUserByIdV2

Get a Single User by Id.
users.inviteUser

Create a User and invite them to the system
users.listUsers

Get a paginated response listing the Users
users.registerSms

Register an Sms number and send an OTP to it

Used for manual verification of a user

The backoffice user initiates the request to send the OTP to the user's sms

The user then reads back the OTP which the backoffice user enters in the verifactionCode property for requests that require it
users.roleUpdate

Update the user's Role
users.unlockUserV2

If a user is locked this endpoint will unlock them
users.unregisterMfa

Unregister the MFA device for the user

If the user does not require further verification then a register new MFA device token will be sent to them via their email address
users.unregisterMfaForSelf

Unregister the MFA device for the user

If the user does not require further verification then a register new MFA device token will be sent to them via their email address
users.updatePasswordSelf

Update password for self
users.userDetailsUpdate

Update the profile details for the given user

When updating Payor users with the role of payor.master_admin a verificationCode is required
users.userDetailsUpdateForSelf

Update the profile details for the given user

Only Payee user types are supported
users.validatePasswordSelf

validate the password and return a score
webhooks.createWebhookV1

Create Webhook
webhooks.getWebhookV1

Get details about the given webhook.
webhooks.listWebhooksV1

List the details about the webhooks for the given payor.
webhooks.pingWebhookV1

POST /v1/webhooks/{webhookId}/ping
webhooks.updateWebhookV1

Update Webhook
openapi.previewSpec

Preview an OpenAPI document before adding it as a source
openapi.addSource

Add an OpenAPI source and register its operations as tools