API docs by Redocly

Vality Wallet API (0.1.0)

Download OpenAPI specification:

Technical support team: support@vality.dev URL: https://api.vality.dev License: Apache 2.0 Terms of Service

The Vality Wallet API is the base and only point of interaction with the wallet system. All system state changes are carried out by calling the corresponding API methods. Any third party applications, including our websites and other UIs, are external client applications. The Vality API works on top of the HTTP protocol. We use REST architecture, the scheme is described according to OpenAPI 2.0. Return codes are described by the corresponding HTTP statuses. The system accepts and returns JSON values in the body of requests and responses.

Content Format

Any API request must be encoded in UTF-8 and must contain JSON content.

  Content-Type: application/json; charset=utf-8

Date format

The system accepts and returns timestamp values in the date-time format described in RFC 3339:

  2017-01-01T00:00:00Z
  2017-01-01T00:00:01+00:00

Maximum request processing time

In any API call, you can pass a timeout parameter in the X-Request-Deadline header of the corresponding request, which determines the maximum time to wait for the operation to complete on the request:

 X-Request-Deadline: 10s

After the specified time has elapsed, the system stops processing the request. It is recommended to specify a value of no more than one minute, but no less than three seconds. X-Request-Deadline can:

  • set in date-time format according to RFC 3339;
  • specified in relative terms: in milliseconds (150000ms), seconds (540s) or minutes (3.5m).

Request processing errors

During the processing of requests by our system, various unforeseen situations may occur. The system signals about their appearance via the HTTP protocol with the corresponding statuses, indicating server errors.

Code Description
500 An unexpected situation occurred while the system was processing the request. If you receive such a response code, we recommend that you contact technical support.
503 The system is temporarily unavailable and not ready to serve this request. The request is guaranteed to fail, if you receive a response code like this, try to implement it later when the system is restored to availability.
504 The system has exceeded the allowable request processing time, the result of the request is undefined. Try to resubmit the request or find out the result of the original request, if you do not want to re-execute the request.

Service providers

List available providers

Authorizations:
bearer
query Parameters
residence
string^[A-Za-z]{3}$

The residence within which the services are provided, [ISO 3166-1] country or region code (https://en.wikipedia.org/wiki/ISO_3166-1)

header Parameters
X-Request-ID
required
string [ 1 .. 32 ] characters

Unique identifier of the request to the system

X-Request-Deadline
string [ 1 .. 40 ] characters

Maximum request processing time

Responses

Response samples

Content type
application/json; charset=utf-8
[
  • {
    }
]

Get provider details

Authorizations:
bearer
path Parameters
providerID
required
string [ 1 .. 40 ] characters

Identifier of the provider

header Parameters
X-Request-ID
required
string [ 1 .. 32 ] characters

Unique identifier of the request to the system

X-Request-Deadline
string [ 1 .. 40 ] characters

Maximum request processing time

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "id": "serviceprovider",
  • "name": "SERVICE PROVIDER LLC",
  • "residences": [
    ]
}

Identities

List the identities of the owners

Authorizations:
bearer
query Parameters
partyID
string [ 1 .. 40 ] characters

The participant's unique identifier within the system.

providerID
string [ 1 .. 40 ] characters

Service provider's identifier

continuationToken
string

A token signalling that only part of the data has been transmitted in the response. To retrieve the next part, you need repeat the request to the service again, specifying the same set of conditions and the received token. If there is no token, the last piece of data is received.

header Parameters
X-Request-ID
required
string [ 1 .. 32 ] characters

Unique identifier of the request to the system

X-Request-Deadline
string [ 1 .. 40 ] characters

Maximum request processing time

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "continuationToken": "string",
  • "result": [
    ]
}

Create owner identity

Authorizations:
bearer
header Parameters
X-Request-ID
required
string [ 1 .. 32 ] characters

Unique identifier of the request to the system

X-Request-Deadline
string [ 1 .. 40 ] characters

Maximum request processing time

Request Body schema: application/json; charset=utf-8
required

Data of the identity created

name
required
string

Human-readable name of the owner's identity, by which he can be easily identified

provider
required
string

Identifier of the service provider

metadata
object

Some non-transparent for system set of data associated with this identity

externalID
string

The unique identifier of the entity on your side.

When specified, will be used to ensure idempotent processing of the operation.

partyID
string [ 1 .. 40 ] characters

The participant's unique identifier within the system.

Responses

Request samples

Content type
application/json; charset=utf-8
{
  • "name": "Keyn Fawkes",
  • "provider": "serviceprovider",
  • "metadata": {
    },
  • "externalID": "10036274",
  • "partyID": "string"
}

Response samples

Content type
application/json; charset=utf-8
{
  • "id": "10036274",
  • "name": "Keyn Fawkes",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "provider": "serviceprovider",
  • "isBlocked": false,
  • "metadata": {
    },
  • "externalID": "10036274",
  • "partyID": "string"
}

Get the owner's identity

Authorizations:
bearer
path Parameters
identityID
required
string [ 1 .. 40 ] characters

Identifier of the owner's identity

header Parameters
X-Request-ID
required
string [ 1 .. 32 ] characters

Unique identifier of the request to the system

X-Request-Deadline
string [ 1 .. 40 ] characters

Maximum request processing time

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "id": "10036274",
  • "name": "Keyn Fawkes",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "provider": "serviceprovider",
  • "isBlocked": false,
  • "metadata": {
    },
  • "externalID": "10036274",
  • "partyID": "string"
}

Get withdrawal methods available by owner identity

Authorizations:
bearer
path Parameters
identityID
required
string [ 1 .. 40 ] characters

Identifier of the owner's identity

header Parameters
X-Request-ID
required
string [ 1 .. 32 ] characters

Unique identifier of the request to the system

X-Request-Deadline
string [ 1 .. 40 ] characters

Maximum request processing time

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "methods": [
    ]
}

Wallets

Get wallet by specified external identifier

Authorizations:
bearer
query Parameters
externalID
required
string [ 1 .. 40 ] characters

External wallet identifier

header Parameters
X-Request-ID
required
string [ 1 .. 32 ] characters

Unique identifier of the request to the system

X-Request-Deadline
string [ 1 .. 40 ] characters

Maximum request processing time

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "id": "10068321",
  • "name": "Worldwide PHP Awareness Initiative",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "isBlocked": false,
  • "identity": "10036274",
  • "currency": "USD",
  • "metadata": {
    },
  • "externalID": "10036274"
}

List the wallets

Authorizations:
bearer
query Parameters
partyID
string [ 1 .. 40 ] characters

The participant's unique identifier within the system.

identityID
string [ 1 .. 40 ] characters

Identifier of owner's identity

currencyID
string^[A-Z]{3}$

Currency, character code according to ISO 4217.

limit
required
integer <int32> [ 1 .. 1000 ]

Selection limit

continuationToken
string

A token signalling that only part of the data has been transmitted in the response. To retrieve the next part, you need repeat the request to the service again, specifying the same set of conditions and the received token. If there is no token, the last piece of data is received.

header Parameters
X-Request-ID
required
string [ 1 .. 32 ] characters

Unique identifier of the request to the system

X-Request-Deadline
string [ 1 .. 40 ] characters

Maximum request processing time

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "continuationToken": "string",
  • "result": [
    ]
}

Create a new wallet

Authorizations:
bearer
header Parameters
X-Request-ID
required
string [ 1 .. 32 ] characters

Unique identifier of the request to the system

X-Request-Deadline
string [ 1 .. 40 ] characters

Maximum request processing time

Request Body schema: application/json; charset=utf-8
required

Data of the created wallet

name
required
string

Human-readable name of the wallet, by which it is easy to recognize

identity
required
string

Identifier of wallet owner

currency
required
string^[A-Z]{3}$

Currency character code according to ISO 4217.

metadata
object

Some non-transparent for system set of data associated with this wallet

externalID
string

The unique identifier of the entity on your side.

When specified, will be used to ensure idempotent processing of the operation.

Responses

Request samples

Content type
application/json; charset=utf-8
{
  • "name": "Worldwide PHP Awareness Initiative",
  • "identity": "10036274",
  • "currency": "USD",
  • "metadata": {
    },
  • "externalID": "10036274"
}

Response samples

Content type
application/json; charset=utf-8
{
  • "id": "10068321",
  • "name": "Worldwide PHP Awareness Initiative",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "isBlocked": false,
  • "identity": "10036274",
  • "currency": "USD",
  • "metadata": {
    },
  • "externalID": "10036274"
}

Get wallet data

Authorizations:
bearer
path Parameters
walletID
required
string [ 1 .. 40 ] characters

Identifier of the wallet

header Parameters
X-Request-ID
required
string [ 1 .. 32 ] characters

Unique identifier of the request to the system

X-Request-Deadline
string [ 1 .. 40 ] characters

Maximum request processing time

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "id": "10068321",
  • "name": "Worldwide PHP Awareness Initiative",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "isBlocked": false,
  • "identity": "10036274",
  • "currency": "USD",
  • "metadata": {
    },
  • "externalID": "10036274"
}

Get account status

Authorizations:
bearer
path Parameters
walletID
required
string [ 1 .. 40 ] characters

Identifier of the wallet

header Parameters
X-Request-ID
required
string [ 1 .. 32 ] characters

Unique identifier of the request to the system

X-Request-Deadline
string [ 1 .. 40 ] characters

Maximum request processing time

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "own": {
    },
  • "available": {
    }
}

Grant the right to manage funds

Authorizations:
bearer
path Parameters
walletID
required
string [ 1 .. 40 ] characters

Identifier of the wallet

header Parameters
X-Request-ID
required
string [ 1 .. 32 ] characters

Unique identifier of the request to the system

X-Request-Deadline
string [ 1 .. 40 ] characters

Maximum request processing time

Request Body schema: application/json; charset=utf-8
required

Request for the right to manage funds on the wallet

required
object

Amount of funds allowed for use

validUntil
required
string <date-time>

Date and time until which the granted right is valid

Responses

Request samples

Content type
application/json; charset=utf-8
{
  • "asset": {
    },
  • "validUntil": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json; charset=utf-8
{
  • "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5M\nDIyfQ.XbPfbIHMI6arZ3Y922BhjWgQzWXcXNrz0ogtVhfEd2o\n",
  • "asset": {
    },
  • "validUntil": "2019-08-24T14:15:22Z"
}

Deposits

Finding adjustments

Authorizations:
bearer
query Parameters
partyID
string [ 1 .. 40 ] characters

The participant's unique identifier within the system.

walletID
string [ 1 .. 40 ] characters

Wallet identifier

identityID
string [ 1 .. 40 ] characters

Identifier of the owner's identity

depositID
string [ 1 .. 50 ] characters

Identifier of the input of funds

sourceID
string [ 1 .. 40 ] characters

Identifier of the fund source

status
string
Enum: "Pending" "Succeeded" "Failed"
createdAtFrom
string <date-time>

Creation date from

createdAtTo
string <date-time>

Creation date to

amountFrom
integer <int64>

Amount of monetary funds in minor units

amountTo
integer <int64>

Amount of monetary funds in minor units

currencyID
string^[A-Z]{3}$

Currency, character code according to ISO 4217.

limit
required
integer <int32> [ 1 .. 1000 ]

Selection limit

continuationToken
string

A token signalling that only part of the data has been transmitted in the response. To retrieve the next part, you need repeat the request to the service again, specifying the same set of conditions and the received token. If there is no token, the last piece of data is received.

header Parameters
X-Request-ID
required
string [ 1 .. 32 ] characters

Unique identifier of the request to the system

X-Request-Deadline
string [ 1 .. 40 ] characters

Maximum request processing time

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "continuationToken": "string",
  • "result": [
    ]
}

Search for reverts

Authorizations:
bearer
query Parameters
partyID
string [ 1 .. 40 ] characters

The participant's unique identifier within the system.

walletID
string [ 1 .. 40 ] characters

Identifier of the wallet

identityID
string [ 1 .. 40 ] characters

Identifier of the owner's identity

depositID
string [ 1 .. 50 ] characters

Identifier of the input of funds

sourceID
string [ 1 .. 40 ] characters

Identifier of the source of funds

status
string
Enum: "Pending" "Succeeded" "Failed"
createdAtFrom
string <date-time>

Creation date from

createdAtTo
string <date-time>

Creation date to

amountFrom
integer <int64>

Amount of monetary funds in minor units

amountTo
integer <int64>

Amount of monetary funds in minor units

currencyID
string^[A-Z]{3}$

Currency, character code according to ISO 4217.

limit
required
integer <int32> [ 1 .. 1000 ]

Selection limit

continuationToken
string

A token signalling that only part of the data has been transmitted in the response. To retrieve the next part, you need repeat the request to the service again, specifying the same set of conditions and the received token. If there is no token, the last piece of data is received.

header Parameters
X-Request-ID
required
string [ 1 .. 32 ] characters

Unique identifier of the request to the system

X-Request-Deadline
string [ 1 .. 40 ] characters

Maximum request processing time

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "continuationToken": "string",
  • "result": [
    ]
}

Search for deposits

Authorizations:
bearer
query Parameters
partyID
string [ 1 .. 40 ] characters

The participant's unique identifier within the system.

walletID
string [ 1 .. 40 ] characters

Identifier of the wallet

identityID
string [ 1 .. 40 ] characters

Identifier of the owner's identity

depositID
string [ 1 .. 50 ] characters

Identifier of the deposit

sourceID
string [ 1 .. 40 ] characters

Identifier of the funds source

status
string
Enum: "Pending" "Succeeded" "Failed"
createdAtFrom
string <date-time>

Creation date from

createdAtTo
string <date-time>

Creation date to

revertStatus
string
Enum: "None" "Partial" "Full"
amountFrom
integer <int64>

Amount of monetary funds in minor units

amountTo
integer <int64>

Amount of monetary funds in minor units

currencyID
string^[A-Z]{3}$

Currency, character code according to ISO 4217.

limit
required
integer <int32> [ 1 .. 1000 ]

Selection limit

continuationToken
string

A token signalling that only part of the data has been transmitted in the response. To retrieve the next part, you need repeat the request to the service again, specifying the same set of conditions and the received token. If there is no token, the last piece of data is received.

header Parameters
X-Request-ID
required
string [ 1 .. 32 ] characters

Unique identifier of the request to the system

X-Request-Deadline
string [ 1 .. 40 ] characters

Maximum request processing time

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "continuationToken": "string",
  • "result": [
    ]
}

Withdrawals

List of destinations

Authorizations:
bearer
query Parameters
partyID
string [ 1 .. 40 ] characters

The participant's unique identifier within the system.

identityID
string [ 1 .. 40 ] characters

Identifier of the owner's idenity

currencyID
string^[A-Z]{3}$

Currency, character code according to ISO 4217.

limit
required
integer <int32> [ 1 .. 1000 ]

Selection limit

continuationToken
string

A token signalling that only part of the data has been transmitted in the response. To retrieve the next part, you need repeat the request to the service again, specifying the same set of conditions and the received token. If there is no token, the last piece of data is received.

header Parameters
X-Request-ID
required
string [ 1 .. 32 ] characters

Unique identifier of the request to the system

X-Request-Deadline
string [ 1 .. 40 ] characters

Maximum request processing time

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "continuationToken": "string",
  • "result": [
    ]
}

Start a destination creation

Authorizations:
bearer
header Parameters
X-Request-ID
required
string [ 1 .. 32 ] characters

Unique identifier of the request to the system

X-Request-Deadline
string [ 1 .. 40 ] characters

Maximum request processing time

Request Body schema: application/json; charset=utf-8
required

Destination data

name
required
string

A human-readable name for the destination by which it is easily recognizable

identity
required
string

Identifier of wallet owner

currency
required
string^[A-Z]{3}$

Currency character code according to ISO 4217.

required
object (DestinationResource)

Destination resource used to make withdrawals

object (DestinationAuthData)

Destination auth data to make withdrawals

metadata
object

Some non-transparent for system set of data associated with this destination

externalID
string

The unique identifier of the entity on your side.

When specified, will be used to ensure idempotent processing of the operation.

Responses

Request samples

Content type
application/json; charset=utf-8
{
  • "name": "Squarey plastic thingy",
  • "identity": "10036274",
  • "currency": "USD",
  • "resource": {
    },
  • "additionalAuthData": {
    },
  • "metadata": {
    },
  • "externalID": "10036274"
}

Response samples

Content type
application/json; charset=utf-8
{
  • "id": "107498",
  • "name": "Squarey plastic thingy",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "isBlocked": false,
  • "identity": "10036274",
  • "currency": "USD",
  • "resource": {
    },
  • "additionalAuthData": {
    },
  • "metadata": {
    },
  • "externalID": "10036274",
  • "status": "Authorized",
  • "validUntil": "2019-08-24T14:15:22Z"
}

Get a specific destination

Authorizations:
bearer
path Parameters
destinationID
required
string [ 1 .. 40 ] characters

Identifier of the destination

header Parameters
X-Request-ID
required
string [ 1 .. 32 ] characters

Unique identifier of the request to the system

X-Request-Deadline
string [ 1 .. 40 ] characters

Maximum request processing time

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "id": "107498",
  • "name": "Squarey plastic thingy",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "isBlocked": false,
  • "identity": "10036274",
  • "currency": "USD",
  • "resource": {
    },
  • "additionalAuthData": {
    },
  • "metadata": {
    },
  • "externalID": "10036274",
  • "status": "Authorized",
  • "validUntil": "2019-08-24T14:15:22Z"
}

Grant the right to manage the destinations

Authorizations:
bearer
path Parameters
destinationID
required
string [ 1 .. 40 ] characters

Identifier of the destination

header Parameters
X-Request-ID
required
string [ 1 .. 32 ] characters

Unique identifier of the request to the system

X-Request-Deadline
string [ 1 .. 40 ] characters

Maximum request processing time

Request Body schema: application/json; charset=utf-8
required

Request for the right to manage the destinations

validUntil
required
string <date-time>

The date and time by which the granted right is valid

Responses

Request samples

Content type
application/json; charset=utf-8
{
  • "validUntil": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json; charset=utf-8
{
  • "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5M\nDIyfQ.XbPfbIHMI6arZ3Y922BhjWgQzWXcXNrz0ogtVhfEd2o\n",
  • "validUntil": "2019-08-24T14:15:22Z"
}

Get a destination by external identifier

Authorizations:
bearer
path Parameters
externalID
required
string

External identifier

header Parameters
X-Request-ID
required
string [ 1 .. 32 ] characters

Unique identifier of the request to the system

X-Request-Deadline
string [ 1 .. 40 ] characters

Maximum request processing time

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "id": "107498",
  • "name": "Squarey plastic thingy",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "isBlocked": false,
  • "identity": "10036274",
  • "currency": "USD",
  • "resource": {
    },
  • "additionalAuthData": {
    },
  • "metadata": {
    },
  • "externalID": "10036274",
  • "status": "Authorized",
  • "validUntil": "2019-08-24T14:15:22Z"
}

Get withdrawal status by external identifier

Authorizations:
bearer
path Parameters
externalID
required
string

External identifier

header Parameters
X-Request-ID
required
string [ 1 .. 32 ] characters

Unique identifier of the request to the system

X-Request-Deadline
string [ 1 .. 40 ] characters

Maximum request processing time

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "id": "tZ0jUmlsV0",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "wallet": "10068321",
  • "destination": "107498",
  • "body": {
    },
  • "fee": {
    },
  • "metadata": {
    },
  • "externalID": "10036274",
  • "quote": {
    },
  • "status": "Pending",
  • "failure": {
    }
}

Quote preparation

Fixing the exchange rate for making withdrawals with conversion

Authorizations:
bearer
header Parameters
X-Request-ID
required
string [ 1 .. 32 ] characters

Unique identifier of the request to the system

X-Request-Deadline
string [ 1 .. 40 ] characters

Maximum request processing time

Request Body schema: application/json; charset=utf-8
required

Quote data for withdrawal

externalID
string

The unique identifier of the entity on your side.

When specified, will be used to ensure idempotent processing of the operation.

walletID
required
string

Identifier of the wallet

destinationID
string

Destination identifier

currencyFrom
required
string^[A-Z]{3}$

Source currency code

currencyTo
required
string^[A-Z]{3}$

Target currency code

required
object

The amount of funds for receiving a quote in one of the exchange currencies

walletGrant
string [ 1 .. 4000 ] characters

A token that gives the right to withdraw from the wallet to pay for the withdrawal. It is necessary to provide if the withdrawal is made at the expense of the funds of a foreign wallet. The owner of the specified wallet can issue this right

destinationGrant
string [ 1 .. 4000 ] characters

A token that gives the right to withdraw. Must be provided if the withdrawal is made through a foreign fund recipient. The owner of the specified recipient can grant this right

Responses

Request samples

Content type
application/json; charset=utf-8
{
  • "externalID": "10036274",
  • "walletID": "10068321",
  • "destinationID": "107498",
  • "currencyFrom": "USD",
  • "currencyTo": "USD",
  • "cash": {
    },
  • "walletGrant": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5M\nDIyfQ.XbPfbIHMI6arZ3Y922BhjWgQzWXcXNrz0ogtVhfEd2o\n",
  • "destinationGrant": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5M\nDIyfQ.XbPfbIHMI6arZ3Y922BhjWgQzWXcXNrz0ogtVhfEd2o\n"
}

Response samples

Content type
application/json; charset=utf-8
{
  • "cashFrom": {
    },
  • "cashTo": {
    },
  • "createdAt": "2019-08-24T14:15:22Z",
  • "expiresOn": "2019-08-24T14:15:22Z",
  • "quoteToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5M\nDIyfQ.XbPfbIHMI6arZ3Y922BhjWgQzWXcXNrz0ogtVhfEd2o\n"
}

Search of withdrawals

Authorizations:
bearer
query Parameters
partyID
string [ 1 .. 40 ] characters

The participant's unique identifier within the system.

walletID
string [ 1 .. 40 ] characters

Identifier of the wallet

identityID
string [ 1 .. 40 ] characters

Identifier of the owner's identity

withdrawalID
string [ 1 .. 40 ] characters

Identifier of the funds withdrawal

externalID
string [ 1 .. 40 ] characters

Identifier of the external's ID

destinationID
string [ 1 .. 40 ] characters

Identifier of the destination

status
string
Enum: "Pending" "Succeeded" "Failed"
createdAtFrom
string <date-time>

Creation date range start

createdAtTo
string <date-time>

Creation date range end

amountFrom
integer <int64>

Amount of monetary funds in minor units

amountTo
integer <int64>

Amount of monetary funds in minor units

currencyID
string^[A-Z]{3}$

Currency, character code according to ISO 4217.

limit
required
integer <int32> [ 1 .. 1000 ]

Selection limit

continuationToken
string

A token signalling that only part of the data has been transmitted in the response. To retrieve the next part, you need repeat the request to the service again, specifying the same set of conditions and the received token. If there is no token, the last piece of data is received.

header Parameters
X-Request-ID
required
string [ 1 .. 32 ] characters

Unique identifier of the request to the system

X-Request-Deadline
string [ 1 .. 40 ] characters

Maximum request processing time

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "continuationToken": "string",
  • "result": [
    ]
}

Create withdrawal

Authorizations:
bearer
header Parameters
X-Request-ID
required
string [ 1 .. 32 ] characters

Unique identifier of the request to the system

X-Request-Deadline
string [ 1 .. 40 ] characters

Maximum request processing time

Request Body schema: application/json; charset=utf-8
required

Withdrawal data

wallet
required
string

Identifier of the wallet

destination
required
string

Destination identifier

required
object

Amount of funds to be withdrawn

object

Fee amount

metadata
object

Some non-transparent for system set of data associated with this withdrawal

externalID
string

The unique identifier of the entity on your side.

When specified, will be used to ensure idempotent processing of the operation.

object

Quote data for withdrawal

walletGrant
string [ 1 .. 4000 ] characters

A token that gives the right to withdraw from the wallet to pay for the withdrawal.

Must be provided if withdrawal is made at the expense of foreign wallet. The owner of said wallet can issue this right.

destinationGrant
string [ 1 .. 4000 ] characters

A token that gives the right to withdraw.

Must be provided if the withdrawal is made through a foreign recipient of funds. The owner of the specified recipient can issue this right.

quoteToken
string [ 1 .. 4000 ] characters

Quote at which funds should be withdrawn.

Must be obtained in advance for each individual withdrawal operation with conversion.

Responses

Request samples

Content type
application/json; charset=utf-8
{
  • "wallet": "10068321",
  • "destination": "107498",
  • "body": {
    },
  • "fee": {
    },
  • "metadata": {
    },
  • "externalID": "10036274",
  • "quote": {
    },
  • "walletGrant": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5M\nDIyfQ.XbPfbIHMI6arZ3Y922BhjWgQzWXcXNrz0ogtVhfEd2o\n",
  • "destinationGrant": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5M\nDIyfQ.XbPfbIHMI6arZ3Y922BhjWgQzWXcXNrz0ogtVhfEd2o\n",
  • "quoteToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5M\nDIyfQ.XbPfbIHMI6arZ3Y922BhjWgQzWXcXNrz0ogtVhfEd2o\n"
}

Response samples

Content type
application/json; charset=utf-8
{
  • "id": "tZ0jUmlsV0",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "wallet": "10068321",
  • "destination": "107498",
  • "body": {
    },
  • "fee": {
    },
  • "metadata": {
    },
  • "externalID": "10036274",
  • "quote": {
    },
  • "status": "Pending",
  • "failure": {
    }
}

Get withdrawal status

Authorizations:
bearer
path Parameters
withdrawalID
required
string [ 1 .. 40 ] characters

Identifier of the withdrawal

header Parameters
X-Request-ID
required
string [ 1 .. 32 ] characters

Unique identifier of the request to the system

X-Request-Deadline
string [ 1 .. 40 ] characters

Maximum request processing time

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "id": "tZ0jUmlsV0",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "wallet": "10068321",
  • "destination": "107498",
  • "body": {
    },
  • "fee": {
    },
  • "metadata": {
    },
  • "externalID": "10036274",
  • "quote": {
    },
  • "status": "Pending",
  • "failure": {
    }
}

Request withdrawal events

Authorizations:
bearer
path Parameters
withdrawalID
required
string [ 1 .. 40 ] characters

Identifier of the withdrawal

query Parameters
limit
required
integer <int32> [ 1 .. 1000 ]

Selection limit

eventCursor
integer <int32>

The identifier of the last known event.

All events that occurred after the specified one will be included in the selection. If this parameter is not specified, the selection will include events starting from the very first one.

header Parameters
X-Request-ID
required
string [ 1 .. 32 ] characters

Unique identifier of the request to the system

X-Request-Deadline
string [ 1 .. 40 ] characters

Maximum request processing time

Responses

Response samples

Content type
application/json; charset=utf-8
[
  • {
    }
]

Get an event of withdrawal

Authorizations:
bearer
path Parameters
withdrawalID
required
string [ 1 .. 40 ] characters

Identifier of the withdrawal

eventID
required
integer <int32>

Identifier of the identification procedure event.

header Parameters
X-Request-ID
required
string [ 1 .. 32 ] characters

Unique identifier of the request to the system

X-Request-Deadline
string [ 1 .. 40 ] characters

Maximum request processing time

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "eventID": 42,
  • "occuredAt": "2019-08-24T14:15:22Z",
  • "changes": [
    ]
}

Residences

Get a description of the residence region

Authorizations:
bearer
path Parameters
residence
required
string^[A-Za-z]{3}$

The residence within which the services are provided, [ISO 3166-1] country or region code (https://en.wikipedia.org/wiki/ISO_3166-1)

header Parameters
X-Request-ID
required
string [ 1 .. 32 ] characters

Unique identifier of the request to the system

X-Request-Deadline
string [ 1 .. 40 ] characters

Maximum request processing time

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "id": "RUS",
  • "name": "The United States of America",
  • "flag": "πŸ‡ΊπŸ‡Έ"
}

Currencies

Get currency description

Authorizations:
bearer
path Parameters
currencyID
required
string^[A-Za-z]{3}$

Currency character code according to ISO 4217.

header Parameters
X-Request-ID
required
string [ 1 .. 32 ] characters

Unique identifier of the request to the system

X-Request-Deadline
string [ 1 .. 40 ] characters

Maximum request processing time

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "id": "USD",
  • "numericCode": "840",
  • "name": "United States Dollar",
  • "sign": "$",
  • "exponent": 2
}

Reports

createReport

Generate a report with the specified type on the identity of the owner for the specified period of time

Authorizations:
bearer
path Parameters
identityID
required
string [ 1 .. 40 ] characters

Identifier of the owner's identity

query Parameters
partyID
string [ 1 .. 40 ] characters

The participant's unique identifier within the system.

header Parameters
X-Request-ID
required
string [ 1 .. 32 ] characters

Unique identifier of the request to the system

X-Request-Deadline
string [ 1 .. 40 ] characters

Maximum request processing time

Request Body schema: application/json; charset=utf-8
required

Report generation options

reportType
required
string
Value: "withdrawalRegistry"

Type of report

fromTime
required
string <date-time>

Start of the time period

toTime
required
string <date-time>

End of the time period

Responses

Request samples

Content type
application/json; charset=utf-8
{
  • "reportType": "withdrawalRegistry",
  • "fromTime": "2019-08-24T14:15:22Z",
  • "toTime": "2019-08-24T14:15:22Z"
}

Response samples

Content type
application/json; charset=utf-8
{
  • "id": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "fromTime": "2019-08-24T14:15:22Z",
  • "toTime": "2019-08-24T14:15:22Z",
  • "status": "pending",
  • "type": "withdrawalRegistry",
  • "files": [
    ]
}

getReports

Get a list of owner identity reports for a period

Authorizations:
bearer
path Parameters
identityID
required
string [ 1 .. 40 ] characters

Identifier of the owner's identity

query Parameters
partyID
string [ 1 .. 40 ] characters

The participant's unique identifier within the system.

fromTime
required
string <date-time>

Start of the time period

toTime
required
string <date-time>

End of the time period

type
string
Value: "withdrawalRegistry"

Type of reports received

header Parameters
X-Request-ID
required
string [ 1 .. 32 ] characters

Unique identifier of the request to the system

X-Request-Deadline
string [ 1 .. 40 ] characters

Maximum request processing time

Responses

Response samples

Content type
application/json; charset=utf-8
[
  • {
    }
]

getReport

Get a report for a given identifier

Authorizations:
bearer
path Parameters
identityID
required
string [ 1 .. 40 ] characters

Identifier of the owner's identity

reportID
required
integer <int64>

The report identifier

query Parameters
partyID
string [ 1 .. 40 ] characters

The participant's unique identifier within the system.

header Parameters
X-Request-ID
required
string [ 1 .. 32 ] characters

Unique identifier of the request to the system

X-Request-Deadline
string [ 1 .. 40 ] characters

Maximum request processing time

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "id": 0,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "fromTime": "2019-08-24T14:15:22Z",
  • "toTime": "2019-08-24T14:15:22Z",
  • "status": "pending",
  • "type": "withdrawalRegistry",
  • "files": [
    ]
}

File upload

downloadFile

Get a link to download a file

Authorizations:
bearer
path Parameters
fileID
required
string [ 1 .. 40 ] characters

The file identifier

header Parameters
X-Request-ID
required
string [ 1 .. 32 ] characters

Unique identifier of the request to the system

X-Request-Deadline
string [ 1 .. 40 ] characters

Maximum request processing time

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "url": "string",
  • "expiresAt": "2019-08-24T14:15:22Z"
}

Transfers within the system

Transfers of funds between wallets within the system

createW2WTransfer

Create a transfer

Authorizations:
bearer
header Parameters
X-Request-ID
required
string [ 1 .. 32 ] characters

Unique identifier of the request to the system

X-Request-Deadline
string [ 1 .. 40 ] characters

Maximum request processing time

Request Body schema: application/json; charset=utf-8

Transfer creation options

sender
required
string (WalletID)

Identifier of the wallet

receiver
required
string (WalletID)

Identifier of the wallet

required
object

Transfer amount

externalID
string

The unique identifier of the entity on your side.

When specified, will be used to ensure idempotent processing of the operation.

Responses

Request samples

Content type
application/json; charset=utf-8
{
  • "sender": "10068321",
  • "receiver": "10068321",
  • "body": {
    },
  • "externalID": "10036274"
}

Response samples

Content type
application/json; charset=utf-8
{
  • "id": "10a0b68D3E21",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "body": {
    },
  • "sender": "10068321",
  • "receiver": "10068321",
  • "status": {
    },
  • "externalID": "10036274"
}

getW2WTransfer

Get the transfer status.

Authorizations:
bearer
path Parameters
w2wTransferID
required
string [ 1 .. 40 ] characters

Identifier of transfer

header Parameters
X-Request-ID
required
string [ 1 .. 32 ] characters

Unique identifier of the request to the system

X-Request-Deadline
string [ 1 .. 40 ] characters

Maximum request processing time

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "id": "10a0b68D3E21",
  • "createdAt": "2019-08-24T14:15:22Z",
  • "body": {
    },
  • "sender": "10068321",
  • "receiver": "10068321",
  • "status": {
    },
  • "externalID": "10036274"
}

Webhooks

Vality Webhooks Management API

This section describes methods that allow you to manage Webhooks, or tools for receiving asynchronous notifications via HTTP requests when one or a group of events of interest to you occurs, for example, that a withdrawal within the created wallet was successfully completed.

Vality Webhooks Events API

Attention! Only the Webhooks Management API is part of the Vality system and hence this specification. To implement the notification handler, you will need to read the OpenAPI specification Vality Wallets Webhook Events API.

createWebhook

Create a new webhook.

Authorizations:
bearer
header Parameters
X-Request-ID
required
string [ 1 .. 32 ] characters

Unique identifier of the request to the system

X-Request-Deadline
string [ 1 .. 40 ] characters

Maximum request processing time

Request Body schema: application/json; charset=utf-8
required

Parameters of the created webhook

identityID
required
string

Identifier of wallet owner

required
object (WebhookScope)

The scope of a webhook, limiting the set of event types, for which the notifications should be sent

url
required
string <uri> <= 1000 characters

The URL that will receive notifications of events that have occurred

Responses

Request samples

Content type
application/json; charset=utf-8
{
  • "identityID": "10036274",
  • "scope": {
    },
  • "url": "http://example.com"
}

Response samples

Content type
application/json; charset=utf-8
{
  • "id": "string",
  • "identityID": "10036274",
  • "active": true,
  • "scope": {
    },
  • "url": "http://example.com",
  • "publicKey": "MIGJAoGBAM1fmNUvezts3yglTdhXuqG7OhHxQtDFA+Ss//YuUGjw5ossDbEMoS+SIFuYZ/UL9Xg0rEHNRSbmf48OK+mz0FobEtbji8MADayzGfFopXsfRFa7MVy3Uhu5jBDpLsN3DyJapAkK0TAYINlZXxVjDwxRNheTvC+xub5WNdiwc28fAgMBAAE="
}

getWebhooks

Get list of existing webhooks.

Authorizations:
bearer
query Parameters
identityID
required
string [ 1 .. 40 ] characters

Identifier of the owner's identity

header Parameters
X-Request-ID
required
string [ 1 .. 32 ] characters

Unique identifier of the request to the system

X-Request-Deadline
string [ 1 .. 40 ] characters

Maximum request processing time

Responses

Response samples

Content type
application/json; charset=utf-8
[
  • {
    }
]

getWebhookByID

Get a webhook by its identifier.

Authorizations:
bearer
path Parameters
webhookID
required
string [ 1 .. 40 ] characters

Webhook identifier

query Parameters
identityID
required
string [ 1 .. 40 ] characters

Identifier of the owner's identity

header Parameters
X-Request-ID
required
string [ 1 .. 32 ] characters

Unique identifier of the request to the system

X-Request-Deadline
string [ 1 .. 40 ] characters

Maximum request processing time

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "id": "string",
  • "identityID": "10036274",
  • "active": true,
  • "scope": {
    },
  • "url": "http://example.com",
  • "publicKey": "MIGJAoGBAM1fmNUvezts3yglTdhXuqG7OhHxQtDFA+Ss//YuUGjw5ossDbEMoS+SIFuYZ/UL9Xg0rEHNRSbmf48OK+mz0FobEtbji8MADayzGfFopXsfRFa7MVy3Uhu5jBDpLsN3DyJapAkK0TAYINlZXxVjDwxRNheTvC+xub5WNdiwc28fAgMBAAE="
}

deleteWebhookByID

Remove the specified webhook.

Authorizations:
bearer
path Parameters
webhookID
required
string [ 1 .. 40 ] characters

Webhook identifier

query Parameters
identityID
required
string [ 1 .. 40 ] characters

Identifier of the owner's identity

header Parameters
X-Request-ID
required
string [ 1 .. 32 ] characters

Unique identifier of the request to the system

X-Request-Deadline
string [ 1 .. 40 ] characters

Maximum request processing time

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "errorType": "NotFound",
  • "name": "X-Request-ID",
  • "description": "Required parameter was not sent"
}

Error codes

Withdrawal errors

Code Description
InvalidSenderResource Invalid transfer source (entered the number of a non-existent card, missing account, etc.)
InvalidReceiverResource Wrong transfer receiver (invalid card number entered, etc.)
InsufficientFunds Insufficient funds on the bank card account
PreauthorizationFailed Pre-Authorization Rejected (Wrong 3D-Secure Code Entered, Cancel Link Clicked on 3D-Secure Form)
RejectedByIssuer The transfer was rejected by the issuer (prohibitions were established by the country of debiting, a ban on purchases on the Internet, the withdrawal was rejected by the issuer's antifraud, etc.)