VantagePay Documentation

Tokens & OTP ​

Send an OTP to an email address for verification. ​

POST /v1/auth/admin/otp/send/email

Auth: API key (VantagePayAdminClient).

Request body

FieldTypeRequiredDescription
fullNamestring?NoThe user's full name, used to personalise the OTP email (optional).
emailAddressstringYesThe email address to which the OTP will be sent (required).
json
{
  "fullName": "string",
  "emailAddress": "string"
}

Responses

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

Response body

FieldTypeRequiredDescription
successbooleanNoGets a value indicating whether the operation was successful.
json
{
  "success": true
}

Code samples ​

WARNING

The JavaScript SDK does not cover admin APIs - use the .NET SDK.

csharp
await adminClient.Authentication.SendEmailAddressOtpAsync("Jane Doe", "customer@example.com");

Send an OTP to a mobile number for verification. ​

POST /v1/auth/admin/otp/send/mobile

Auth: API key (VantagePayAdminClient).

Request body

FieldTypeRequiredDescription
mobileNumberstringYesThe mobile number (MSISDN) to which the OTP will be sent (required).
json
{
  "mobileNumber": "string"
}

Responses

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

Response body

FieldTypeRequiredDescription
successbooleanNoGets a value indicating whether the operation was successful.
json
{
  "success": true
}

Code samples ​

WARNING

The JavaScript SDK does not cover admin APIs - use the .NET SDK.

csharp
await adminClient.Authentication.SendMobileNumberOtpAsync("233555666112");

Validate an OTP sent to an email address and optionally mark linked profiles as verified. ​

POST /v1/auth/admin/otp/validate/email

Auth: API key (VantagePayAdminClient).

Request body

FieldTypeRequiredDescription
emailAddressstringYesThe email address that the OTP was sent to (required).
referencestring?YesThe system reference of the pending verification session, if applicable.
otpValuestringYesThe OTP value entered by the user (required).
json
{
  "emailAddress": "string",
  "reference": "00000000-0000-0000-0000-000000000000",
  "otpValue": "string"
}

Responses

StatusDescription
200The OTP was valid and email verification was completed successfully.
400The request failed validation, the error object will contain further information.
401The OTP was invalid or expired.
403The authorization header does not contain the correct type or you do not have access to this resource.
422The request payload is invalid, the error object will contain further information.
429Too many requests are being sent concurrently or rate limiting has taken effect.
500An unexpected error occurred, the error object will contain further information.

Response body

FieldTypeRequiredDescription
successbooleanNoGets a value indicating whether the operation was successful.
json
{
  "success": true
}

Code samples ​

WARNING

The JavaScript SDK does not cover admin APIs - use the .NET SDK.

csharp
await adminClient.Authentication.ValidateEmailAddressOtpAsync("123456", "customer@example.com", Guid.Parse("7c9e6679-7425-40de-944b-e07fc1f90ae7"));

Validate an OTP sent to a mobile number and optionally mark linked profiles as verified. ​

POST /v1/auth/admin/otp/validate/mobile

Auth: API key (VantagePayAdminClient).

Request body

FieldTypeRequiredDescription
mobileNumberstringYesThe mobile number (MSISDN) that the OTP was sent to (required).
referencestring?YesThe system reference of the pending verification session, if applicable.
otpValuestringYesThe OTP value entered by the user (required).
json
{
  "mobileNumber": "string",
  "reference": "00000000-0000-0000-0000-000000000000",
  "otpValue": "string"
}

Responses

StatusDescription
200The OTP was valid and mobile number verification was completed successfully.
400The request failed validation, the error object will contain further information.
401The OTP was invalid or expired.
403The authorization header does not contain the correct type or you do not have access to this resource.
422The request payload is invalid, the error object will contain further information.
429Too many requests are being sent concurrently or rate limiting has taken effect.
500An unexpected error occurred, the error object will contain further information.

Response body

FieldTypeRequiredDescription
successbooleanNoGets a value indicating whether the operation was successful.
json
{
  "success": true
}

Code samples ​

WARNING

The JavaScript SDK does not cover admin APIs - use the .NET SDK.

csharp
await adminClient.Authentication.ValidateMobileNumberOtpAsync("123456", "233555666112", Guid.Parse("7c9e6679-7425-40de-944b-e07fc1f90ae7"));

Generate an access and refresh token pair for a consumer. ​

POST /v1/auth/admin/token/generate/consumer/{consumerReference}

This is useful for partners who register consumers through us but use their own login server and handle authentication themselves.

Sample

json
POST /v1/auth/token/generate/consumer/50a881c7-ce35-4c3b-be1d-28d643fef6d7

Auth: API key (VantagePayAdminClient).

Parameters

NameInRequiredDescription
consumerReferencepathYesA globally unique internal consumer reference (UUID).

Responses

StatusDescription
200Token generation for the specified consumer succeeded and a new access and refresh token pair was returned.
400The request failed validation, the error object will contain further information.
401Token generation failed and flags will be set in the response to indicate what went wrong.
403The authorization header does not contain the correct type or you do not have access to this resource.
422The request payload is invalid, the error object will contain further information.
429Too many requests are being sent concurrently or rate limiting has taken effect.
500An unexpected error occurred, the error object will contain further information.

Response body

FieldTypeRequiredDescription
successbooleanNoGets a value indicating whether the operation was successful.
resultobjectNoProvides token information for successful login and refresh operations.
json
{
  "success": true,
  "result": {
    "refreshToken": "string",
    "accessToken": "string",
    "accessTokenValidForSeconds": 0
  }
}

Code samples ​

WARNING

The JavaScript SDK does not cover admin APIs - use the .NET SDK.

csharp
var tokens = await adminClient.Authentication.GenerateConsumerTokenAsync(Guid.Parse("7c9e6679-7425-40de-944b-e07fc1f90ae7"));

Generate an access and refresh token pair for a merchant. ​

POST /v1/auth/admin/token/generate/merchant/{merchantReference}

Sample

json
POST /v1/auth/token/generate/merchant/0bf31b49-9420-4726-8f51-96ce60a770fb

Auth: API key (VantagePayAdminClient).

Parameters

NameInRequiredDescription
merchantReferencepathYesA globally unique internal merchant reference (UUID).

Responses

StatusDescription
200Token generation for the specified merchant succeeded and a new access and refresh token pair was returned.
400The request failed validation, the error object will contain further information.
401Token generation failed and flags will be set in the response to indicate what went wrong.
403The authorization header does not contain the correct type or you do not have access to this resource.
422The request payload is invalid, the error object will contain further information.
429Too many requests are being sent concurrently or rate limiting has taken effect.
500An unexpected error occurred, the error object will contain further information.

Response body

FieldTypeRequiredDescription
successbooleanNoGets a value indicating whether the operation was successful.
resultobjectNoProvides token information for successful login and refresh operations.
json
{
  "success": true,
  "result": {
    "refreshToken": "string",
    "accessToken": "string",
    "accessTokenValidForSeconds": 0
  }
}

Code samples ​

WARNING

The JavaScript SDK does not cover admin APIs - use the .NET SDK.

csharp
var merchantToken = await adminClient.Authentication.GenerateMerchantTokenAsync(Guid.Parse("3fa85f64-5717-4562-b3fc-2c963f66afa6"));

Generate tokens manually with a custom set of claims. ​

POST /v1/auth/admin/token/generate

Sample

json
POST /v1/auth/token/generate
{
  "expiryInSeconds": 16070400,
  "claims":
  {
    "userReference": "string",              
    "name": "string",
    "dateOfBirth": "string",
    "mobileNumber": "string",
    "emailAddress": "string",
    "canUseDoNotProcess": "true/false",
    "canDisableThreeDSecure": "true/false",
    "canDisableConfirmation": "true/false"
  }
}

Auth: API key (VantagePayAdminClient).

Request body

FieldTypeRequired
expiryInSecondsinteger?No
claimsobject?No
accessPoliciesarray<string>?No
json
{
  "expiryInSeconds": 0,
  "claims": {
    "UserReference": "string",
    "ConsumerReference": "string",
    "MerchantReference": "string",
    "BusinessReference": "string",
    "TerminalReference": "string",
    "Name": "string",
    "LoginName": "string",
    "DateOfBirth": "string",
    "MobileNumber": "string",
    "EmailAddress": "string",
    "AccessPolicy": "string",
    "CanUseCashSource": "string",
    "CanUseDoNotProcess": "string",
    "CanDisableThreeDSecure": "string",
    "CanDisableConfirmation": "string",
    "MaxTotalSourceAmountInCents": "string",
    "MaxTotalDestinationAmountInCents": "string",
    "OverrideSourcePluginName": "string",
    "OverrideSourcePluginSettingsName": "string",
    "OverrideDestinationPluginName": "string",
    "OverrideDestinationPluginSettingsName": "string",
    "AllowedCurrencies": "string",
    "RedirectAction": "string",
    "PaymentRequestWasRouted": "string"
  },
  "accessPolicies": [
    "string"
  ]
}

Responses

StatusDescription
200Token generation was successful and a new access and refresh token pair was returned.
400The request failed validation, the error object will contain further information.
401Token generation failed and flags will be set in the response to indicate what went wrong.
403The authorization header does not contain the correct type or you do not have access to this resource.
422The request payload is invalid, the error object will contain further information.
429Too many requests are being sent concurrently or rate limiting has taken effect.
500An unexpected error occurred, the error object will contain further information.

Response body

FieldTypeRequiredDescription
successbooleanNoGets a value indicating whether the operation was successful.
resultobjectNoProvides token information for successful login and refresh operations.
json
{
  "success": true,
  "result": {
    "refreshToken": "string",
    "accessToken": "string",
    "accessTokenValidForSeconds": 0
  }
}

Code samples ​

WARNING

The JavaScript SDK does not cover admin APIs - use the .NET SDK.

csharp
// Generates a token for the current API-key context. Use the consumer/merchant token overloads for a specific entity.
// Not wrapped by the .NET SDK - call the endpoint directly with an authorized HttpClient.
using var http = new HttpClient { BaseAddress = new Uri("https://sandbox-api.vantagepay.dev") };
http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", client.ApiTokens.AccessToken);
var response = await http.PostAsync("/v1/auth/admin/token/generate", content: null);
response.EnsureSuccessStatusCode();

Payments for Africa

© VantagePay 2026