Authentication

POST /v1/auth/login

Access tokens are used for all API calls and refresh tokens are used to get new access tokens without logging in again.

Sample

json

POST /v1/auth/login
{
    "username": "{{$randomUserName}}",
    "password": "{{$randomPassword}}"
}

Auth: None (public).

Request body

Field	Type	Required	Description
`username`	string	Yes	The username (required).
`password`	string	Yes	The password (required).

json

{
  "username": "string",
  "password": "string"
}

Responses

Status	Description
`200`	The login succeeded and an access and refresh token pair was returned.
`400`	The request failed validation, the error object will contain further information.
`401`	The login failed because of incorrect credentials or because the account requires additional verification.
`422`	The request payload is invalid, the error object will contain further information.
`429`	Too many requests are being sent concurrently or rate limiting has taken effect.
`500`	An unexpected error occurred, the error object will contain further information.

Response body

Field	Type	Required	Description
`success`	boolean	No	Gets a value indicating whether the operation was successful.
`result`	object	No	Provides token information for successful login and refresh operations.

json

{
  "success": true,
  "result": {
    "refreshToken": "string",
    "accessToken": "string",
    "accessTokenValidForSeconds": 0
  }
}

Code samples

JavaScript.NET

// @vantagepay/vantagepay
import { ApiError } from '@vantagepay/vantagepay'

try {
  const tokens = await client.auth.login('233555666112', 'Password123!')
  console.log(tokens.accessToken, tokens.refreshToken)
} catch (error) {
  if (error instanceof ApiError) {
    if (error.statusCode === 401 && error.result?.mustChangePassword) {
      await client.auth.changePassword('Password123!', 'NewPassword456!')
    } else if (error.statusCode === 401 && (error.result?.mustValidatePhoneNumber || error.result?.mustValidateEmailAddress)) {
      await client.auth.resendOtp()
      await client.auth.validateOtp('123456')
    } else {
      console.error(error.statusCode, error.message)
    }
  } else {
    throw error
  }
}

csharp

// VantagePay.SDK
using VantagePay.SDK.Exceptions;

try
{
    var tokens = await client.Authentication.LoginAsync("233555666112", "Password123!");
    Console.WriteLine($"{tokens?.AccessToken} / {tokens?.RefreshToken}");
}
catch (ApiAuthorizationException ex)
{
    if (ex.ErrorResponse?.MustChangePassword == true)
    {
        await client.Authentication.ChangePasswordAsync("Password123!", "NewPassword456!");
    }
    else if (ex.ErrorResponse?.MustValidatePhoneNumber == true || ex.ErrorResponse?.MustValidateEmailAddress == true)
    {
        await client.Authentication.ResendOtpAsync();
        await client.Authentication.ValidateOtpAsync("123456");
    }
}

Perform a logout operation to clear your currently active refresh token so that it can no longer be used to generate access tokens.

POST /v1/auth/logout

Sample - Refresh Token required in authorization bearer header

json

POST /v1/auth/logout

Auth: Refresh token (Bearer).

Responses

Status	Description
`200`	The logout succeeded and the most recently active refresh token is no longer valid.
`400`	The request failed validation, the error object will contain further information.
`401`	The authorization information provided is not valid, authentication is required to access this resource.
`403`	The authorization header does not contain the correct type or you do not have access to this resource.
`422`	The request payload is invalid, the error object will contain further information.
`429`	Too many requests are being sent concurrently or rate limiting has taken effect.
`500`	An unexpected error occurred, the error object will contain further information.

Response body

Field	Type	Required	Description
`success`	boolean	No	Gets a value indicating whether the operation was successful.

json

{
  "success": true
}

Code samples

JavaScript.NET

// @vantagepay/vantagepay
await client.auth.logout()

csharp

// VantagePay.SDK
await client.Authentication.LogoutAsync();

Perform a token refresh operation to retrieve a new access and refresh token pair.

POST /v1/auth/refresh

Sample - Refresh Token required in authorization bearer header

json

POST /v1/auth/refresh

Auth: Refresh token (Bearer).

Responses

Status	Description
`200`	The refresh succeeded and a new access and refresh token pair was returned.
`400`	The request failed validation, the error object will contain further information.
`401`	The refresh failed and new tokens need be retrieved using the /login end-point.
`403`	The authorization header does not contain the correct type or you do not have access to this resource.
`422`	The request payload is invalid, the error object will contain further information.
`429`	Too many requests are being sent concurrently or rate limiting has taken effect.
`500`	An unexpected error occurred, the error object will contain further information.

Response body

Field	Type	Required	Description
`success`	boolean	No	Gets a value indicating whether the operation was successful.
`result`	object	No	Provides token information for successful login and refresh operations.

json

{
  "success": true,
  "result": {
    "refreshToken": "string",
    "accessToken": "string",
    "accessTokenValidForSeconds": 0
  }
}

Code samples

JavaScript.NET

// @vantagepay/vantagepay
// The SDK refreshes automatically; call refresh() to force a new token pair.
const tokens = await client.auth.refresh()

csharp

// VantagePay.SDK
// The SDK refreshes automatically; call RefreshAsync() to force a new token pair.
var tokens = await client.Authentication.RefreshAsync();

Checks the liveness of a user's face by analyzing a series of images.

POST /v1/auth/liveness

Auth: Access token (Bearer).

Request body

Field	Type	Required	Description
`base64Images`	array<string>?	No	Gets the ordered collection of Base64-encoded face-capture images used for liveness detection.

json

{
  "base64Images": [
    "string"
  ]
}

Responses

Status	Description
`200`	The request was successful but does not return any results.
`400`	The request failed validation, the error object will contain further information.
`401`	The authorization information provided is not valid, authentication is required to access this resource.
`403`	The authorization header does not contain the correct type or you do not have access to this resource.
`422`	The request payload is invalid, the error object will contain further information.
`429`	Too many requests are being sent concurrently or rate limiting has taken effect.
`500`	An unexpected error occurred, the error object will contain further information.

Response body

Field	Type	Required	Description
`success`	boolean	No	Gets a value indicating whether the operation was successful.
`result`	None, OneRangeOfMotion, MultipleRangesOfMotion, AllRangesOfMotion	No	Controls the strictness of facial liveness movement detection during a KYC liveness check.

json

{
  "success": true,
  "result": "None"
}

Code samples

JavaScript.NET

// @vantagepay/vantagepay
const level = await client.auth.checkLiveness([image1Base64, image2Base64])
// FaceMovementDetectionLevel indicates the confidence of the liveness check.

csharp

// VantagePay.SDK
var level = await client.Authentication.CheckLivenessAsync(new[] { image1Base64, image2Base64 });

Checks the quality of a facial image.

POST /v1/auth/face-check

Auth: Access token (Bearer).

Request body

Field	Type	Required	Description
`base64Image`	string?	No	Gets the Base64-encoded selfie image to use for facial comparison.

json

{
  "base64Image": "string"
}

Responses

Status	Description
`200`	The request was successful but does not return any results.
`400`	The request failed validation, the error object will contain further information.
`401`	The authorization information provided is not valid, authentication is required to access this resource.
`403`	The authorization header does not contain the correct type or you do not have access to this resource.
`422`	The request payload is invalid, the error object will contain further information.
`429`	Too many requests are being sent concurrently or rate limiting has taken effect.
`500`	An unexpected error occurred, the error object will contain further information.

Response body

Field	Type	Required	Description
`success`	boolean	No	Gets a value indicating whether the operation was successful.
`result`	object	No	The result of a facial image quality check performed prior to a KYC biometric submission.

json

{
  "success": true,
  "result": {
    "faceCount": 0,
    "containsNoise": true,
    "isLowQuality": true,
    "isOverExposed": true,
    "isUnderExposed": true,
    "isBlurry": true,
    "isWearingMask": true,
    "foreheadNotIncluded": true,
    "eyesNotIncluded": true,
    "mouthNotIncluded": true,
    "problems": []
  }
}

Code samples

JavaScript.NET

// @vantagepay/vantagepay
const result = await client.auth.checkFace(selfieBase64)
console.log(result.isValid, result.qualityScore)

csharp

// VantagePay.SDK
var result = await client.Authentication.CheckFaceAsync(selfieBase64);

Change a user's password.

POST /v1/auth/password/change

Auth: Access token (Bearer).

Request body

Field	Type	Required	Description
`oldPassword`	string?	No	The user's current/old password. Required when the user is already authenticated.
`newPassword`	string	Yes	The new password to set (required).
`resetCode`	string?	No	A password-reset code sent to the user by email or SMS. Required when calling the anonymous (unauthenticated) endpoint.
`userReference`	string?	No	The unique reference of the user account to update. Not required when the user is already authenticated.

json

{
  "oldPassword": "string",
  "newPassword": "string",
  "resetCode": "00000000-0000-0000-0000-000000000000",
  "userReference": "00000000-0000-0000-0000-000000000000"
}

Responses

Status	Description
`200`	The request was successful and the password was changed.
`400`	The request failed validation, the error object will contain further information.
`401`	The request was successful but does not return any results.
`422`	The request payload is invalid, the error object will contain further information.
`429`	Too many requests are being sent concurrently or rate limiting has taken effect.
`500`	An unexpected error occurred, the error object will contain further information.

Response body

Field	Type	Required	Description
`success`	boolean	No	Gets a value indicating whether the operation was successful.
`result`	object	No	Provides token information for successful login and refresh operations.

json

{
  "success": true,
  "result": {
    "refreshToken": "string",
    "accessToken": "string",
    "accessTokenValidForSeconds": 0
  }
}

Code samples

JavaScript.NET

// @vantagepay/vantagepay
const tokens = await client.auth.changePassword('OldPassword123!', 'NewPassword456!')

csharp

// VantagePay.SDK
var tokens = await client.Authentication.ChangePasswordAsync("OldPassword123!", "NewPassword456!");

Validate OTP request.

POST /v1/auth/otp/validate

Auth: Access token (Bearer).

Request body

Field	Type	Required	Description
`otpValue`	string	Yes	The OTP value entered by the user (required).

json

{
  "otpValue": "string"
}

Responses

Status	Description
`200`	The request was successful and the correct OTP value was supplied.
`400`	The request failed validation, the error object will contain further information.
`401`	The authorization information provided is not valid, authentication is required to access this resource.
`403`	The authorization header does not contain the correct type or you do not have access to this resource.
`422`	The request payload is invalid, the error object will contain further information.
`429`	Too many requests are being sent concurrently or rate limiting has taken effect.
`500`	An unexpected error occurred, the error object will contain further information.

Response body

Field	Type	Required	Description
`success`	boolean	No	Gets a value indicating whether the operation was successful.
`result`	object	No	Provides token information for successful login and refresh operations.

json

{
  "success": true,
  "result": {
    "refreshToken": "string",
    "accessToken": "string",
    "accessTokenValidForSeconds": 0
  }
}

Code samples

JavaScript.NET

// @vantagepay/vantagepay
const tokens = await client.auth.validateOtp('123456')
if (tokens) {
  console.log('OTP accepted, session established')
}

csharp

// VantagePay.SDK
var tokens = await client.Authentication.ValidateOtpAsync("123456");

Request a new OTP to be sent.

POST /v1/auth/otp/resend

Auth: Access token (Bearer).

Responses

Status	Description
`200`	The request was successful and a new OTP was sent to the merchant mobile number.
`400`	The request failed validation, the error object will contain further information.
`401`	The authorization information provided is not valid, authentication is required to access this resource.
`403`	The authorization header does not contain the correct type or you do not have access to this resource.
`422`	The request payload is invalid, the error object will contain further information.
`429`	Too many requests are being sent concurrently or rate limiting has taken effect.
`500`	An unexpected error occurred, the error object will contain further information.

Response body

Field	Type	Required	Description
`success`	boolean	No	Gets a value indicating whether the operation was successful.

json

{
  "success": true
}

Code samples

JavaScript.NET

// @vantagepay/vantagepay
await client.auth.resendOtp()

csharp

// VantagePay.SDK
await client.Authentication.ResendOtpAsync();

Send a temporary password to the email addresses associated with the specified username.

POST /v1/auth/password/forgot

To prevent timing-based enumeration, the response is always delayed to a minimum of 3 seconds regardless of whether the account exists.

Auth: Access token (Bearer).

Request body

Field	Type	Required	Description
`username`	string	Yes	The username (email address or mobile number) of the account to reset (required).

json

{
  "username": "string"
}

Responses

Status	Description
`200`	The request was processed. A temporary password will have been sent if the account was found and had verified email addresses.
`400`	The request failed validation, the error object will contain further information.
`422`	The request payload is invalid, the error object will contain further information.
`429`	Too many requests are being sent concurrently or rate limiting has taken effect.
`500`	An unexpected error occurred, the error object will contain further information.

Response body

Field	Type	Required	Description
`success`	boolean	No	Gets a value indicating whether the operation was successful.

json

{
  "success": true
}

Code samples

JavaScript.NET

// @vantagepay/vantagepay
await client.auth.forgotPassword('233555666112')

csharp

// VantagePay.SDK
await client.Authentication.ForgotPasswordAsync("233555666112");

Re-sends email verification for a user.

POST /v1/auth/email/verify/resend

Auth: Access token (Bearer).

Responses

Status	Description
`200`	Email verification resend operation succeeded.
`400`	Email verification resend operation failed due to invalid request input.
`401`	The authorization information provided is not valid, authentication is required to access this resource.
`403`	The authorization header does not contain the correct type or you do not have access to this resource.
`422`	The request payload is invalid, the error object will contain further information.
`429`	Too many requests are being sent concurrently or rate limiting has taken effect.
`500`	An unexpected error occurred, the error object will contain further information.

Response body

Field	Type	Required	Description
`success`	boolean	No	Gets a value indicating whether the operation was successful.

json

{
  "success": true
}

Code samples

JavaScript.NET

// @vantagepay/vantagepay
await client.auth.resendEmailAddressVerification()

csharp

// VantagePay.SDK
await client.Authentication.ResendEmailAddressVerificationAsync();

Verifies an email address using a verification code.

GET /v1/auth/email/verify/{reference}/{verificationCode}

Auth: Access token (Bearer).

Parameters

Name	In	Required	Description
`reference`	path	Yes	The reference of the entity that requested the verification.
`verificationCode`	path	Yes	The verification code sent to the user's email address.

Responses

Status	Description
`200`	Email verification operation succeeded. Returns an Microsoft.AspNetCore.Mvc.ActionResult.
`400`	Email verification operation failed due to invalid request input. Returns a BadRequest result.
`422`	The request payload is invalid, the error object will contain further information.
`429`	Too many requests are being sent concurrently or rate limiting has taken effect.
`500`	An unexpected error occurred, the error object will contain further information.

Response body

Field	Type	Required	Description
`success`	boolean	No	Gets a value indicating whether the operation was successful.

json

{
  "success": true
}

Code samples

JavaScript.NET

// @vantagepay/vantagepay
// Confirms an email address from the link sent to the user. This is not intended to be called directly.

csharp

// VantagePay.SDK
// Confirms an email address from the link sent to the user. This is not intended to be called directly.

Create a user.

POST /v1/user/create

Sample

json

POST v1/user/create
{
  "username": "{{$randomUserName}}",
  "password": "{{$randomPassword}}"
}

Auth: Access token (Bearer).

Request body

Field	Type	Required	Description
`username`	string	Yes	The username (required).
`password`	string	Yes	The password (required).
`isLockedOut`	boolean	No	`true` if the user account is currently locked out.
`reasonForLockout`	string?	No	The reason the user account was locked out, if applicable.

json

{
  "username": "string",
  "password": "string",
  "isLockedOut": true,
  "reasonForLockout": "string"
}

Responses

Status	Description
`200`	The user was created successfully and a new user reference was returned.
`400`	The request failed validation, the error object will contain further information.
`401`	The authorization information provided is not valid, authentication is required to access this resource.
`403`	The authorization header does not contain the correct type or you do not have access to this resource.
`422`	The request payload is invalid, the error object will contain further information.
`429`	Too many requests are being sent concurrently or rate limiting has taken effect.
`500`	An unexpected error occurred, the error object will contain further information.

Response body

Field	Type	Required	Description
`success`	boolean	No	Gets a value indicating whether the operation was successful.
`result`	string	No	Gets the response payload.

json

{
  "success": true,
  "result": "00000000-0000-0000-0000-000000000000"
}

Code samples

JavaScript.NET

// @vantagepay/vantagepay
// Server-side only - requires an admin API key (use the .NET VantagePayAdminClient).

csharp

// VantagePay.SDK
// Server-side only - requires an admin API key.
var userReference = await adminClient.Users.CreateUserAsync("partner.user", "StrongPassword123!");

Deactivate a user.

DELETE /v1/user/deactivate/{userReference}

Auth: Access token (Bearer).

Parameters

Name	In	Required	Description
`userReference`	path	Yes	The globally unique user reference (UUID) to deactivate.

Responses

Status	Description
`200`	The user was deactivate successfully.
`400`	The request failed validation, the error object will contain further information.
`401`	The authorization information provided is not valid, authentication is required to access this resource.
`403`	The authorization header does not contain the correct type or you do not have access to this resource.
`422`	The request payload is invalid, the error object will contain further information.
`429`	Too many requests are being sent concurrently or rate limiting has taken effect.
`500`	An unexpected error occurred, the error object will contain further information.

Response body

Field	Type	Required	Description
`success`	boolean	No	Gets a value indicating whether the operation was successful.

json

{
  "success": true
}

Code samples

JavaScript.NET

// @vantagepay/vantagepay
// Server-side only - requires an admin API key (use the .NET VantagePayAdminClient).

csharp

// VantagePay.SDK
await adminClient.Users.DeactivateUserAsync(Guid.Parse("3c3d3e3f-4a4b-4c4d-5e5f-6a6b7c7d8e8f"));

Create a user and link to all merchants based on the mobile number.

POST /v1/merchant/user

Auth: Access token (Bearer).

Request body

Field	Type	Required	Description
`emailAddress`	string?	No	The email address registered to this merchant account.
`mobileNumber`	string?	No	The mobile number registered to this merchant account, in international format.
`username`	string	Yes	The username (required).
`password`	string	Yes	The password (required).
`isLockedOut`	boolean	No	`true` if the user account is currently locked out.
`reasonForLockout`	string?	No	The reason the user account was locked out, if applicable.

json

{
  "emailAddress": "string",
  "mobileNumber": "string",
  "username": "string",
  "password": "string",
  "isLockedOut": true,
  "reasonForLockout": "string"
}

Responses

Status	Description
`200`	The user was created successfully, linked to existing merchants and logged in.
`400`	The request failed validation, the error object will contain further information.
`401`	The authorization information provided is not valid, authentication is required to access this resource.
`403`	The authorization header does not contain the correct type or you do not have access to this resource.
`422`	The request payload is invalid, the error object will contain further information.
`429`	Too many requests are being sent concurrently or rate limiting has taken effect.
`500`	An unexpected error occurred, the error object will contain further information.

Response body

Field	Type	Required	Description
`success`	boolean	No	Gets a value indicating whether the operation was successful.
`result`	object	No	Provides token information for successful login and refresh operations.

json

{
  "success": true,
  "result": {
    "refreshToken": "string",
    "accessToken": "string",
    "accessTokenValidForSeconds": 0
  }
}

Code samples

JavaScript.NET

// @vantagepay/vantagepay
// Requires a name-validated session (see POST /v1/merchant/validate/name).
const tokens = await client.merchants.createUser('cashier01', 'StrongPassword123!', '233555666112', 'customer@example.com')

csharp

// VantagePay.SDK
var tokens = await client.Merchants.CreateUserAsync("cashier01", "StrongPassword123!", "233555666112", "customer@example.com");

Get a list of merchant information linked to your account.

GET /v1/merchant/user

Auth: Access token (Bearer).

Responses

Status	Description
`200`	The request was successful but does not return any results.
`400`	The request failed validation, the error object will contain further information.
`401`	The authorization information provided is not valid, authentication is required to access this resource.
`403`	The authorization header does not contain the correct type or you do not have access to this resource.
`422`	The request payload is invalid, the error object will contain further information.
`429`	Too many requests are being sent concurrently or rate limiting has taken effect.
`500`	An unexpected error occurred, the error object will contain further information.

Response body

Field	Type	Required	Description
`success`	boolean	No	Gets a value indicating whether the operation was successful.
`result`	array<object>?	No	Gets the response payload.

json

{
  "success": true,
  "result": [
    {}
  ]
}

Code samples

JavaScript.NET

// @vantagepay/vantagepay
const merchants = await client.merchants.getUserMerchants()

csharp

// VantagePay.SDK
var merchants = await client.Merchants.GetUserMerchantsAsync();

Switch to another merchant account that is linked to your user.

POST /v1/merchant/user/switch/{merchantReference}

Auth: Access token (Bearer).

Parameters

Name	In	Required	Description
`merchantReference`	path	Yes	A globally unique internal merchant reference (UUID).

Responses

Status	Description
`200`	The request was successful but does not return any results.
`400`	The request failed validation, the error object will contain further information.
`401`	The authorization information provided is not valid, authentication is required to access this resource.
`403`	The authorization header does not contain the correct type or you do not have access to this resource.
`422`	The request payload is invalid, the error object will contain further information.
`429`	Too many requests are being sent concurrently or rate limiting has taken effect.
`500`	An unexpected error occurred, the error object will contain further information.

Response body

Field	Type	Required	Description
`success`	boolean	No	Gets a value indicating whether the operation was successful.
`result`	object	No	Provides token information for successful login and refresh operations.

json

{
  "success": true,
  "result": {
    "refreshToken": "string",
    "accessToken": "string",
    "accessTokenValidForSeconds": 0
  }
}

Code samples

JavaScript.NET

// @vantagepay/vantagepay
const tokens = await client.merchants.switchToMerchant('3fa85f64-5717-4562-b3fc-2c963f66afa6')

csharp

// VantagePay.SDK
var tokens = await client.Merchants.SwitchToMerchantAsync(Guid.Parse("3fa85f64-5717-4562-b3fc-2c963f66afa6"));

Consumers

Merchants

Payments

Authentication Admin

Consumers Admin

Merchants Admin

Notifications Admin

Authentication

Code samples

Perform a logout operation to clear your currently active refresh token so that it can no longer be used to generate access tokens.

Code samples

Perform a token refresh operation to retrieve a new access and refresh token pair.

Code samples

Checks the liveness of a user's face by analyzing a series of images.

Code samples

Checks the quality of a facial image.

Code samples

Change a user's password.

Code samples

Validate OTP request.

Code samples

Request a new OTP to be sent.

Code samples

Send a temporary password to the email addresses associated with the specified username.

Code samples

Re-sends email verification for a user.

Code samples

Verifies an email address using a verification code.

Code samples

Create a user.

Code samples

Deactivate a user.

Code samples

Create a user and link to all merchants based on the mobile number.

Code samples

Get a list of merchant information linked to your account.

Code samples

Switch to another merchant account that is linked to your user.

Code samples

Authentication ​

Perform a login operation to retrieve an access and refresh token pair. ​

Code samples ​

Perform a logout operation to clear your currently active refresh token so that it can no longer be used to generate access tokens. ​

Code samples ​

Perform a token refresh operation to retrieve a new access and refresh token pair. ​

Code samples ​

Checks the liveness of a user's face by analyzing a series of images. ​

Code samples ​

Checks the quality of a facial image. ​

Code samples ​

Change a user's password. ​

Code samples ​

Validate OTP request. ​

Code samples ​

Request a new OTP to be sent. ​

Code samples ​

Send a temporary password to the email addresses associated with the specified username. ​

Code samples ​

Re-sends email verification for a user. ​

Code samples ​

Verifies an email address using a verification code. ​

Code samples ​

Create a user. ​

Code samples ​

Deactivate a user. ​

Code samples ​

Create a user and link to all merchants based on the mobile number. ​

Code samples ​

Get a list of merchant information linked to your account. ​

Code samples ​

Switch to another merchant account that is linked to your user. ​

Code samples ​

Authentication

Perform a login operation to retrieve an access and refresh token pair.

Code samples

Perform a logout operation to clear your currently active refresh token so that it can no longer be used to generate access tokens.

Code samples

Perform a token refresh operation to retrieve a new access and refresh token pair.

Code samples

Checks the liveness of a user's face by analyzing a series of images.

Code samples

Checks the quality of a facial image.

Code samples

Change a user's password.

Code samples

Validate OTP request.

Code samples

Request a new OTP to be sent.

Code samples

Send a temporary password to the email addresses associated with the specified username.

Code samples

Re-sends email verification for a user.

Code samples

Verifies an email address using a verification code.

Code samples

Create a user.

Code samples

Deactivate a user.

Code samples

Create a user and link to all merchants based on the mobile number.

Code samples

Get a list of merchant information linked to your account.

Code samples

Switch to another merchant account that is linked to your user.

Code samples