Status, Receipts & Interactive

Send an SMS receipt for the recently completed payment.

POST /v1/notification/sms/{paymentReference}

Auth: Access token (Bearer).

Parameters

Name	In	Required	Description
paymentReference	path	Yes	A globally unique internal payment reference (UUID) that is returned when submitting a payment request.

Request body

Field	Type	Required	Description
toNumber	string?	No	The international mobile number (MSISDN) to which the SMS notification is sent.
receiptType	Consumer, Merchant	No	Determines whether the SMS is formatted as a consumer receipt or a merchant receipt. Defaults to ZGA.Core.Models.Payments.ReceiptType.Consumer.

{
  "toNumber": "string",
  "receiptType": "Consumer"
}

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

JavaScript

// @vantagepay/vantagepay
await client.payments.sendSmsPaymentNotification('c7b8a9d0-1234-4567-89ab-cdef01234567', '233555666112')

.NET

// VantagePay.SDK
await client.Payments.SendSmsNotificationAsync("c7b8a9d0-1234-4567-89ab-cdef01234567", "233555666112");

---

Send an email receipt for the recently completed payment.

POST /v1/notification/email/{paymentReference}

Auth: Access token (Bearer).

Parameters

Name	In	Required	Description
paymentReference	path	Yes	A globally unique internal payment reference (UUID) that is returned when submitting a payment request.

Request body

Field	Type	Required	Description
toEmailAddress	string?	No	The email address to which the payment notification or receipt is sent.
templateName	string?	No	Optional name of the notification template to use when rendering the email. When null, the default template for the given ZGA.Core.Models.Payments.Requests.EmailNotificationRequest.ReceiptType is applied.
receiptType	Consumer, Merchant	No	Determines whether the email is formatted as a consumer receipt or a merchant receipt. Defaults to ZGA.Core.Models.Payments.ReceiptType.Consumer.

{
  "toEmailAddress": "string",
  "templateName": "string",
  "receiptType": "Consumer"
}

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

JavaScript

// @vantagepay/vantagepay
await client.payments.sendEmailPaymentNotification('c7b8a9d0-1234-4567-89ab-cdef01234567', 'customer@example.com')

.NET

// VantagePay.SDK
await client.Payments.SendEmailNotificationAsync("c7b8a9d0-1234-4567-89ab-cdef01234567", "customer@example.com");

---

Check the status and progress of a payment based on a payment reference.

GET /v1/pay/status/{paymentReference}

This endpoint should be polled at an interval of at least one second to avoid receiving cached results.

Sample

GET /v1/pay/status/9fd4dff4-5edc-4b28-b593-dc76739a6171

Auth: Access token (Bearer).

Parameters

Name	In	Required	Description
paymentReference	path	Yes	A globally unique internal payment reference (UUID) that is returned when submitting a payment request.

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.
result	object	No	A model to hold the details of a payment request, including the current status of all associated transactions and the overall payment itself.

{
  "success": true,
  "result": {
    "isComplete": true,
    "percentageComplete": 0,
    "paymentStartedDate": "string",
    "paymentCompletedDate": "string",
    "yourReference": "string",
    "description": "string",
    "paymentReference": "00000000-0000-0000-0000-000000000000",
    "shortPaymentReference": "string",
    "splitReference": "00000000-0000-0000-0000-000000000000",
    "verificationCode": "string",
    "channel": "Unknown",
    "consumerReference": "00000000-0000-0000-0000-000000000000",
    "notificationFileReference": "00000000-0000-0000-0000-000000000000",
    "consumer": {},
    "paymentSources": {},
    "paymentDestinations": {},
    "amountTotals": {}
  }
}

Code samples

JavaScript

// @vantagepay/vantagepay
const status = await client.payments.paymentStatusCheck('c7b8a9d0-1234-4567-89ab-cdef01234567')

.NET

// VantagePay.SDK
var status = await client.Payments.PaymentStatusCheckAsync(Guid.Parse("c7b8a9d0-1234-4567-89ab-cdef01234567"));

---

Check the status and progress of a QR Code payment based on a bill reference.

GET /v1/pay/status/qrpayment/{billReference}

This endpoint should be polled at an interval of at least one second to avoid receiving cached results.

Sample

GET /v1/pay/qrpayment/status/ABC123456

Auth: Access token (Bearer).

Parameters

Name	In	Required	Description
billReference	path	Yes	The bill reference associated with the QR Code payment.

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.
result	object	No	A model to hold the details of a payment request, including the current status of all associated transactions and the overall payment itself.

{
  "success": true,
  "result": {
    "isComplete": true,
    "percentageComplete": 0,
    "paymentStartedDate": "string",
    "paymentCompletedDate": "string",
    "yourReference": "string",
    "description": "string",
    "paymentReference": "00000000-0000-0000-0000-000000000000",
    "shortPaymentReference": "string",
    "splitReference": "00000000-0000-0000-0000-000000000000",
    "verificationCode": "string",
    "channel": "Unknown",
    "consumerReference": "00000000-0000-0000-0000-000000000000",
    "notificationFileReference": "00000000-0000-0000-0000-000000000000",
    "consumer": {},
    "paymentSources": {},
    "paymentDestinations": {},
    "amountTotals": {}
  }
}

Code samples

JavaScript

// @vantagepay/vantagepay
// Checks the status of a bill/QR payment.
// Not wrapped by the JavaScript SDK - call the endpoint directly with the active token.
const response = await fetch(baseUrl + '/v1/pay/status/qrpayment/' + billReference, {
  method: 'GET',
  headers: { Authorization: 'Bearer ' + ApiTokens.accessToken },
})
const result = await response.json()

.NET

// VantagePay.SDK
// Checks the status of a bill/QR payment.
// 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.GetAsync($"/v1/pay/status/qrpayment/{billReference}");
response.EnsureSuccessStatusCode();

---

Get detailed payment information for generating receipts.

GET /v1/pay/receipt/{paymentReference}

Auth: Access token (Bearer).

Parameters

Name	In	Required	Description
paymentReference	path	Yes	A globally unique internal payment reference (UUID) that is returned when submitting a payment request.

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.
result	object	No	A payment status response that also includes the line items associated with the transaction, suitable for generating receipts.

{
  "success": true,
  "result": {
    "lineItems": [],
    "isComplete": true,
    "percentageComplete": 0,
    "paymentStartedDate": "string",
    "paymentCompletedDate": "string",
    "yourReference": "string",
    "description": "string",
    "paymentReference": "00000000-0000-0000-0000-000000000000",
    "shortPaymentReference": "string",
    "splitReference": "00000000-0000-0000-0000-000000000000",
    "verificationCode": "string",
    "channel": "Unknown",
    "consumerReference": "00000000-0000-0000-0000-000000000000",
    "notificationFileReference": "00000000-0000-0000-0000-000000000000",
    "consumer": {},
    "paymentSources": {},
    "paymentDestinations": {},
    "amountTotals": {}
  }
}

Code samples

JavaScript

// @vantagepay/vantagepay
const receipt = await client.payments.paymentReceipt('c7b8a9d0-1234-4567-89ab-cdef01234567')

.NET

// VantagePay.SDK
var receipt = await client.Payments.GetPaymentReceiptAsync(Guid.Parse("c7b8a9d0-1234-4567-89ab-cdef01234567"));

---

Submit a PIN or voucher code to unblock a transaction that is in a 'requires PIN' state.

POST /v1/transaction/pin/{transactionReference}

Sample

POST /v1/transaction/pin/1dc67f55-f445-481d-8c89-471b2082dd06
{
  "pin": "123456"
}

Auth: Access token (Bearer).

Parameters

Name	In	Required	Description
transactionReference	path	Yes	A globally unique internal transaction reference (UUID).

Request body

Field	Type	Required	Description
pin	string?	No	The PIN or voucher code entered by the end user.

{
  "pin": "string"
}

Responses

Status	Description
202	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

JavaScript

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

client.events.subscribe(OnRequiresPin, async (_, data) => {
  await client.payments.submitPinCode(data.transactionReference, '1234')
})

.NET

// VantagePay.SDK
client.Payments.OnRequiresPin = data =>
{
    _ = client.Payments.SubmitPinCodeAsync(data.TransactionReference, "1234");
};

---

Submit a transaction confirmation to unblock a transaction that is in a 'requires confirmation' state.

POST /v1/transaction/confirm/{transactionReference}

Sample

POST /v1/transaction/confirm/1ae12fcf-a32b-45b8-a9af-4fef6b684567
{
  "confirm": false
}

Auth: Access token (Bearer).

Parameters

Name	In	Required	Description
transactionReference	path	Yes	A globally unique internal transaction reference (UUID).

Request body

Field	Type	Required	Description
confirm	boolean	No	true if the user has confirmed the transaction; false to cancel it.

{
  "confirm": true
}

Responses

Status	Description
202	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

JavaScript

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

client.events.subscribe(OnRequiresConfirmation, async (_, data) => {
  await client.payments.submitConfirmation(data.transactionReference, true)
})

.NET

// VantagePay.SDK
client.Payments.OnRequiresConfirmation = data =>
{
    _ = client.Payments.SubmitConfirmationAsync(data.TransactionReference, confirm: true);
};

---

Submit address details to unblock a transaction that is in a 'requires address' state.

POST /v1/transaction/address/{transactionReference}

Sample

POST /v1/transaction/address/1ae12fcf-a32b-45b8-a9af-4fef6b684567
{
  "addressType": "POST",
  "addressLine1": "No. 20 Bissau Avenue",
  "addressLine2": "West Legon",
  "addressLine3": "",
  "postalCode": "00233",
  "countryIsoCode": "GHA",
  "city": "Accra",
  "state": "Accra"
}

Auth: Access token (Bearer).

Parameters

Name	In	Required	Description
transactionReference	path	Yes	A globally unique internal transaction reference (UUID).

Request body

Field	Type	Required	Description
reference	string?	No	The system-assigned unique reference (UUID) for this address.
yourReference	string?	No	An optional external reference from the caller's system that identifies this address.
addressType	MAIN, POST, BILL, SHIP	No	The classification of this address (e.g. billing, shipping, postal, main).
addressLine1	string	Yes	The first line of the street address.
addressLine2	string?	No	The second line of the street address, if applicable.
addressLine3	string?	No	The third line of the street address, if applicable.
postalCode	string?	No	The postal or ZIP code for this address.
countryIsoCode	one of 248 values (e.g. None, AFG, ALB, ...)	Yes	The ISO 3166-1 alpha-3 country code of the country where this address is located.
city	string	Yes	The city or town of this address.
state	string?	No	The state, province, or region of this address, if applicable.
location	object	No	A geographic coordinate with an optional time zone and description. Used to pin an address or entity on a map.
description	string?	No	A free-text description or label for this address (e.g. "Head Office", "Warehouse").
formatted	string?	No	A single-line formatted string representation of the full address.
isActive	boolean	No	true if this address record is currently active.

{
  "reference": "00000000-0000-0000-0000-000000000000",
  "yourReference": "string",
  "addressType": "MAIN",
  "addressLine1": "string",
  "addressLine2": "string",
  "addressLine3": "string",
  "postalCode": "string",
  "countryIsoCode": "None",
  "city": "string",
  "state": "string",
  "location": {
    "latitude": 0,
    "longitude": 0,
    "timeZone": "string",
    "description": "string"
  },
  "description": "string",
  "formatted": "string",
  "isActive": true
}

Responses

Status	Description
202	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

JavaScript

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

client.events.subscribe(OnRequiresAddress, async (_, data) => {
  await client.payments.submitAddress(data.transactionReference, {
    addressType: 'BILL',
    addressLine1: '10 Main Road',
    city: 'Johannesburg',
    countryIsoCode: 'ZAF',
    postalCode: '2196',
  })
})

.NET

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

client.Payments.OnRequiresAddress = data =>
{
    _ = client.Payments.SubmitAddressAsync(data.TransactionReference, new Address
    {
        AddressType = AddressType.Billing,
        AddressLine1 = "10 Main Road",
        City = "Johannesburg",
        CountryIsoCode = Country.ZAF,
        PostalCode = "2196",
    });
};