VantagePay Documentation

Profile & Agreement ​

Create a new consumer. ​

POST /v1/consumer

Sample

json
POST /v1/consumer
{
  "yourReference": "{{$guid}}",
  "firstName": "{{$randomFirstName}}",
  "lastName": "{{$randomLastName}}",
  "emailAddress": "{{$randomEmail}}",
  "mobileNumber": "{{$randomPhoneNumber}}",
  "countryIsoCode": "GHA",
  "dateOfBirth": "1982-08-16",
  "addresses": [
    {
      "addressType": "POST",
      "addressLine1": "{{$randomStreetAddress}}",
      "addressLine2": "Test 1",
      "postalCode": "23021",
      "countryIsoCode": "GHA",
      "city": "Accra",
      "location": {
          "longitude": -0.08176,
          "latitude": 5.64311
        }
    }
  ]
}

Auth: Access token (Bearer).

Request body

FieldTypeRequiredDescription
createdDatestringNoThe UTC date and time at which this consumer record was created.
loginCredentialsobjectNoLogin credentials for a user account - used to authenticate and generate access tokens.
preferredNamestring?NoThe consumer's preferred display name, if different from their first name.
fullNameOfNextOfKinstring?NoThe full name of the consumer's nominated next of kin.
contactNumberForNextOfKinstring?NoThe contact phone number for the consumer's next of kin.
alternateContactNumberstring?NoAn additional contact number for the consumer, supplementary to their primary mobile number.
invitationCodestring?NoAn optional invitation or referral code entered by the consumer during registration.
isRegistrationCompletebooleanNotrue if the consumer has completed the self-registration flow.
isEmailVerifiedbooleanNotrue if the consumer has verified their email address via a confirmation link or OTP.
isMobileNumberVerifiedbooleanNotrue if the consumer has verified their mobile number via an OTP.
identityDocumentsarray<object>?NoThe identity documents (e.g. passport, national ID) associated with this consumer.
kycLookupResultsarray<object>?NoThe results of KYC identity lookups performed for this consumer across all configured providers.
filesarray<object>?NoFiles uploaded for this consumer (e.g. selfies, documents used for KYC and biometric verification).
devicesarray<object>?NoMobile and POS devices registered to this consumer for push notification delivery.
addressesarray<object>?NoPhysical addresses linked to this consumer (billing, shipping, postal, and primary).
beneficiariesarray<object>?NoSaved beneficiaries (payee shortcuts) associated with the consumer for faster repeat payments.
accountsobjectNoA container for all financial accounts linked to a consumer, grouped by account type.
attributesarray<object>?NoCustom attribute values associated with this consumer (partner-specific metadata).
rewardPointsInfoobjectNoA summary of a consumer's loyalty reward points balance and tier standing.
referencestring?NoThe system-assigned unique reference (UUID) for this consumer. Assigned on creation; null on new records before persistence.
yourReferencestring?NoAn optional external reference from the caller's system that identifies this consumer in their own data store.
sourcestring?NoThe identifier of the originating system or partner that registered this consumer.
userReferencestring?NoThe unique reference (UUID) of the authentication user account associated with this consumer profile, if one exists.
firstNamestring?NoThe consumer's first (given) name.
lastNamestring?NoThe consumer's last name (surname).
middleNamestring?NoThe consumer's middle name, if applicable.
emailAddressstring?NoThe consumer's email address.
mobileNumberstring?NoThe consumer's mobile number in international MSISDN format.
countryIsoCodeone of 248 values (e.g. None, AFG, ALB, ...)NoThe ISO 3166-1 alpha-3 country code of the country where the consumer resides.
dateOfBirthstring?NoThe consumer's date of birth.
genderMale, FemaleNoThe consumer's gender.
preferredLanguageone of 238 values (e.g. None, AAR, AFR, ...)NoThe consumer's preferred language for communications.
kycStatusSummaryUnverified, Verified, RejectedNoA summary of the consumer's Know Your Customer (KYC) verification status across all required identity checks.
isActivebooleanNotrue if the consumer account is active; false if it has been deactivated.
json
{
  "createdDate": "string",
  "loginCredentials": {
    "username": "string",
    "password": "string",
    "isLockedOut": true,
    "reasonForLockout": "string"
  },
  "preferredName": "string",
  "fullNameOfNextOfKin": "string",
  "contactNumberForNextOfKin": "string",
  "alternateContactNumber": "string",
  "invitationCode": "string",
  "isRegistrationComplete": true,
  "isEmailVerified": true,
  "isMobileNumberVerified": true,
  "identityDocuments": [
    {}
  ],
  "kycLookupResults": [
    {}
  ],
  "files": [
    {}
  ],
  "devices": [
    {}
  ],
  "addresses": [
    {}
  ],
  "beneficiaries": [
    {}
  ],
  "accounts": {
    "bankAccounts": [],
    "mobileWallets": [],
    "loanAccounts": [],
    "insurancePolicies": [],
    "genericAccounts": [],
    "cards": []
  },
  "attributes": [
    {}
  ],
  "rewardPointsInfo": {
    "pointsBalance": 0,
    "rewardTier": 0,
    "creditTransactionCount": 0
  },
  "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
}

Responses

StatusDescription
200The request was successful and a consumer was created.
400The request failed validation, the error object will contain further information.
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.
resultobjectNoCore identity and contact details for a consumer (end user).
json
{
  "success": true,
  "result": {
    "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
  }
}

Code samples ​

ts
// @vantagepay/vantagepay
const consumer = await client.consumers.createConsumer({
  firstName: 'Jane',
  lastName: 'Doe',
  mobileNumber: '233555666112',
  emailAddress: 'customer@example.com',
  countryIsoCode: 'GHA',
  languageIsoCode: 'ENG',
})
csharp
// VantagePay.SDK
using VantagePay.Models.Consumers;
using VantagePay.Models.Lookups;

var consumer = await client.Consumers.CreateConsumerAsync(new Consumer
{
    FirstName = "Jane",
    LastName = "Doe",
    MobileNumber = "233555666112",
    EmailAddress = "customer@example.com",
    CountryIsoCode = Country.GHA,
    LanguageIsoCode = Language.ENG,
});

Update your consumer details. ​

PUT /v1/consumer

Sample

json
PUT /v1/consumer
{
  "reference": "ff1af424-9ece-42d1-897d-f023f91f3ce2",
  "firstName": "{{$randomFirstName}}",
  "lastName": "{{$randomLastName}}",
  "emailAddress": "{{$randomEmail}}",
  "mobileNumber": "{{$randomPhoneNumber}}",
  "countryIsoCode": "GHA",
  "dateOfBirth": "1983-10-16"
}

Auth: Access token (Bearer).

Request body

FieldTypeRequiredDescription
createdDatestringNoThe UTC date and time at which this consumer record was created.
loginCredentialsobjectNoLogin credentials for a user account - used to authenticate and generate access tokens.
preferredNamestring?NoThe consumer's preferred display name, if different from their first name.
fullNameOfNextOfKinstring?NoThe full name of the consumer's nominated next of kin.
contactNumberForNextOfKinstring?NoThe contact phone number for the consumer's next of kin.
alternateContactNumberstring?NoAn additional contact number for the consumer, supplementary to their primary mobile number.
invitationCodestring?NoAn optional invitation or referral code entered by the consumer during registration.
isRegistrationCompletebooleanNotrue if the consumer has completed the self-registration flow.
isEmailVerifiedbooleanNotrue if the consumer has verified their email address via a confirmation link or OTP.
isMobileNumberVerifiedbooleanNotrue if the consumer has verified their mobile number via an OTP.
identityDocumentsarray<object>?NoThe identity documents (e.g. passport, national ID) associated with this consumer.
kycLookupResultsarray<object>?NoThe results of KYC identity lookups performed for this consumer across all configured providers.
filesarray<object>?NoFiles uploaded for this consumer (e.g. selfies, documents used for KYC and biometric verification).
devicesarray<object>?NoMobile and POS devices registered to this consumer for push notification delivery.
addressesarray<object>?NoPhysical addresses linked to this consumer (billing, shipping, postal, and primary).
beneficiariesarray<object>?NoSaved beneficiaries (payee shortcuts) associated with the consumer for faster repeat payments.
accountsobjectNoA container for all financial accounts linked to a consumer, grouped by account type.
attributesarray<object>?NoCustom attribute values associated with this consumer (partner-specific metadata).
rewardPointsInfoobjectNoA summary of a consumer's loyalty reward points balance and tier standing.
referencestring?NoThe system-assigned unique reference (UUID) for this consumer. Assigned on creation; null on new records before persistence.
yourReferencestring?NoAn optional external reference from the caller's system that identifies this consumer in their own data store.
sourcestring?NoThe identifier of the originating system or partner that registered this consumer.
userReferencestring?NoThe unique reference (UUID) of the authentication user account associated with this consumer profile, if one exists.
firstNamestring?NoThe consumer's first (given) name.
lastNamestring?NoThe consumer's last name (surname).
middleNamestring?NoThe consumer's middle name, if applicable.
emailAddressstring?NoThe consumer's email address.
mobileNumberstring?NoThe consumer's mobile number in international MSISDN format.
countryIsoCodeone of 248 values (e.g. None, AFG, ALB, ...)NoThe ISO 3166-1 alpha-3 country code of the country where the consumer resides.
dateOfBirthstring?NoThe consumer's date of birth.
genderMale, FemaleNoThe consumer's gender.
preferredLanguageone of 238 values (e.g. None, AAR, AFR, ...)NoThe consumer's preferred language for communications.
kycStatusSummaryUnverified, Verified, RejectedNoA summary of the consumer's Know Your Customer (KYC) verification status across all required identity checks.
isActivebooleanNotrue if the consumer account is active; false if it has been deactivated.
json
{
  "createdDate": "string",
  "loginCredentials": {
    "username": "string",
    "password": "string",
    "isLockedOut": true,
    "reasonForLockout": "string"
  },
  "preferredName": "string",
  "fullNameOfNextOfKin": "string",
  "contactNumberForNextOfKin": "string",
  "alternateContactNumber": "string",
  "invitationCode": "string",
  "isRegistrationComplete": true,
  "isEmailVerified": true,
  "isMobileNumberVerified": true,
  "identityDocuments": [
    {}
  ],
  "kycLookupResults": [
    {}
  ],
  "files": [
    {}
  ],
  "devices": [
    {}
  ],
  "addresses": [
    {}
  ],
  "beneficiaries": [
    {}
  ],
  "accounts": {
    "bankAccounts": [],
    "mobileWallets": [],
    "loanAccounts": [],
    "insurancePolicies": [],
    "genericAccounts": [],
    "cards": []
  },
  "attributes": [
    {}
  ],
  "rewardPointsInfo": {
    "pointsBalance": 0,
    "rewardTier": 0,
    "creditTransactionCount": 0
  },
  "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
}

Responses

StatusDescription
200The request was successful and the consumer details were updated.
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.
404The request was successful but does not return any results.
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.
resultobjectNoFull consumer profile, extending ZGA.Core.Models.Consumers.BasicConsumer with linked accounts, KYC documents, devices, notification preferences, and extended identity fields.
json
{
  "success": true,
  "result": {
    "createdDate": "string",
    "loginCredentials": {},
    "preferredName": "string",
    "fullNameOfNextOfKin": "string",
    "contactNumberForNextOfKin": "string",
    "alternateContactNumber": "string",
    "invitationCode": "string",
    "isRegistrationComplete": true,
    "isEmailVerified": true,
    "isMobileNumberVerified": true,
    "identityDocuments": [],
    "kycLookupResults": [],
    "files": [],
    "devices": [],
    "addresses": [],
    "beneficiaries": [],
    "accounts": {},
    "attributes": [],
    "rewardPointsInfo": {},
    "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
  }
}

Code samples ​

ts
// @vantagepay/vantagepay
const consumer = await client.consumers.getConsumer()
consumer.preferredName = 'Janey'
const updated = await client.consumers.updateConsumer(consumer)
csharp
// VantagePay.SDK
var consumer = await client.Consumers.GetConsumerAsync();
consumer!.PreferredName = "Janey";
var updated = await client.Consumers.UpdateConsumerAsync(consumer);

Delete your consumer details. ​

DELETE /v1/consumer

Sample

json
DELETE /v1/consumer

Auth: Access token (Bearer).

Responses

StatusDescription
200The request was successful and the consumer was deleted.
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.
404The request was successful but does not return any results.
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 ​

ts
// @vantagepay/vantagepay
await client.consumers.deleteConsumer() // also ends the session
csharp
// VantagePay.SDK
await client.Consumers.DeleteConsumerAsync(); // also ends the session

Get your consumer information. ​

GET /v1/consumer

Sample

json
GET /v1/consumer/ff1af424-9ece-42d1-897d-f023f91f3ce2

Auth: Access token (Bearer).

Responses

StatusDescription
200The request was successful and the consumer information was returned.
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.
404The request was successful but does not return any results.
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.
resultobjectNoFull consumer profile, extending ZGA.Core.Models.Consumers.BasicConsumer with linked accounts, KYC documents, devices, notification preferences, and extended identity fields.
json
{
  "success": true,
  "result": {
    "createdDate": "string",
    "loginCredentials": {},
    "preferredName": "string",
    "fullNameOfNextOfKin": "string",
    "contactNumberForNextOfKin": "string",
    "alternateContactNumber": "string",
    "invitationCode": "string",
    "isRegistrationComplete": true,
    "isEmailVerified": true,
    "isMobileNumberVerified": true,
    "identityDocuments": [],
    "kycLookupResults": [],
    "files": [],
    "devices": [],
    "addresses": [],
    "beneficiaries": [],
    "accounts": {},
    "attributes": [],
    "rewardPointsInfo": {},
    "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
  }
}

Code samples ​

ts
// @vantagepay/vantagepay
const consumer = await client.consumers.getConsumer()
csharp
// VantagePay.SDK
var consumer = await client.Consumers.GetConsumerAsync();

Retrieves the HTML content of the consumer agreement, populated with the current consumer's information. ​

GET /v1/consumer/agreement

The returned HTML is personalized with the consumer's name, address, and the current date. The response is served with a content type of "text/html" and is cached for 24 hours. If the consumer reference is invalid, or if the agreement template or consumer information cannot be found, an appropriate error response is returned.

Auth: Access token (Bearer).

Responses

StatusDescription
200The request was successful but does not return any results.
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.

Code samples ​

ts
// @vantagepay/vantagepay
const agreementHtml = await client.consumers.getConsumerAgreement()
csharp
// VantagePay.SDK
var agreementHtml = await client.Consumers.GetConsumerAgreementAsync();

Accepts the agreement for the currently authenticated user and creates a signed agreement file if one does not already exist within the last 24 hours. ​

POST /v1/consumer/agreement/accept

If the user has already accepted and verified the agreement within the past 24 hours, the method returns an Accepted response without creating a new agreement file. Otherwise, it generates a new agreement PDF, uploads it, and marks it as verified. The method requires the user to be authenticated and associated with a valid consumer reference.

Auth: Access token (Bearer).

Responses

StatusDescription
200The request was successful but does not return any results.
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 ​

ts
// @vantagepay/vantagepay
await client.consumers.acceptConsumerAgreement()
csharp
// VantagePay.SDK
await client.Consumers.AcceptConsumerAgreementAsync();

Create a consumer contact/lead record. ​

POST /v1/consumer/contact

Auth: Access token (Bearer).

Request body

FieldTypeRequiredDescription
detailsobject?NoThe contact detail key/value pairs. Keys and values are both strings.
json
{
  "details": {}
}

Responses

StatusDescription
200The request was successful and a consumer contact/lead record was created.
400The request failed validation, the error object will contain further information.
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 ​

ts
// @vantagepay/vantagepay
await client.consumers.contactSupport({
  details: { subject: 'Card query', message: 'I need help with a transaction.' },
})
csharp
// VantagePay.SDK
// Sends a support contact request. Not wrapped by the .NET SDK.
// 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/consumer/contact", content: null);
response.EnsureSuccessStatusCode();

Stores feedback from a consumer. ​

POST /v1/consumer/feedback/send

Sample

json
POST /v1/consumer/feedbcak
{
  "description": "This is amazing!"
}

Auth: Access token (Bearer).

Request body

FieldTypeRequiredDescription
descriptionstring?NoThe free-text feedback message left by the consumer.
json
{
  "description": "string"
}

Responses

StatusDescription
200The request was successful and the feedback was saved.
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 ​

ts
// @vantagepay/vantagepay
await client.consumers.submitFeedback('Great app, very easy to use!')
csharp
// VantagePay.SDK
await client.Consumers.AddConsumerFeedbackAsync("Great app, very easy to use!");

Payments for Africa

© VantagePay 2026