Tokens

Tokenize a credit card.

POST /v2/token/card

Sample

POST /v2/token/card
{
  "nameOnCard": "Sandbox Test Card",
  "cardNumber": "5200000000000007",
  "expiryMonth": 9,
  "expiryYear": 2022
}

Auth: Access token (Bearer).

Request body

Field	Type	Required	Description
cardNumber	string	Yes	The full primary account number (PAN) of the card to be tokenized.
nameOnCard	string	Yes	The cardholder name as it appears on the card.
expiryMonth	1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12	Yes	The month in which the card expires.
expiryYear	integer	Yes	The four-digit expiry year (e.g. 2027).

{
  "cardNumber": "string",
  "nameOnCard": "string",
  "expiryMonth": 1,
  "expiryYear": 0
}

Responses

Status	Description
200	The request was successful and the card was tokenized.
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	A model to hold the details of a card response that is returned to a caller when they tokenize a card or verify a tokenized card.

{
  "success": true,
  "result": {
    "token": "string",
    "requiresPayment": true,
    "requiresVerification": true,
    "verificationAttemptsRemaining": 0,
    "paymentCurrency": "None",
    "paymentAmountInCents": 0
  }
}

Code samples

JavaScript

// @vantagepay/vantagepay
const cardToken = await client.payments.createCardToken({
  cardNumber: '5200000000000114',
  nameOnCard: 'Jane Doe',
  expiryMonth: 9,
  expiryYear: 2028,
})

.NET

// VantagePay.SDK
using VantagePay.Models.Lookups;
using VantagePay.Models.Tokens;

var cardToken = await client.Payments.CreateCardTokenAsync(new CardRequest
{
    CardNumber = "5200000000000114",
    NameOnCard = "Jane Doe",
    ExpiryMonth = Month.September,
    ExpiryYear = 2028,
});

---

Tokenize a bank account.

POST /v2/token/bank-account

Sample

POST /v2/token/bank-account
{
  "accountNumber": "1111000333777888",
  "bank": "ADB"
}

Auth: Access token (Bearer).

Request body

Field	Type	Required	Description
accountNumber	string	Yes	The bank account number to tokenize.
bank	one of 106 values (e.g. None, ABD, ACB, ...)	Yes	The bank at which the account is held.

{
  "accountNumber": "string",
  "bank": "None"
}

Responses

Status	Description
200	The request was successful and the bank account was tokenized.
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 bank account tokenization request, containing the token that represents the account for future use.

{
  "success": true,
  "result": {
    "token": "string"
  }
}

Code samples

JavaScript

// @vantagepay/vantagepay
// Tokenizes a bank account. Not wrapped by the JavaScript SDK.
// Not wrapped by the JavaScript SDK - call the endpoint directly with the active token.
const response = await fetch(baseUrl + '/v2/token/bank-account', {
  method: 'POST',
  headers: { Authorization: 'Bearer ' + ApiTokens.accessToken },
})
const result = await response.json()

.NET

// VantagePay.SDK
using VantagePay.Models.Lookups;
using VantagePay.Models.Tokens;

var bankToken = await client.Payments.CreateBankAccountTokenAsync(new BankAccountRequest
{
    AccountNumber = "1234567890",
    Bank = Bank.GCB,
});

---

Activate a card token.

POST /v2/token/card/activate/{cardToken}

Sample

POST /v2/token/card/activate/FF5B3EF7CCDE40A4911CAE63ABF2416537FB49DEF0B14E2B8BFAB59B7F43A15E

Auth: Access token (Bearer).

Parameters

Name	In	Required	Description
cardToken	path	Yes	The card token to be activated.

Responses

Status	Description
200	The request was successful and the card token was activated.
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.

{
  "success": true
}

Code samples

JavaScript

// @vantagepay/vantagepay
// Activates a card token. Not wrapped by the JavaScript SDK.
// Not wrapped by the JavaScript SDK - call the endpoint directly with the active token.
const response = await fetch(baseUrl + '/v2/token/card/activate/' + cardToken, {
  method: 'POST',
  headers: { Authorization: 'Bearer ' + ApiTokens.accessToken },
})
const result = await response.json()

.NET

// VantagePay.SDK
await client.Payments.ActivateCardTokenAsync(cardToken);

---

Verify a card with a verification code obtained from the credit card statement.

POST /v2/token/card/verify

Sample

POST /v2/token/card/verify
{
  "token": "FF5B3EF7CCDE40A4911CAE63ABF2416537FB49DEF0B14E2B8BFAB59B7F43A15E",
  "verificationCode": "VC-1534"
}

Auth: Access token (Bearer).

Request body

Field	Type	Required	Description
token	string?	No	A card token.
verificationCode	string	Yes	The verification code that appeared on the credit card statement after the verification test payment was made.

{
  "token": "string",
  "verificationCode": "string"
}

Responses

Status	Description
200	A verification attempt was successfully made.
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	A model to hold the details of a card response that is returned to a caller when they tokenize a card or verify a tokenized card.

{
  "success": true,
  "result": {
    "token": "string",
    "requiresPayment": true,
    "requiresVerification": true,
    "verificationAttemptsRemaining": 0,
    "paymentCurrency": "None",
    "paymentAmountInCents": 0
  }
}

Code samples

JavaScript

// @vantagepay/vantagepay
const card = await client.payments.verifyCardToken({ token: cardToken, verificationCode: '123' })

.NET

// VantagePay.SDK
using VantagePay.Models.Tokens;

var card = await client.Payments.VerifyCardTokenAsync(new VerifyCardRequest { Token = cardToken, VerificationCode = "123" });

---

Initiate a test payment to verify the ownership of a credit card.

POST /v2/token/card/verify/payment

Sample

POST /v2/token/card/verify/payment
{
  "yourReference": "{{$guid}}",
  "token": "FF5B3EF7CCDE40A4911CAE63ABF2416537FB49DEF0B14E2B8BFAB59B7F43A15E",
  "cvv": 123,
  "cardHolder": {
    "firstName": "John",
    "lastName": "Wick",
    "emailAddress": "demo@vantagepay.com",
    "phoneNumber": "233111222333",
    "countryIsoCode": "GHA"
   }
}

Auth: Access token (Bearer).

Request body

Field	Type	Required	Description
yourReference	string?	No	An external reference supplied by the caller.
consumer	object	No	Core identity and contact details for a consumer (end user).
token	string	Yes	A card token.
cvv	string?	No	The CVV for the card.
billingAddress	object	No	A physical address associated with a consumer, merchant, or other entity.
cardHolder	object	No	Contact and billing details for the card holder, required by card-present and online card payment processors.
location	object	No	A geographic coordinate with an optional time zone and description. Used to pin an address or entity on a map.
paymentStatusWebhook	object	No	A model to hold the details of a web hook that a caller of this API would like to be called back on.

{
  "yourReference": "string",
  "consumer": {
    "reference": "00000000-0000-0000-0000-000000000000",
    "yourReference": "string",
    "source": "string",
    "userReference": "00000000-0000-0000-0000-000000000000",
    "firstName": "string",
    "lastName": "string",
    "middleName": "string",
    "emailAddress": "string",
    "mobileNumber": "string",
    "countryIsoCode": "None",
    "dateOfBirth": "string",
    "gender": "Male",
    "preferredLanguage": "None",
    "kycStatusSummary": "Unverified",
    "isActive": true
  },
  "token": "string",
  "cvv": "string",
  "billingAddress": {
    "reference": "00000000-0000-0000-0000-000000000000",
    "yourReference": "string",
    "addressType": "MAIN",
    "addressLine1": "string",
    "addressLine2": "string",
    "addressLine3": "string",
    "postalCode": "string",
    "countryIsoCode": "None",
    "city": "string",
    "state": "string",
    "location": {},
    "description": "string",
    "formatted": "string",
    "isActive": true
  },
  "cardHolder": {
    "firstName": "string",
    "lastName": "string",
    "emailAddress": "string",
    "phoneNumber": "string",
    "countryIsoCode": "None",
    "shippingAddress": {}
  },
  "location": {
    "latitude": 0,
    "longitude": 0,
    "timeZone": "string",
    "description": "string"
  },
  "paymentStatusWebhook": {
    "callbackUrl": "string",
    "onPaymentCompleteOnly": true
  }
}

Responses

Status	Description
200	The request to initiate a card verification test payment was accepted and processed successfully.
202	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	Model to hold details of a response to a payment request.

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

Code samples

JavaScript

// @vantagepay/vantagepay
const status = await client.payments.createCardVerificationPayment({ token: cardToken, cvv: '123' })

.NET

// VantagePay.SDK
using VantagePay.Models.Payments.Requests;

var status = await client.Payments.CreateCardVerificationPaymentAsync(new CardVerificationPaymentRequest
{
    Token = cardToken,
    Cvv = "123",
});