Products Admin

Get all products for a specific merchant.

GET /v1/merchant/product/admin/{merchantReference}

Sample

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

Auth: API key (VantagePayAdminClient).

Parameters

Name	In	Required	Description
merchantReference	path	Yes	A globally unique internal merchant 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.
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

WARNING

The JavaScript SDK does not cover admin APIs - use the .NET SDK.

.NET

var products = await adminClient.Products.GetProductsAsync(Guid.Parse("3fa85f64-5717-4562-b3fc-2c963f66afa6"));

---

Create a new product for a merchant.

POST /v1/merchant/product/admin/{merchantReference}

Auth: API key (VantagePayAdminClient).

Parameters

Name	In	Required	Description
merchantReference	path	Yes	A globally unique internal merchant reference (UUID).

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

WARNING

The JavaScript SDK does not cover admin APIs - use the .NET SDK.

.NET

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

var product = await adminClient.Products.CreateProductAsync(Guid.Parse("3fa85f64-5717-4562-b3fc-2c963f66afa6"), new MerchantProduct
{
    Name = "Airtime Voucher",
    ProductType = ProductType.Airtime,
    Currency = Currency.GHS,
    AmountInCents = 1000,
    IsActive = true,
});

---

Get product catalogs for a specific merchant.

GET /v1/merchant/product/admin/catalog

Auth: API key (VantagePayAdminClient).

Responses

Status	Description
200	The request was successful and a list of product catalogs 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

WARNING

The JavaScript SDK does not cover admin APIs - use the .NET SDK.

.NET

var catalogs = await adminClient.Products.GetProductCatalogsAsync();

---

Get the pool of products that an admin is allowed to assign to any merchant.

GET /v1/merchant/product/admin/assignable

The returned list contains products that are active, non-deleted and not linked to a product catalog. Catalog-sourced products are private to the merchant they were applied to and must never surface in the public assignable pool.

Auth: API key (VantagePayAdminClient).

Responses

Status	Description
200	The request was successful and the assignable products list 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

WARNING

The JavaScript SDK does not cover admin APIs - use the .NET SDK.

.NET

var assignable = await adminClient.Products.GetAssignableProductsAsync();

---

Update an existing product for a merchant.

PUT /v1/merchant/product/admin

Auth: API key (VantagePayAdminClient).

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

WARNING

The JavaScript SDK does not cover admin APIs - use the .NET SDK.

.NET

using VantagePay.Models.Merchants.Products;

var updated = await adminClient.Products.UpdateProductAsync(product); // product: MerchantProduct with Reference set

---

Delete a product for a merchant.

DELETE /v1/merchant/product/admin/{productReference}

Auth: API key (VantagePayAdminClient).

Parameters

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

Responses

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

WARNING

The JavaScript SDK does not cover admin APIs - use the .NET SDK.

.NET

await adminClient.Products.DeleteProductAsync(Guid.Parse("5f4e3d2c-1b0a-4988-8765-1234567890ab"));

---

Apply a preconfigured product catalog to a merchant.

POST /v1/merchant/product/admin/catalog/apply/{merchantReference}/{productCatalogReference}

Auth: API key (VantagePayAdminClient).

Parameters

Name	In	Required	Description
merchantReference	path	Yes	A globally unique internal merchant reference (UUID).
productCatalogReference	path	Yes	A globally unique internal product catalog reference (UUID).

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.
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.

{
  "success": true
}

Code samples

WARNING

The JavaScript SDK does not cover admin APIs - use the .NET SDK.

.NET

await adminClient.Products.ApplyProductCatalogAsync(Guid.Parse("3fa85f64-5717-4562-b3fc-2c963f66afa6"), Guid.Parse("aa11bb22-cc33-dd44-ee55-ff6677889900"));