Products

Get a list of all active products and the type and merchant they are associated with.

GET /v1/merchant/product/lookup

Sample

GET /v1/merchant/product/lookup

Auth: Access token (Bearer).

Responses

Status	Description
200	The request was successful and a list of products was retrieved.
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	array<object>?	No	Gets the response payload.

{
  "success": true,
  "result": [
    {}
  ]
}

Code samples

JavaScript

// @vantagepay/vantagepay
const catalog = await client.merchants.getAllProducts()

.NET

// VantagePay.SDK
var catalog = await client.Products.GetAllProductsAsync();

---

Get a list of all active products and which products are associated with which merchant.

GET /v1/merchant/product/details/{productReference}

Auth: Access token (Bearer).

Parameters

Name	In	Required	Description
productReference	path	Yes	A globally unique internal product reference (UUID).

Responses

Status	Description
200	The request was successful and a list of products was retrieved.
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	A billable product or service that a merchant offers, with pricing, currency, and custom field configuration.

{
  "success": true,
  "result": {
    "reference": "00000000-0000-0000-0000-000000000000",
    "createdDate": "string",
    "lastUpdatedDate": "string",
    "yourReference": "string",
    "name": "string",
    "description": "string",
    "unitLabel": "string",
    "productType": "Airtime",
    "currency": "None",
    "amountInCents": 0,
    "maximumAmountInCents": 0,
    "futureAmountInCents": 0,
    "futureAmountEffectiveFromDate": "string",
    "fullAmountRequired": true,
    "quantityRequired": true,
    "isActive": true,
    "isAssigned": true,
    "iconUrl": "string",
    "fields": []
  }
}

Code samples

JavaScript

// @vantagepay/vantagepay
const product = await client.merchants.getProductDetails('5f4e3d2c-1b0a-4988-8765-1234567890ab')

.NET

// VantagePay.SDK
var product = await client.Products.GetProductDetailsAsync(Guid.Parse("5f4e3d2c-1b0a-4988-8765-1234567890ab"));

---

Get all products for a specific merchant.

GET /v1/merchant/product

Sample

GET /v1/merchant/product/merchant/25441723-1A78-4345-A667-2C462DA525F1

Auth: Access token (Bearer).

Responses

Status	Description
200	The request was successful and a list of products was retrieved.
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	array<object>?	No	Gets the response payload.

{
  "success": true,
  "result": [
    {}
  ]
}

Code samples

JavaScript

// @vantagepay/vantagepay
const products = await client.merchants.getProducts()

.NET

// VantagePay.SDK
var products = await client.Products.GetProductsAsync();

---

Create a new product for a merchant.

POST /v1/merchant/product

Auth: Access token (Bearer).

Request body

Field	Type	Required	Description
reference	string?	No	The system-assigned unique reference (UUID) for this product.
createdDate	string	No	The UTC date and time this product record was created.
lastUpdatedDate	string?	No	The UTC date and time this product was last updated, or null if never modified after creation.
yourReference	string?	No	An optional external reference from the caller's system for this product.
name	string	Yes	The display name of the product (e.g. Petrol 95).
description	string?	No	An optional human-readable description of the product.
unitLabel	string?	No	The label for the unit of measure shown to the consumer (e.g. litre, unit).
productType	one of 24 values (e.g. Airtime, Internet, Television, ...)	Yes	The product category (e.g. ZGA.Core.Models.Lookups.ProductType.Fuel, ZGA.Core.Models.Lookups.ProductType.Airtime).
currency	one of 106 values (e.g. None, AFN, ALL, ...)	No	The currency in which this product is priced.
amountInCents	integer?	No	The fixed price of the product in cents. When a future price is configured and its effective date has passed, returns ZGA.Core.Models.Merchants.MerchantProduct.FutureAmountInCents instead.
maximumAmountInCents	integer?	No	The maximum amount in cents that can be paid for this product, used when the amount is consumer-entered rather than fixed.
futureAmountInCents	integer?	No	A future price in cents that will replace ZGA.Core.Models.Merchants.MerchantProduct.AmountInCents once ZGA.Core.Models.Merchants.MerchantProduct.FutureAmountEffectiveFromDate is reached.
futureAmountEffectiveFromDate	string?	No	The date and time from which the ZGA.Core.Models.Merchants.MerchantProduct.FutureAmountInCents price becomes effective.
fullAmountRequired	boolean	No	true if the consumer must pay the exact product amount and cannot enter a custom amount.
quantityRequired	boolean	No	true if the consumer must specify a quantity when purchasing this product.
isActive	boolean	No	true if this product is visible and purchasable; otherwise false.
isAssigned	boolean	No	Indicates whether the product was assigned to the authenticated merchant (true) because it was assigned from another merchant's catalog, or owned directly by the authenticated merchant (false). Populated by the server on list responses that return a merchant's accessible products so clients can partition results into "my products" vs "other/assigned products" without needing to inspect ZGA.Core.Models.Merchants.MerchantProduct.MerchantReference.
iconUrl	string?	No	A URL pointing to the product's icon image, or null if no icon is configured.
fields	array<object>?	No	The custom input fields that the consumer must populate when purchasing this product (e.g. account number, meter number).

{
  "reference": "00000000-0000-0000-0000-000000000000",
  "createdDate": "string",
  "lastUpdatedDate": "string",
  "yourReference": "string",
  "name": "string",
  "description": "string",
  "unitLabel": "string",
  "productType": "Airtime",
  "currency": "None",
  "amountInCents": 0,
  "maximumAmountInCents": 0,
  "futureAmountInCents": 0,
  "futureAmountEffectiveFromDate": "string",
  "fullAmountRequired": true,
  "quantityRequired": true,
  "isActive": true,
  "isAssigned": true,
  "iconUrl": "string",
  "fields": [
    {}
  ]
}

Responses

Status	Description
200	The request was successful and the product was created.
400	The request was invalid or the product could not be created.
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 billable product or service that a merchant offers, with pricing, currency, and custom field configuration.

{
  "success": true,
  "result": {
    "reference": "00000000-0000-0000-0000-000000000000",
    "createdDate": "string",
    "lastUpdatedDate": "string",
    "yourReference": "string",
    "name": "string",
    "description": "string",
    "unitLabel": "string",
    "productType": "Airtime",
    "currency": "None",
    "amountInCents": 0,
    "maximumAmountInCents": 0,
    "futureAmountInCents": 0,
    "futureAmountEffectiveFromDate": "string",
    "fullAmountRequired": true,
    "quantityRequired": true,
    "isActive": true,
    "isAssigned": true,
    "iconUrl": "string",
    "fields": []
  }
}

Code samples

JavaScript

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

const product = await client.merchants.createProduct({
  name: 'Airtime Voucher',
  productType: 'Airtime',
  currency: 'GHS',
  amountInCents: 1000,
  fullAmountRequired: true,
  quantityRequired: false,
  isActive: true,
})

.NET

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

var product = await client.Products.CreateProductAsync(new MerchantProduct
{
    Name = "Airtime Voucher",
    ProductType = ProductType.Airtime,
    Currency = Currency.GHS,
    AmountInCents = 1000,
    FullAmountRequired = true,
    IsActive = true,
});

---

Update an existing product for a merchant.

PUT /v1/merchant/product

Auth: Access token (Bearer).

Request body

Field	Type	Required	Description
reference	string?	No	The system-assigned unique reference (UUID) for this product.
createdDate	string	No	The UTC date and time this product record was created.
lastUpdatedDate	string?	No	The UTC date and time this product was last updated, or null if never modified after creation.
yourReference	string?	No	An optional external reference from the caller's system for this product.
name	string	Yes	The display name of the product (e.g. Petrol 95).
description	string?	No	An optional human-readable description of the product.
unitLabel	string?	No	The label for the unit of measure shown to the consumer (e.g. litre, unit).
productType	one of 24 values (e.g. Airtime, Internet, Television, ...)	Yes	The product category (e.g. ZGA.Core.Models.Lookups.ProductType.Fuel, ZGA.Core.Models.Lookups.ProductType.Airtime).
currency	one of 106 values (e.g. None, AFN, ALL, ...)	No	The currency in which this product is priced.
amountInCents	integer?	No	The fixed price of the product in cents. When a future price is configured and its effective date has passed, returns ZGA.Core.Models.Merchants.MerchantProduct.FutureAmountInCents instead.
maximumAmountInCents	integer?	No	The maximum amount in cents that can be paid for this product, used when the amount is consumer-entered rather than fixed.
futureAmountInCents	integer?	No	A future price in cents that will replace ZGA.Core.Models.Merchants.MerchantProduct.AmountInCents once ZGA.Core.Models.Merchants.MerchantProduct.FutureAmountEffectiveFromDate is reached.
futureAmountEffectiveFromDate	string?	No	The date and time from which the ZGA.Core.Models.Merchants.MerchantProduct.FutureAmountInCents price becomes effective.
fullAmountRequired	boolean	No	true if the consumer must pay the exact product amount and cannot enter a custom amount.
quantityRequired	boolean	No	true if the consumer must specify a quantity when purchasing this product.
isActive	boolean	No	true if this product is visible and purchasable; otherwise false.
isAssigned	boolean	No	Indicates whether the product was assigned to the authenticated merchant (true) because it was assigned from another merchant's catalog, or owned directly by the authenticated merchant (false). Populated by the server on list responses that return a merchant's accessible products so clients can partition results into "my products" vs "other/assigned products" without needing to inspect ZGA.Core.Models.Merchants.MerchantProduct.MerchantReference.
iconUrl	string?	No	A URL pointing to the product's icon image, or null if no icon is configured.
fields	array<object>?	No	The custom input fields that the consumer must populate when purchasing this product (e.g. account number, meter number).

{
  "reference": "00000000-0000-0000-0000-000000000000",
  "createdDate": "string",
  "lastUpdatedDate": "string",
  "yourReference": "string",
  "name": "string",
  "description": "string",
  "unitLabel": "string",
  "productType": "Airtime",
  "currency": "None",
  "amountInCents": 0,
  "maximumAmountInCents": 0,
  "futureAmountInCents": 0,
  "futureAmountEffectiveFromDate": "string",
  "fullAmountRequired": true,
  "quantityRequired": true,
  "isActive": true,
  "isAssigned": true,
  "iconUrl": "string",
  "fields": [
    {}
  ]
}

Responses

Status	Description
200	The request was successful and the product was updated.
400	The request was invalid or the product could not be updated.
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 product was not found.
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 billable product or service that a merchant offers, with pricing, currency, and custom field configuration.

{
  "success": true,
  "result": {
    "reference": "00000000-0000-0000-0000-000000000000",
    "createdDate": "string",
    "lastUpdatedDate": "string",
    "yourReference": "string",
    "name": "string",
    "description": "string",
    "unitLabel": "string",
    "productType": "Airtime",
    "currency": "None",
    "amountInCents": 0,
    "maximumAmountInCents": 0,
    "futureAmountInCents": 0,
    "futureAmountEffectiveFromDate": "string",
    "fullAmountRequired": true,
    "quantityRequired": true,
    "isActive": true,
    "isAssigned": true,
    "iconUrl": "string",
    "fields": []
  }
}

Code samples

JavaScript

// @vantagepay/vantagepay
const product = await client.merchants.getProductDetails('5f4e3d2c-1b0a-4988-8765-1234567890ab')
product.amountInCents = 1500
const updated = await client.merchants.updateProduct(product)

.NET

// VantagePay.SDK
var product = await client.Products.GetProductDetailsAsync(Guid.Parse("5f4e3d2c-1b0a-4988-8765-1234567890ab"));
product!.AmountInCents = 1500;
var updated = await client.Products.UpdateProductAsync(product);

---

Get all products the merchant can use - their own products plus products that have been assigned to them from other merchants.

GET /v1/merchant/product/accessible

Sample

GET /v1/merchant/product/accessible

Auth: Access token (Bearer).

Responses

Status	Description
200	The request was successful and a list of accessible products was retrieved.
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	array<object>?	No	Gets the response payload.

{
  "success": true,
  "result": [
    {}
  ]
}

Code samples

JavaScript

// @vantagepay/vantagepay
const accessible = await client.merchants.getAccessibleProducts()

.NET

// VantagePay.SDK
var accessible = await client.Products.GetAccessibleProductsAsync();

---

Delete a product for a merchant.

DELETE /v1/merchant/product/{productReference}

Auth: Access token (Bearer).

Parameters

Name	In	Required	Description
productReference	path	Yes	A globally unique internal product reference (UUID).

Responses

Status	Description
204	The request was successful and the product 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 product was not found.
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.deleteProduct('5f4e3d2c-1b0a-4988-8765-1234567890ab')

.NET

// VantagePay.SDK
await client.Products.DeleteProductAsync(Guid.Parse("5f4e3d2c-1b0a-4988-8765-1234567890ab"));