Profile, Agreement & OTP

Create a new merchant.

POST /v1/merchant

Auth: Access token (Bearer).

Request body

Field	Type	Required	Description
createdDate	string	No	The UTC date and time at which this merchant record was created.
loginCredentials	object	No	Login credentials for a user account - used to authenticate and generate access tokens.
tradingName	string?	No	The merchant's trading name if different from their registered business name.
franchiseName	string?	No	The name of the franchise group this merchant belongs to, if applicable.
capturedBy	string?	No	The identifier of the user or system that captured this merchant record.
capturedFrom	string?	No	The source system or channel through which this merchant was captured.
industry	None, Retail, Restaurant, Forecourt, Workshop	No	The industry classification of this merchant's business.
phoneNumber	string?	No	The merchant's landline or switchboard phone number.
notificationEmailAddress	string?	No	The email address to which payment notifications are sent.
notificationMobileNumber	string?	No	The mobile number to which payment notification SMSes are sent.
city	string?	No	The city in which the merchant primarily operates.
state	string?	No	The state or province in which the merchant primarily operates.
languageIsoCode	one of 238 values (e.g. None, AAR, AFR, ...)	No	The merchant's preferred language for communications.
webSiteUrl	string?	No	The merchant's website URL.
isRegistrationComplete	boolean	No	true if the merchant has completed their self-registration flow.
isEmailVerified	boolean	No	true if the merchant has verified their email address.
isMobileNumberVerified	boolean	No	true if the merchant has verified their mobile number via OTP.
vCard	string?	No	A vCard-encoded contact string for this merchant, generated by the system.
logoImage	string?	No	A base64-encoded logo image for the merchant, used in hosted payment pages and receipts.
taxNumber	string?	No	The merchant's tax registration number (e.g. VAT number).
companyRegistrationNumber	string?	No	The merchant's company registration number as issued by the registrar.
companyRegistrationDate	string?	No	The date on which the merchant's company was formally registered.
adminPasscode	string?	No	An optional admin passcode for POS terminal access control.
logoUrl	string?	No	The publicly accessible URL of the merchant's logo image.
hostedPaymentUrl	string?	No	The URL for this merchant's hosted payment page (VantagePay-generated).
hostedPaymentOptions	object	No	Configuration options for a merchant's hosted (online / card-not-present) payment page, including accepted card schemes and settlement timing.
posOptions	object	No	Feature flags that control which transaction types and capabilities are enabled on a merchant's POS terminals.
business	object	No	The legal business entity associated with a merchant, used for KYB verification and settlement.
addresses	array<object>?	No	Physical addresses linked to this merchant.
employees	array<object>?	No	Employees associated with this merchant.
terminals	array<object>?	No	POS terminals configured for this merchant.
files	array<object>?	No	Files uploaded for this merchant (e.g. KYB documents, business registration certificates).
notificationSettings	array<object>?	No	Configured notification event preferences for this merchant.
attributes	array<object>?	No	Custom attribute values associated with this merchant (partner-specific metadata).
bankAccounts	array<object>?	No	Bank accounts linked to this merchant for settlement.
mobileWallets	array<object>?	No	Mobile money wallet accounts linked to this merchant for settlement.
operatingTimes	array<object>?	No	The operating hours configured for this merchant.
devices	array<object>?	No	Mobile and POS devices registered to this merchant for push notification delivery.
qrCodes	array<object>?	No	EMV QR codes configured for this merchant.
assignedProductReferences	array<string>?	No	The set of product references (from other merchants) that this merchant has been granted access to in addition to their own products. Sync semantics on admin merchant update: null = caller did not supply the field (no change is applied); empty collection = all existing assignments are cleared; populated collection = assignments are replaced with exactly the supplied set. The self-service merchant update controller strips this field before persistence so only admins can modify merchant product assignments.
reference	string?	No	The system-assigned unique reference (UUID) for this merchant. Assigned on creation; null on new records before persistence.
userReference	string?	No	The unique reference (UUID) of the authentication user account associated with this merchant profile, if one exists.
yourReference	string?	No	An optional external reference from the caller's system that identifies this merchant in their own data store.
source	string?	No	The identifier of the originating system or partner that registered this merchant.
name	string	Yes	The trading name of the merchant.
categoryCode	one of 967 values (e.g. 0, 11, 701, ...)	Yes	The ISO 18245 Merchant Category Code (MCC) that classifies the merchant's type of business.
category	string?	No	The display name of the merchant category, derived from ZGA.Core.Models.Merchants.BasicMerchant.CategoryCode.
emailAddress	string?	No	The primary contact email address for the merchant.
mobileNumber	string?	No	The primary contact mobile number for the merchant 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 in which the merchant operates.
currency	one of 106 values (e.g. None, AFN, ALL, ...)	Yes	The ISO 4217 currency in which the merchant transacts.
kybStatusSummary	Unverified, Verified, PartiallyVerified, Rejected	No	A summary of the merchant's Know Your Business (KYB) verification status.
shortCode	integer?	No	A short numeric code assigned to the merchant that can be used as a compact identifier in USSD/QR flows.
isActive	boolean	No	true if the merchant account is currently active and able to accept payments.

{
  "createdDate": "string",
  "loginCredentials": {
    "username": "string",
    "password": "string",
    "isLockedOut": true,
    "reasonForLockout": "string"
  },
  "tradingName": "string",
  "franchiseName": "string",
  "capturedBy": "string",
  "capturedFrom": "string",
  "industry": "None",
  "phoneNumber": "string",
  "notificationEmailAddress": "string",
  "notificationMobileNumber": "string",
  "city": "string",
  "state": "string",
  "languageIsoCode": "None",
  "webSiteUrl": "string",
  "isRegistrationComplete": true,
  "isEmailVerified": true,
  "isMobileNumberVerified": true,
  "vCard": "string",
  "logoImage": "string",
  "taxNumber": "string",
  "companyRegistrationNumber": "string",
  "companyRegistrationDate": "string",
  "adminPasscode": "string",
  "logoUrl": "string",
  "hostedPaymentUrl": "string",
  "hostedPaymentOptions": {
    "cardNotPresentMID": 0,
    "isVisaEnabled": true,
    "isMastercardEnabled": true,
    "isAmericanExpressEnabled": true,
    "isDinersEnabled": true,
    "settlementTime": "None"
  },
  "posOptions": {
    "isRefundsEnabled": true,
    "isCancellationsEnabled": true,
    "isPurchaseWithCashbackEnabled": true,
    "isWithdrawalsEnabled": true,
    "isBalanceCheckEnabled": true,
    "isCurrencyConversionEnabled": true,
    "isRcsPaymentEnabled": true,
    "isDebiCheckEnabled": true,
    "isPreAuthorizationEnabled": true,
    "isManualCardEntryEnabled": true,
    "isInvoiceNumberEnabled": true,
    "isPasscodeAlwaysRequired": true,
    "fuelPurchaseMethod": "ByAmount"
  },
  "business": {
    "reference": "00000000-0000-0000-0000-000000000000",
    "parentBusinessReference": "00000000-0000-0000-0000-000000000000",
    "createdDate": "string",
    "yourReference": "string",
    "source": "string",
    "name": "string",
    "emailAddress": "string",
    "mobileNumber": "string",
    "phoneNumber": "string",
    "isEmailVerified": true,
    "isMobileNumberVerified": true,
    "isActive": true
  },
  "addresses": [
    {}
  ],
  "employees": [
    {}
  ],
  "terminals": [
    {}
  ],
  "files": [
    {}
  ],
  "notificationSettings": [
    {}
  ],
  "attributes": [
    {}
  ],
  "bankAccounts": [
    {}
  ],
  "mobileWallets": [
    {}
  ],
  "operatingTimes": [
    {}
  ],
  "devices": [
    {}
  ],
  "qrCodes": [
    {}
  ],
  "assignedProductReferences": [
    "00000000-0000-0000-0000-000000000000"
  ],
  "reference": "00000000-0000-0000-0000-000000000000",
  "userReference": "00000000-0000-0000-0000-000000000000",
  "yourReference": "string",
  "source": "string",
  "name": "string",
  "categoryCode": 0,
  "category": "string",
  "emailAddress": "string",
  "mobileNumber": "string",
  "countryIsoCode": "None",
  "currency": "None",
  "kybStatusSummary": "Unverified",
  "shortCode": 0,
  "isActive": true
}

Responses

Status	Description
200	The request was successful and a merchant 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	Core identity, categorisation, and contact details for a merchant.

{
  "success": true,
  "result": {
    "reference": "00000000-0000-0000-0000-000000000000",
    "userReference": "00000000-0000-0000-0000-000000000000",
    "yourReference": "string",
    "source": "string",
    "name": "string",
    "categoryCode": 0,
    "category": "string",
    "emailAddress": "string",
    "mobileNumber": "string",
    "countryIsoCode": "None",
    "currency": "None",
    "kybStatusSummary": "Unverified",
    "shortCode": 0,
    "isActive": true
  }
}

Code samples

JavaScript

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

const merchant = await client.merchants.createMerchant({
  name: 'Acme Stores',
  tradingName: 'Acme',
  industry: 'Retail',
  city: 'Accra',
  languageIsoCode: 'ENG',
})

.NET

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

var merchant = await client.Merchants.CreateMerchantAsync(new Merchant
{
    Name = "Acme Stores",
    TradingName = "Acme",
    Industry = Industry.Retail,
    City = "Accra",
    LanguageIsoCode = Language.ENG,
});

---

Update your merchant information.

PUT /v1/merchant

Sample

PUT /v1/merchant
{
"yourReference": "123456",
"reference": "8a8b9824-ac42-42e5-b955-a7a84425988c",
"category": "5399",
"categoryCode": 5399,
"currency": "GHS",
"emailAddress": "demo@vantagepay.com",
"languageIsoCode": "ENG",
"loginCredentials": null,
"mobileNumber": "233111222333",
"name": "Global Enterprises",
"addresses": [
  {
    "addressLine1": "DEFAULT",
    "addressLine2": "",
    "addressLine3": "",
    "addressType": 1,
    "city": "Accra",
    "countryIsoCode": "GHA",
    "postalCode": "0000",
    "reference": "caba6360-1043-41c7-89ad-7402ffebc392",
    "state": "Gt Accra",
    "yourReference": "ADDRESS_1234",
    "location": {
      "latitude": 0.0,
      "longitude": 0.0,
      "timeZone": "UTC"
    }
  }
],
"attributes": [
  {
    "Id": 8,
    "Name": null,
    "Value": "0241931361"
  }
],
"bankAccount": {
  "accountNumber": "1050325859314",
  "bank": "FBL",
  "currency": "GHS"
},
"employees": [],
"notificationSettings": [],
"operatingTimes": [],
"settlementBankAccount": {
  "accountName": null,
  "accountNumber": "1555555777777",
  "bank": "FBL",
  "currency": "GHS"
},
"terminals": [
  {
    "name": "Terminal 1",
    "qrCodes": null,
    "reference": "dc1ea64e-0b38-4f3d-a15e-179df92b014c",
    "yourReference": "2097",
  }
],
"webSiteUrl": ""

}

Auth: Access token (Bearer).

Request body

Field	Type	Required	Description
createdDate	string	No	The UTC date and time at which this merchant record was created.
loginCredentials	object	No	Login credentials for a user account - used to authenticate and generate access tokens.
tradingName	string?	No	The merchant's trading name if different from their registered business name.
franchiseName	string?	No	The name of the franchise group this merchant belongs to, if applicable.
capturedBy	string?	No	The identifier of the user or system that captured this merchant record.
capturedFrom	string?	No	The source system or channel through which this merchant was captured.
industry	None, Retail, Restaurant, Forecourt, Workshop	No	The industry classification of this merchant's business.
phoneNumber	string?	No	The merchant's landline or switchboard phone number.
notificationEmailAddress	string?	No	The email address to which payment notifications are sent.
notificationMobileNumber	string?	No	The mobile number to which payment notification SMSes are sent.
city	string?	No	The city in which the merchant primarily operates.
state	string?	No	The state or province in which the merchant primarily operates.
languageIsoCode	one of 238 values (e.g. None, AAR, AFR, ...)	No	The merchant's preferred language for communications.
webSiteUrl	string?	No	The merchant's website URL.
isRegistrationComplete	boolean	No	true if the merchant has completed their self-registration flow.
isEmailVerified	boolean	No	true if the merchant has verified their email address.
isMobileNumberVerified	boolean	No	true if the merchant has verified their mobile number via OTP.
vCard	string?	No	A vCard-encoded contact string for this merchant, generated by the system.
logoImage	string?	No	A base64-encoded logo image for the merchant, used in hosted payment pages and receipts.
taxNumber	string?	No	The merchant's tax registration number (e.g. VAT number).
companyRegistrationNumber	string?	No	The merchant's company registration number as issued by the registrar.
companyRegistrationDate	string?	No	The date on which the merchant's company was formally registered.
adminPasscode	string?	No	An optional admin passcode for POS terminal access control.
logoUrl	string?	No	The publicly accessible URL of the merchant's logo image.
hostedPaymentUrl	string?	No	The URL for this merchant's hosted payment page (VantagePay-generated).
hostedPaymentOptions	object	No	Configuration options for a merchant's hosted (online / card-not-present) payment page, including accepted card schemes and settlement timing.
posOptions	object	No	Feature flags that control which transaction types and capabilities are enabled on a merchant's POS terminals.
business	object	No	The legal business entity associated with a merchant, used for KYB verification and settlement.
addresses	array<object>?	No	Physical addresses linked to this merchant.
employees	array<object>?	No	Employees associated with this merchant.
terminals	array<object>?	No	POS terminals configured for this merchant.
files	array<object>?	No	Files uploaded for this merchant (e.g. KYB documents, business registration certificates).
notificationSettings	array<object>?	No	Configured notification event preferences for this merchant.
attributes	array<object>?	No	Custom attribute values associated with this merchant (partner-specific metadata).
bankAccounts	array<object>?	No	Bank accounts linked to this merchant for settlement.
mobileWallets	array<object>?	No	Mobile money wallet accounts linked to this merchant for settlement.
operatingTimes	array<object>?	No	The operating hours configured for this merchant.
devices	array<object>?	No	Mobile and POS devices registered to this merchant for push notification delivery.
qrCodes	array<object>?	No	EMV QR codes configured for this merchant.
assignedProductReferences	array<string>?	No	The set of product references (from other merchants) that this merchant has been granted access to in addition to their own products. Sync semantics on admin merchant update: null = caller did not supply the field (no change is applied); empty collection = all existing assignments are cleared; populated collection = assignments are replaced with exactly the supplied set. The self-service merchant update controller strips this field before persistence so only admins can modify merchant product assignments.
reference	string?	No	The system-assigned unique reference (UUID) for this merchant. Assigned on creation; null on new records before persistence.
userReference	string?	No	The unique reference (UUID) of the authentication user account associated with this merchant profile, if one exists.
yourReference	string?	No	An optional external reference from the caller's system that identifies this merchant in their own data store.
source	string?	No	The identifier of the originating system or partner that registered this merchant.
name	string	Yes	The trading name of the merchant.
categoryCode	one of 967 values (e.g. 0, 11, 701, ...)	Yes	The ISO 18245 Merchant Category Code (MCC) that classifies the merchant's type of business.
category	string?	No	The display name of the merchant category, derived from ZGA.Core.Models.Merchants.BasicMerchant.CategoryCode.
emailAddress	string?	No	The primary contact email address for the merchant.
mobileNumber	string?	No	The primary contact mobile number for the merchant 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 in which the merchant operates.
currency	one of 106 values (e.g. None, AFN, ALL, ...)	Yes	The ISO 4217 currency in which the merchant transacts.
kybStatusSummary	Unverified, Verified, PartiallyVerified, Rejected	No	A summary of the merchant's Know Your Business (KYB) verification status.
shortCode	integer?	No	A short numeric code assigned to the merchant that can be used as a compact identifier in USSD/QR flows.
isActive	boolean	No	true if the merchant account is currently active and able to accept payments.

{
  "createdDate": "string",
  "loginCredentials": {
    "username": "string",
    "password": "string",
    "isLockedOut": true,
    "reasonForLockout": "string"
  },
  "tradingName": "string",
  "franchiseName": "string",
  "capturedBy": "string",
  "capturedFrom": "string",
  "industry": "None",
  "phoneNumber": "string",
  "notificationEmailAddress": "string",
  "notificationMobileNumber": "string",
  "city": "string",
  "state": "string",
  "languageIsoCode": "None",
  "webSiteUrl": "string",
  "isRegistrationComplete": true,
  "isEmailVerified": true,
  "isMobileNumberVerified": true,
  "vCard": "string",
  "logoImage": "string",
  "taxNumber": "string",
  "companyRegistrationNumber": "string",
  "companyRegistrationDate": "string",
  "adminPasscode": "string",
  "logoUrl": "string",
  "hostedPaymentUrl": "string",
  "hostedPaymentOptions": {
    "cardNotPresentMID": 0,
    "isVisaEnabled": true,
    "isMastercardEnabled": true,
    "isAmericanExpressEnabled": true,
    "isDinersEnabled": true,
    "settlementTime": "None"
  },
  "posOptions": {
    "isRefundsEnabled": true,
    "isCancellationsEnabled": true,
    "isPurchaseWithCashbackEnabled": true,
    "isWithdrawalsEnabled": true,
    "isBalanceCheckEnabled": true,
    "isCurrencyConversionEnabled": true,
    "isRcsPaymentEnabled": true,
    "isDebiCheckEnabled": true,
    "isPreAuthorizationEnabled": true,
    "isManualCardEntryEnabled": true,
    "isInvoiceNumberEnabled": true,
    "isPasscodeAlwaysRequired": true,
    "fuelPurchaseMethod": "ByAmount"
  },
  "business": {
    "reference": "00000000-0000-0000-0000-000000000000",
    "parentBusinessReference": "00000000-0000-0000-0000-000000000000",
    "createdDate": "string",
    "yourReference": "string",
    "source": "string",
    "name": "string",
    "emailAddress": "string",
    "mobileNumber": "string",
    "phoneNumber": "string",
    "isEmailVerified": true,
    "isMobileNumberVerified": true,
    "isActive": true
  },
  "addresses": [
    {}
  ],
  "employees": [
    {}
  ],
  "terminals": [
    {}
  ],
  "files": [
    {}
  ],
  "notificationSettings": [
    {}
  ],
  "attributes": [
    {}
  ],
  "bankAccounts": [
    {}
  ],
  "mobileWallets": [
    {}
  ],
  "operatingTimes": [
    {}
  ],
  "devices": [
    {}
  ],
  "qrCodes": [
    {}
  ],
  "assignedProductReferences": [
    "00000000-0000-0000-0000-000000000000"
  ],
  "reference": "00000000-0000-0000-0000-000000000000",
  "userReference": "00000000-0000-0000-0000-000000000000",
  "yourReference": "string",
  "source": "string",
  "name": "string",
  "categoryCode": 0,
  "category": "string",
  "emailAddress": "string",
  "mobileNumber": "string",
  "countryIsoCode": "None",
  "currency": "None",
  "kybStatusSummary": "Unverified",
  "shortCode": 0,
  "isActive": true
}

Responses

Status	Description
200	The request was successful and the merchants details are 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 merchant profile, extending ZGA.Core.Models.Merchants.BasicMerchant with trading details, linked accounts, terminals, employees, addresses, and KYB documentation.

{
  "success": true,
  "result": {
    "createdDate": "string",
    "loginCredentials": {},
    "tradingName": "string",
    "franchiseName": "string",
    "capturedBy": "string",
    "capturedFrom": "string",
    "industry": "None",
    "phoneNumber": "string",
    "notificationEmailAddress": "string",
    "notificationMobileNumber": "string",
    "city": "string",
    "state": "string",
    "languageIsoCode": "None",
    "webSiteUrl": "string",
    "isRegistrationComplete": true,
    "isEmailVerified": true,
    "isMobileNumberVerified": true,
    "vCard": "string",
    "logoImage": "string",
    "taxNumber": "string",
    "companyRegistrationNumber": "string",
    "companyRegistrationDate": "string",
    "adminPasscode": "string",
    "logoUrl": "string",
    "hostedPaymentUrl": "string",
    "hostedPaymentOptions": {},
    "posOptions": {},
    "business": {},
    "addresses": [],
    "employees": [],
    "terminals": [],
    "files": [],
    "notificationSettings": [],
    "attributes": [],
    "bankAccounts": [],
    "mobileWallets": [],
    "operatingTimes": [],
    "devices": [],
    "qrCodes": [],
    "assignedProductReferences": [],
    "reference": "00000000-0000-0000-0000-000000000000",
    "userReference": "00000000-0000-0000-0000-000000000000",
    "yourReference": "string",
    "source": "string",
    "name": "string",
    "categoryCode": 0,
    "category": "string",
    "emailAddress": "string",
    "mobileNumber": "string",
    "countryIsoCode": "None",
    "currency": "None",
    "kybStatusSummary": "Unverified",
    "shortCode": 0,
    "isActive": true
  }
}

Code samples

JavaScript

// @vantagepay/vantagepay
const merchant = await client.merchants.getMerchant()
merchant.tradingName = 'Acme Superstore'
const updated = await client.merchants.updateMerchant(merchant)

.NET

// VantagePay.SDK
var merchant = await client.Merchants.GetMerchantAsync();
merchant!.TradingName = "Acme Superstore";
var updated = await client.Merchants.UpdateMerchantAsync(merchant);

---

Get your merchant information.

GET /v1/merchant

Sample

GET /v1/merchant

Auth: Access token (Bearer).

Responses

Status	Description
200	The request was successful and the merchant 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 merchant profile, extending ZGA.Core.Models.Merchants.BasicMerchant with trading details, linked accounts, terminals, employees, addresses, and KYB documentation.

{
  "success": true,
  "result": {
    "createdDate": "string",
    "loginCredentials": {},
    "tradingName": "string",
    "franchiseName": "string",
    "capturedBy": "string",
    "capturedFrom": "string",
    "industry": "None",
    "phoneNumber": "string",
    "notificationEmailAddress": "string",
    "notificationMobileNumber": "string",
    "city": "string",
    "state": "string",
    "languageIsoCode": "None",
    "webSiteUrl": "string",
    "isRegistrationComplete": true,
    "isEmailVerified": true,
    "isMobileNumberVerified": true,
    "vCard": "string",
    "logoImage": "string",
    "taxNumber": "string",
    "companyRegistrationNumber": "string",
    "companyRegistrationDate": "string",
    "adminPasscode": "string",
    "logoUrl": "string",
    "hostedPaymentUrl": "string",
    "hostedPaymentOptions": {},
    "posOptions": {},
    "business": {},
    "addresses": [],
    "employees": [],
    "terminals": [],
    "files": [],
    "notificationSettings": [],
    "attributes": [],
    "bankAccounts": [],
    "mobileWallets": [],
    "operatingTimes": [],
    "devices": [],
    "qrCodes": [],
    "assignedProductReferences": [],
    "reference": "00000000-0000-0000-0000-000000000000",
    "userReference": "00000000-0000-0000-0000-000000000000",
    "yourReference": "string",
    "source": "string",
    "name": "string",
    "categoryCode": 0,
    "category": "string",
    "emailAddress": "string",
    "mobileNumber": "string",
    "countryIsoCode": "None",
    "currency": "None",
    "kybStatusSummary": "Unverified",
    "shortCode": 0,
    "isActive": true
  }
}

Code samples

JavaScript

// @vantagepay/vantagepay
const merchant = await client.merchants.getMerchant()

.NET

// VantagePay.SDK
var merchant = await client.Merchants.GetMerchantAsync();

---

Retrieves the merchant agreement as an HTML document with merchant-specific information populated.

GET /v1/merchant/agreement

The returned HTML is suitable for direct rendering in a browser and includes merchant-specific details such as name, address, and the current date. The response is cached for 24 hours and is delivered with a content type of 'text/html'.

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.

Code samples

JavaScript

// @vantagepay/vantagepay
const agreementHtml = await client.merchants.getMerchantAgreement()

.NET

// VantagePay.SDK
var agreementHtml = await client.Merchants.GetMerchantAgreementAsync();

---

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/merchant/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 merchant reference.

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.

{
  "success": true
}

Code samples

JavaScript

// @vantagepay/vantagepay
await client.merchants.acceptMerchantAgreement()

.NET

// VantagePay.SDK
await client.Merchants.AcceptMerchantAgreementAsync();

---

Validate a merchant's name against the one on record and return an access token if it matches closely enough.

POST /v1/merchant/validate/name

Auth: Access token (Bearer).

Request body

{}

Responses

Status	Description
200	The request was processed; the response body indicates whether the name was accepted.
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 response returned after verifying a merchant name, including an access token if the name is approved for use.

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

Code samples

JavaScript

// @vantagepay/vantagepay
// On success a restricted token is stored so the caller can create a merchant user.
const matched = await client.merchants.validateMerchantName('Acme Stores')
if (matched) {
  await client.merchants.createUser('cashier01', 'StrongPassword123!')
}

.NET

// VantagePay.SDK
// Validates a merchant name (fuzzy match). 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/merchant/validate/name", content: null);
response.EnsureSuccessStatusCode();

---

Verify a merchant mobile number by sending an OTP request.

POST /v1/merchant/otp/{msisdn}

Auth: Access token (Bearer).

Parameters

Name	In	Required	Description
msisdn	path	Yes	The merchant mobile number to send the OTP to.

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.

{
  "success": true
}

Code samples

JavaScript

// @vantagepay/vantagepay
await client.merchants.verifyMobileNumber('233555666112')

.NET

// VantagePay.SDK
await client.Merchants.VerifyMobileNumberAsync("233555666112");

---

Validate merchant OTP request.

POST /v1/merchant/otp/validate/{msisdn}

Auth: Access token (Bearer).

Parameters

Name	In	Required	Description
msisdn	path	Yes	The mobile number to send the OTP to.

Request body

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

{
  "otpValue": "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 returned after a successful OTP verification, indicating whether a user account exists and providing a short-lived access token if so.

{
  "success": true,
  "result": {
    "userAccountExists": true,
    "accessToken": "string"
  }
}

Code samples

JavaScript

// @vantagepay/vantagepay
const result = await client.merchants.validateOtp('123456', '233555666112')

.NET

// VantagePay.SDK
var result = await client.Merchants.ValidateOtpAsync("123456", "233555666112");