Profile
Create a consumer.
POST /v1/consumer/admin
Sample
json
POST /v1/consumer/admin
{
"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: API key (VantagePayAdminClient).
Request body
| Field | Type | Required | Description |
|---|---|---|---|
createdDate | string | No | The UTC date and time at which this consumer record was created. |
loginCredentials | object | No | Login credentials for a user account - used to authenticate and generate access tokens. |
preferredName | string? | No | The consumer's preferred display name, if different from their first name. |
fullNameOfNextOfKin | string? | No | The full name of the consumer's nominated next of kin. |
contactNumberForNextOfKin | string? | No | The contact phone number for the consumer's next of kin. |
alternateContactNumber | string? | No | An additional contact number for the consumer, supplementary to their primary mobile number. |
invitationCode | string? | No | An optional invitation or referral code entered by the consumer during registration. |
isRegistrationComplete | boolean | No | true if the consumer has completed the self-registration flow. |
isEmailVerified | boolean | No | true if the consumer has verified their email address via a confirmation link or OTP. |
isMobileNumberVerified | boolean | No | true if the consumer has verified their mobile number via an OTP. |
identityDocuments | array<object>? | No | The identity documents (e.g. passport, national ID) associated with this consumer. |
kycLookupResults | array<object>? | No | The results of KYC identity lookups performed for this consumer across all configured providers. |
files | array<object>? | No | Files uploaded for this consumer (e.g. selfies, documents used for KYC and biometric verification). |
devices | array<object>? | No | Mobile and POS devices registered to this consumer for push notification delivery. |
addresses | array<object>? | No | Physical addresses linked to this consumer (billing, shipping, postal, and primary). |
beneficiaries | array<object>? | No | Saved beneficiaries (payee shortcuts) associated with the consumer for faster repeat payments. |
accounts | object | No | A container for all financial accounts linked to a consumer, grouped by account type. |
attributes | array<object>? | No | Custom attribute values associated with this consumer (partner-specific metadata). |
rewardPointsInfo | object | No | A summary of a consumer's loyalty reward points balance and tier standing. |
reference | string? | No | The system-assigned unique reference (UUID) for this consumer. Assigned on creation; null on new records before persistence. |
yourReference | string? | No | An optional external reference from the caller's system that identifies this consumer in their own data store. |
source | string? | No | The identifier of the originating system or partner that registered this consumer. |
userReference | string? | No | The unique reference (UUID) of the authentication user account associated with this consumer profile, if one exists. |
firstName | string? | No | The consumer's first (given) name. |
lastName | string? | No | The consumer's last name (surname). |
middleName | string? | No | The consumer's middle name, if applicable. |
emailAddress | string? | No | The consumer's email address. |
mobileNumber | string? | No | The consumer's mobile number in international MSISDN format. |
countryIsoCode | one of 248 values (e.g. None, AFG, ALB, ...) | No | The ISO 3166-1 alpha-3 country code of the country where the consumer resides. |
dateOfBirth | string? | No | The consumer's date of birth. |
gender | Male, Female | No | The consumer's gender. |
preferredLanguage | one of 238 values (e.g. None, AAR, AFR, ...) | No | The consumer's preferred language for communications. |
kycStatusSummary | Unverified, Verified, Rejected | No | A summary of the consumer's Know Your Customer (KYC) verification status across all required identity checks. |
isActive | boolean | No | true 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
| Status | Description |
|---|---|
200 | The request was successful and a consumer was created. |
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 | Full 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
WARNING
The JavaScript SDK does not cover admin APIs - use the .NET SDK.
csharp
using VantagePay.Models.Consumers;
using VantagePay.Models.Lookups;
var consumer = await adminClient.Consumers.CreateConsumerAsync(new Consumer
{
FirstName = "Jane",
LastName = "Doe",
MobileNumber = "233555666112",
CountryIsoCode = Country.GHA,
});Update consumer details.
PUT /v1/consumer/admin
Sample
json
PUT /v1/consumer/admin
{
"reference": "ff1af424-9ece-42d1-897d-f023f91f3ce2",
"firstName": "{{$randomFirstName}}",
"lastName": "{{$randomLastName}}",
"emailAddress": "{{$randomEmail}}",
"mobileNumber": "{{$randomPhoneNumber}}",
"countryIsoCode": "GHA",
"dateOfBirth": "1983-10-16"
}Auth: API key (VantagePayAdminClient).
Request body
| Field | Type | Required | Description |
|---|---|---|---|
createdDate | string | No | The UTC date and time at which this consumer record was created. |
loginCredentials | object | No | Login credentials for a user account - used to authenticate and generate access tokens. |
preferredName | string? | No | The consumer's preferred display name, if different from their first name. |
fullNameOfNextOfKin | string? | No | The full name of the consumer's nominated next of kin. |
contactNumberForNextOfKin | string? | No | The contact phone number for the consumer's next of kin. |
alternateContactNumber | string? | No | An additional contact number for the consumer, supplementary to their primary mobile number. |
invitationCode | string? | No | An optional invitation or referral code entered by the consumer during registration. |
isRegistrationComplete | boolean | No | true if the consumer has completed the self-registration flow. |
isEmailVerified | boolean | No | true if the consumer has verified their email address via a confirmation link or OTP. |
isMobileNumberVerified | boolean | No | true if the consumer has verified their mobile number via an OTP. |
identityDocuments | array<object>? | No | The identity documents (e.g. passport, national ID) associated with this consumer. |
kycLookupResults | array<object>? | No | The results of KYC identity lookups performed for this consumer across all configured providers. |
files | array<object>? | No | Files uploaded for this consumer (e.g. selfies, documents used for KYC and biometric verification). |
devices | array<object>? | No | Mobile and POS devices registered to this consumer for push notification delivery. |
addresses | array<object>? | No | Physical addresses linked to this consumer (billing, shipping, postal, and primary). |
beneficiaries | array<object>? | No | Saved beneficiaries (payee shortcuts) associated with the consumer for faster repeat payments. |
accounts | object | No | A container for all financial accounts linked to a consumer, grouped by account type. |
attributes | array<object>? | No | Custom attribute values associated with this consumer (partner-specific metadata). |
rewardPointsInfo | object | No | A summary of a consumer's loyalty reward points balance and tier standing. |
reference | string? | No | The system-assigned unique reference (UUID) for this consumer. Assigned on creation; null on new records before persistence. |
yourReference | string? | No | An optional external reference from the caller's system that identifies this consumer in their own data store. |
source | string? | No | The identifier of the originating system or partner that registered this consumer. |
userReference | string? | No | The unique reference (UUID) of the authentication user account associated with this consumer profile, if one exists. |
firstName | string? | No | The consumer's first (given) name. |
lastName | string? | No | The consumer's last name (surname). |
middleName | string? | No | The consumer's middle name, if applicable. |
emailAddress | string? | No | The consumer's email address. |
mobileNumber | string? | No | The consumer's mobile number in international MSISDN format. |
countryIsoCode | one of 248 values (e.g. None, AFG, ALB, ...) | No | The ISO 3166-1 alpha-3 country code of the country where the consumer resides. |
dateOfBirth | string? | No | The consumer's date of birth. |
gender | Male, Female | No | The consumer's gender. |
preferredLanguage | one of 238 values (e.g. None, AAR, AFR, ...) | No | The consumer's preferred language for communications. |
kycStatusSummary | Unverified, Verified, Rejected | No | A summary of the consumer's Know Your Customer (KYC) verification status across all required identity checks. |
isActive | boolean | No | true 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
| Status | Description |
|---|---|
200 | The request was successful and the consumer details were updated. |
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. |
404 | 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 | Full 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
WARNING
The JavaScript SDK does not cover admin APIs - use the .NET SDK.
csharp
var consumer = await adminClient.Consumers.GetConsumerAsync(Guid.Parse("7c9e6679-7425-40de-944b-e07fc1f90ae7"));
consumer!.PreferredName = "Janey";
var updated = await adminClient.Consumers.UpdateConsumerAsync(consumer);Retrieves the collection of consumers associated with the specified username.
GET /v1/consumer/admin
Auth: API key (VantagePayAdminClient).
Parameters
| Name | In | Required | Description |
|---|---|---|---|
username | query | No | The username of the user whose associated consumers are to be retrieved. |
Responses
| Status | Description |
|---|---|
200 | The request was successful and the consumer information 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. |
404 | 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 | array<object>? | No | Gets the response payload. |
json
{
"success": true,
"result": [
{}
]
}Code samples
WARNING
The JavaScript SDK does not cover admin APIs - use the .NET SDK.
csharp
var consumers = await adminClient.Consumers.GetConsumersByUsernameAsync("233555666112");Delete a consumer.
DELETE /v1/consumer/admin/{consumerReference}
Sample
json
DELETE /v1/consumer/admin/ff1af424-9ece-42d1-897d-f023f91f3ce2Auth: API key (VantagePayAdminClient).
Parameters
| Name | In | Required | Description |
|---|---|---|---|
consumerReference | path | Yes | A globally unique internal consumer reference (UUID) or an external consumer reference. |
Responses
| Status | Description |
|---|---|
200 | The request was successful and the consumer was deleted. |
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. |
404 | 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. |
json
{
"success": true
}Code samples
WARNING
The JavaScript SDK does not cover admin APIs - use the .NET SDK.
csharp
await adminClient.Consumers.DeleteConsumerAsync(Guid.Parse("7c9e6679-7425-40de-944b-e07fc1f90ae7"));Get consumer information.
GET /v1/consumer/admin/{consumerReference}
Sample
json
GET /v1/consumer/admin/ff1af424-9ece-42d1-897d-f023f91f3ce2Auth: API key (VantagePayAdminClient).
Parameters
| Name | In | Required | Description |
|---|---|---|---|
consumerReference | path | Yes | A globally unique internal consumer reference (UUID) or an external consumer reference. |
Responses
| Status | Description |
|---|---|
200 | The request was successful and the consumer information 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. |
404 | 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 | Full 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
WARNING
The JavaScript SDK does not cover admin APIs - use the .NET SDK.
csharp
var consumer = await adminClient.Consumers.GetConsumerAsync(Guid.Parse("7c9e6679-7425-40de-944b-e07fc1f90ae7"));