VantagePay Documentation

Initiation & Scheduling ​

Get merchant hosted payment form. ​

GET /v1/merchant/payment/form/{terminalOrMerchantOrQrCodeReference}

Sample

json
GET /v1/merchant/payment/form/25441723-1A78-4345-A667-2C462DA525F1?amount=100.50&currency=GHS

Auth: Access token (Bearer).

Parameters

NameInRequiredDescription
terminalOrMerchantOrQrCodeReferencepathYesA globally unique terminal reference (UUID) or globally unique merchant reference (UUID) or globally unique QR code reference (UUID).
amountqueryNoThe amount (in cents, no decimal points) requested for payment.
currencyqueryNoThe three character ISO code for the currency of the payment.
redirectUrlqueryNoOptional URL to redirect to when the payment is complete.
showQrCodequeryNoOptionally show the V2 EMV QR Code to scan for payment.
timestampqueryNoOptional timestamp from the initiating client.
templateNamequeryNoOptional name of the template file to use instead of the partner specific one.
notificationEmailTemplateNamequeryNoOptional name of the notification email template file to use instead of the partner default.
optionsqueryNoOptional set of options that the client can parse and change the UI.

Responses

StatusDescription
200The request was successful and the merchant payment form content was returned.
400The request failed validation, the error object will contain further information.
404The request was successful but does not return any results.
422The request payload is invalid, the error object will contain further information.
429Too many requests are being sent concurrently or rate limiting has taken effect.
500An unexpected error occurred, the error object will contain further information.

Response body

json
"string"

Code samples ​

ts
// @vantagepay/vantagepay
// A hosted (browser) payment form URL - open it directly rather than calling it as an API.
const url = baseUrl + '/v1/merchant/payment/form/' + terminalOrMerchantOrQrCodeReference
window.open(url)
csharp
// VantagePay.SDK
// A hosted (browser) payment form endpoint - navigate to the URL rather than calling it as an API.
var url = $"https://sandbox-api.vantagepay.dev/v1/merchant/payment/form/{terminalOrMerchantOrQrCodeReference}";

Get merchant offline hosted payment form. ​

GET /v1/merchant/payment/form/offline

Auth: Access token (Bearer).

Parameters

NameInRequiredDescription
xqueryNoA pipe-delimited set of values in the following order: ClientTimestamp

Responses

StatusDescription
200The request was successful and the merchant payment form content was returned.
400The request failed validation, the error object will contain further information.
404The request was successful but does not return any results.
422The request payload is invalid, the error object will contain further information.
429Too many requests are being sent concurrently or rate limiting has taken effect.
500An unexpected error occurred, the error object will contain further information.

Response body

json
"string"

Code samples ​

ts
// @vantagepay/vantagepay
// Build the offline hosted payment-form URL for a scanned QR code.
const url = client.payments.getOfflinePaymentFormUrl(Date.now(), merchantId, terminalId, batchNumber, options)
csharp
// VantagePay.SDK
// Build the offline hosted payment-form URL for a scanned QR code.
var url = client.Payments.GetOfflinePaymentFormUrl(timestamp, merchantId, terminalId, options);

Initiate a payment by providing a payment request that contains the details of where to source funds from and where to transfer funds to. ​

POST /v1/pay

Sample - Pay into a Bank Account from a Mobile Wallet - Use required fields only

json
POST /v1/pay
{   
  "paymentSources": {
    "mobileWallets": [
      {
        "mobileWalletOperator": "MTN",
        "msisdn": "233111222333",
        "amountInCents": 133,
        "currency": "GHS"
      }
    ]
  },
  "paymentDestinations":  {
    "bankAccounts": [
      {
        "accountNumber": "111222333",
        "bank": "ABG",
        "amountInCents": 133,
        "currency": "GHS"
      }
    ]
  }          
}

Sample - Scan a QR Code and pay a Merchant from a Mobile Wallet

json
POST /v1/pay
{
  "channel": 1,
  "yourReference": "{{$guid}}",
  "description": "Sample Payment",
  "consumer": {    
    "firstName": "John",
    "lastName": "Wick",
    "emailAddress": "demo@vantagepay.com",
    "mobileNumber": "233111222333",
    "countryIsoCode": "GHA"
  },
  "paymentSources": {
    "mobileWallets": [
      {
        "mobileWalletOperator": "MTN",
        "msisdn": "233111222333",
        "amountInCents": 133,
        "currency": "GHS"
      }
    ]
  },
  "paymentDestinations": {
    "qrCodes": [
        {
          "qrCode":"00020101021251510007V2EmvQR01368e3b8880-3f6c-48e6-b0fc-561ae9d9f0d502164957030013982287520459935802GH5914AllanVisaTest26005Accra61052302154041.00530393662360108202110060506ZGA-560710Terminal 163043E24",
           "amountInCents": 133,
           "currency": "GHS"
        }
      ]
  },
  "location": {
    "longitude": -73.899020,
    "latitude": 40.654170
  },
  "paymentStatusWebhook": {
    "callbackUrl": "https://your.callback.endpoint",
    "onPaymentCompleteOnly": true
  }

Sample - Pay a Merchant (Delayed Settlement) from a Credit Card

json
POST /v1/pay
{
  "channel": 1,
  "yourReference": "{{$guid}}",
  "description": "Sample Payment",
  "consumer": {    
    "firstName": "John",
    "lastName": "Wick",
    "emailAddress": "demo@vantagepay.com",
    "mobileNumber": "233111222333",
    "countryIsoCode": "GHA"
  },
  "paymentSources": {
    "cards": [
      {
        "amountInCents": 133,
        "currency": "GHS",
        "nameOnCard": "John Wick",
        "cardNumber": "5200000000000114",
        "cvv": "123",
        "expiryMonth": "09",
        "expiryYear": "2022",
        "cardHolder": {
          "firstName": "John",
          "lastName": "Wick",
          "emailAddress": "demo@vantagepay.com",
          "phoneNumber": "233111222333",
          "countryIsoCode": "GHA"
        },
        "billingAddress": {
          "addressLine1": "No. 23 Bissau Avenue",
          "addressLine2": "Accra",
          "postalCode": "00233",
          "city": "Accra",
          "state": "",
          "countryIsoCode": "GHA"
        }
      }
    ]
  },
  "paymentDestinations": {
    "merchants": [
      {
        "amountInCents": 133,
        "currency": "GHS",
        "merchantReference": "{{$guid}}",
        "merchantSource": "ZGA"                
      }
    ]
  },
  "location": {
    "longitude": -73.899020,
    "latitude": 40.654170
  },
  "paymentStatusWebhook": {
    "callbackUrl": "https://your.callback.endpoint",
    "onPaymentCompleteOnly": true
  }
}

Sample - Pay into a Bank Account from a Mobile Wallet

json
POST /v1/pay
{
  "channel": 1,
  "yourReference": "{{$guid}}",
  "description": "Sample Payment",
  "consumer": {    
    "firstName": "John",
    "lastName": "Wick",
    "emailAddress": "demo@vantagepay.com",
    "mobileNumber": "233111222333",
    "countryIsoCode": "GHA"
  },
  "paymentSources": {
    "mobileWallets": [
      {
        "mobileWalletOperator": "MTN",
        "msisdn": "233111222333",
        "amountInCents": 133,
        "currency": "GHS"
      }
    ]
  },
  "paymentDestinations":  {
    "bankAccounts": [
      {
        "accountNumber": "111222333",
        "bank": "ABG",
        "amountInCents": 133,
        "currency": "GHS"
      }
    ]
  },
  "location": {
    "longitude": -73.899020,
    "latitude": 40.654170
  },
  "paymentStatusWebhook": {
    "callbackUrl": "https://your.callback.endpoint",
    "onPaymentCompleteOnly": true
  }
}

Sample - Scan a QR Code and pay a Merchant from a Bank Account

json
POST /v1/pay
{
  "channel": 1,
  "yourReference": "{{$guid}}",
  "description": "Sample Payment",
  "consumer": {    
    "firstName": "John",
    "lastName": "Wick",
    "emailAddress": "demo@vantagepay.com",
    "mobileNumber": "233111222333",
    "countryIsoCode": "GHA"
  },
  "paymentSources": {
    "bankAccounts":[
      {
        "amountInCents": 133,
        "currency": "GHS",
        "bank": "FBL",
        "accountNumber": "0011223344",                
      }
    ]
  },
  "paymentDestinations": {
    "qrCodes": [
      {
        "qrCode":"00020101021251510007V2EmvQR01368e3b8880-3f6c-48e6-b0fc-561ae9d9f0d502164957030013982287520459935802GH5914AllanVisaTest26005Accra61052302154041.00530393662360108202110060506ZGA-560710Terminal 163043E24",
          "amountInCents": 133,
          "currency": "GHS"
      }
    ]
  },
  "location": {
    "longitude": -73.899020,
    "latitude": 40.654170
  },
  "paymentStatusWebhook": {
    "callbackUrl": "https://your.callback.endpoint",
    "onPaymentCompleteOnly": true
  }
}

Sample - Pay into a Bank Account from a Credit Card using mandatory Credit Card details only

json
POST /v1/pay
{
  "channel": 1,
  "yourReference": "{{$guid}}",
  "description": "Sample Payment",
  "consumer": {    
    "firstName": "John",
    "lastName": "Wick",
    "emailAddress": "demo@vantagepay.com",
    "mobileNumber": "233111222333",
    "countryIsoCode": "GHA"
  },
  "paymentSources": {
    "cards": [
      {
        "amountInCents": 133,
        "currency": "GHS",
        "nameOnCard": "John Wick",
        "cardNumber": "5200000000000114",
        "cvv": "123",
        "expiryMonth": "09",
        "expiryYear": "2022"
      }
    ]
  },
  "paymentDestinations":  {
    "bankAccounts": [
      {
        "accountNumber": "111222333",
        "bank": "ABG",
        "amountInCents": 133,
        "currency": "GHS"
      }
    ]
  },
  "location": {
    "longitude": -73.899020,
    "latitude": 40.654170
  },
  "paymentStatusWebhook": {
    "callbackUrl": "https://your.callback.endpoint",
    "onPaymentCompleteOnly": true
  }
}

Sample - Pay a Mobile Wallet from another Mobile Wallet

json
POST /v1/pay
{
  "channel": 1,
  "yourReference": "{{$guid}}",
  "description": "Sample Payment",
  "consumer": {    
    "firstName": "John",
    "lastName": "Wick",
    "emailAddress": "demo@vantagepay.com",
    "mobileNumber": "233111222333",
    "countryIsoCode": "GHA"
  },
  "paymentSources": {
    "mobileWallets": [
      {
        "amountInCents": 133,
        "msisdn": "233111222333",
        "mobileWalletOperator": "MTN",
        "currency": "GHS"
      }
    ]
  },
  "paymentDestinations":  {
    "mobileWallets": [
      {              
        "amountInCents": 133,
        "msisdn": "233444555666",
        "mobileWalletOperator": "VDF",
        "currency": "GHS"                
      }
    ]   
  },
  "location": {
    "longitude": -73.899020,
    "latitude": 40.654170
  },
  "paymentStatusWebhook": {
    "callbackUrl": "https://your.callback.endpoint",
    "onPaymentCompleteOnly": true
  }
}

Sample - Pay a Bill from a Mobile Wallet

json
{
  "channel": 1,
  "yourReference": "{{$guid}}",
  "description": "Sample Payment",
  "consumer": {    
    "firstName": "John",
    "lastName": "Wick",
    "emailAddress": "demo@vantagepay.com",
    "mobileNumber": "233111222333",
    "countryIsoCode": "GHA",
    "addresses": [
      {
        "addressType": "BILL",
        "addressLine1": "No. 23 Bissau Avenue",
        "addressLine2": "East Legon",
        "postalCode": "00233",
        "city": "Accra",
        "state": "Fake State",
        "countryIsoCode": "GHA"
      }
    ]
  },
  "paymentSources": {
    "mobileWallets": [
      {
        "amountInCents": 133,
        "currency": "GHS",
        "msisdn": "233123456789",
        "mobileWalletOperator": "MTN"
      }
    ]
  },
  "paymentDestinations": {
    "bills": [
      { 
        "amountInCents": 133,
        "currency": "GHS",
        "productReference": "e8292091-e563-465a-af71-3569d90913a2",
        "productFields":
        {
          "accountRef": "201801603",
          "test": "hello"
        }
      }
    ]
  },
  "location": {
    "longitude": -73.899020,
    "latitude": 40.654170
  },
  "paymentStatusWebhook": {
    "callbackUrl": "https://your.callback.endpoint",
    "onPaymentCompleteOnly": true
  }
}

Auth: Access token (Bearer).

Request body

FieldTypeRequiredDescription
paymentSourcesobjectYesModel to hold lists of Cards and Mobile Money accounts from which a payment must be made.
paymentDestinationsobjectYesModel to hold lists of Merchants who must be paid.
channelUnknown, Web, USSD, Callback, Generated, Settlement, Scheduled, MobileApplication, SDK, POS, SuperPOSNoSpecify the channel that this payment originated from.
yourReferencestring?NoA unique client reference for this payment. This is optional to detect duplicate calls and also allow you to associate payments with your own internal reference numbers.
splitReferencestring?NoAn optional reference that is associated with every transaction batch that participates in a split payment. This is used for split payments in environments like restaurants where multiple transaction batches contribute to one common bill. The client processing the split payment is responsible for generating this reference and ensuring that all transaction batches that are part of the split payment are associated with the same split reference.
consumerobjectNoCore identity and contact details for a consumer (end user).
merchantobjectNoCore identity, categorisation, and contact details for a merchant.
locationobjectNoA geographic coordinate with an optional time zone and description. Used to pin an address or entity on a map.
paymentStatusWebhookobjectNoA model to hold the details of a web hook that a caller of this API would like to be called back on.
descriptionstring?NoA text description of the payment. Sometimes also referred to as a Narration.
recurrenceScheduleobjectNoDefines a recurrence schedule for a repeating payment, specifying the interval, end condition, and historical schedule entries.
lineItemsarray<object>?NoA list of line items associated with this payment.
json
{
  "paymentSources": {
    "cards": [],
    "mobileWallets": [],
    "bankAccounts": [],
    "wallets": [],
    "cash": {},
    "applePay": {},
    "googlePay": {}
  },
  "paymentDestinations": {
    "merchants": [],
    "mobileWallets": [],
    "bankAccounts": [],
    "qrCodes": [],
    "cards": [],
    "wallets": [],
    "bills": [],
    "cash": {}
  },
  "channel": "Unknown",
  "yourReference": "string",
  "splitReference": "00000000-0000-0000-0000-000000000000",
  "consumer": {
    "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
  },
  "merchant": {
    "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
  },
  "location": {
    "latitude": 0,
    "longitude": 0,
    "timeZone": "string",
    "description": "string"
  },
  "paymentStatusWebhook": {
    "callbackUrl": "string",
    "onPaymentCompleteOnly": true
  },
  "description": "string",
  "recurrenceSchedule": {
    "repeatInterval": "Weekly",
    "scheduleEndDate": "string",
    "repeatCount": 0
  },
  "lineItems": [
    {}
  ]
}

Responses

StatusDescription
202The payment request was received and processed successfully.
400The request failed validation, the error object will contain further information.
401The authorization information provided is not valid, authentication is required to access this resource.
403The authorization header does not contain the correct type or you do not have access to this resource.
422The request payload is invalid, the error object will contain further information.
429Too many requests are being sent concurrently or rate limiting has taken effect.
500An unexpected error occurred, the error object will contain further information.

Response body

FieldTypeRequiredDescription
successbooleanNoGets a value indicating whether the operation was successful.
resultobjectNoModel to hold details of a response to a payment request.
json
{
  "success": true,
  "result": {
    "reference": "00000000-0000-0000-0000-000000000000",
    "paymentStatusUrls": {}
  }
}

Code samples ​

ts
// @vantagepay/vantagepay
import { ApiError, OnPaymentComplete } from '@vantagepay/vantagepay'

client.events.subscribe(OnPaymentComplete, (_, status) => {
  console.log('Payment complete:', status.paymentReference)
})

try {
  const status = await client.payments.pay({
    yourReference: 'ORDER-1001',
    paymentSources: {
      mobileWallets: [{ mobileWalletOperator: 'MTN', msisdn: '233555666112', amountInCents: 5000, currency: 'GHS' }],
    },
    paymentDestinations: {
      merchants: [{ merchantReference: '3fa85f64-5717-4562-b3fc-2c963f66afa6', amountInCents: 5000, currency: 'GHS', paymentType: 'BuyingGoods' }],
    },
  })
  console.log('Initial status:', status.percentageComplete)
} catch (error) {
  if (error instanceof ApiError) console.error(error.statusCode, error.message)
  else throw error
}
csharp
// VantagePay.SDK
using System.Collections.Generic;
using VantagePay.Models.Lookups;
using VantagePay.Models.Payments;
using VantagePay.Models.Payments.Requests;

client.Payments.OnPaymentComplete = status => Console.WriteLine($"Complete: {status.PaymentReference}");

var initialStatus = await client.Payments.PayAsync(new PaymentRequest
{
    YourReference = "ORDER-1001",
    PaymentSources = new PaymentSources
    {
        MobileWallets = new List<MobileWalletSource>
        {
            new() { MobileWalletOperator = MobileWalletOperator.MTN, Msisdn = "233555666112", AmountInCents = 5000, Currency = Currency.GHS },
        },
    },
    PaymentDestinations = new PaymentDestinations
    {
        Merchants = new List<MerchantDestination>
        {
            new() { MerchantReference = "3fa85f64-5717-4562-b3fc-2c963f66afa6", AmountInCents = 5000, Currency = Currency.GHS, PaymentType = MerchantPaymentType.BuyingGoods },
        },
    },
});

Generate a settlement batch for a batch number. ​

POST /v1/pay/merchant/external-settlement

Auth: Access token (Bearer).

Request body

FieldTypeRequiredDescription
merchantAccountNumberstring?NoThe merchant account number as returned by the terminal, with leading zeros stripped.
terminalNumberstring?NoThe terminal identifier, left-padded to 8 digits and with leading zeros stripped before padding.
batchNumberstring?NoThe settlement batch number, left-padded to 3 digits.
transactionDateUtcstringNoThe UTC date and time the terminal submitted the settlement batch.
timeZonestring?NoThe IANA or Windows time-zone identifier for the terminal's local time, used to display settlement times in the correct zone.
transactionReferencestring?NoThe unique transaction reference assigned to this settlement batch by the payment engine.
currencyone of 106 values (e.g. None, AFN, ALL, ...)NoThe currency in which the settlement batch was processed.
batchFailedReferencestring?NoThe reference returned by the host for any transactions that failed to settle.
batchFailedCountintegerNoThe number of transactions in the batch that failed to settle.
totalTransactionCountintegerNoThe total number of transactions included in the settlement batch.
totalTransactionAmountInCentsintegerNoThe aggregate settled amount in cents across all transactions in the batch.
debitCardTransactionCountintegerNoThe number of debit-card transactions included in the batch.
debitCardTransactionAmountInCentsintegerNoThe aggregate debit-card settled amount in cents.
resultCodestring?NoThe ISO 8583 result code returned by the acquirer host for the settlement batch.
resultTextstring?NoA human-readable description of the ZGA.Core.Models.Payments.ExternalCardSettlementData.ResultCode.
messagestring?NoA short message describing the overall outcome of the settlement batch.
hostResponsestring?NoThe raw response string returned by the acquiring host.
locationobjectNoA geographic coordinate with an optional time zone and description. Used to pin an address or entity on a map.
json
{
  "merchantAccountNumber": "string",
  "terminalNumber": "string",
  "batchNumber": "string",
  "transactionDateUtc": "string",
  "timeZone": "string",
  "transactionReference": "string",
  "currency": "None",
  "batchFailedReference": "string",
  "batchFailedCount": 0,
  "totalTransactionCount": 0,
  "totalTransactionAmountInCents": 0,
  "debitCardTransactionCount": 0,
  "debitCardTransactionAmountInCents": 0,
  "resultCode": "string",
  "resultText": "string",
  "message": "string",
  "hostResponse": "string",
  "location": {
    "latitude": 0,
    "longitude": 0,
    "timeZone": "string",
    "description": "string"
  }
}

Responses

StatusDescription
200The request was successful but does not return any results.
400The request failed validation, the error object will contain further information.
401The authorization information provided is not valid, authentication is required to access this resource.
403The authorization header does not contain the correct type or you do not have access to this resource.
422The request payload is invalid, the error object will contain further information.
429Too many requests are being sent concurrently or rate limiting has taken effect.
500An unexpected error occurred, the error object will contain further information.

Response body

FieldTypeRequiredDescription
successbooleanNoGets a value indicating whether the operation was successful.
json
{
  "success": true
}

Code samples ​

ts
// @vantagepay/vantagepay
// POS terminal integration - typically driven from the .NET SDK.
// Not wrapped by the JavaScript SDK - call the endpoint directly with the active token.
const response = await fetch(baseUrl + '/v1/pay/merchant/external-settlement', {
  method: 'POST',
  headers: { Authorization: 'Bearer ' + ApiTokens.accessToken },
})
const result = await response.json()
csharp
// VantagePay.SDK
using VantagePay.Models.Payments;
using VantagePay.Models.Lookups;

await client.Payments.CreateSettlementBatchAsync(new ExternalCardSettlementData
{
    MerchantAccountNumber = "12345678",
    TerminalNumber = "00000042",
    BatchNumber = "001",
    Currency = Currency.ZAR,
    TotalTransactionCount = 12,
    TotalTransactionAmountInCents = 150000,
    ResultCode = "0",
    TransactionReference = "e1d2c3b4-a5f6-4738-9a0b-1c2d3e4f5a6b",
});

Generate a transaction for an external card payment. ​

POST /v1/pay/merchant/external-card

Auth: Access token (Bearer).

Request body

FieldTypeRequiredDescription
transactionDateUtcstringNoThe UTC date and time the terminal submitted the transaction.
timeZonestring?NoThe IANA or Windows time-zone identifier for the terminal's local time.
transactionBatchReferencestring?NoThe payment engine transaction batch reference associated with this terminal transaction.
splitReferencestring?NoA shared split-payment reference that groups multiple batches contributing to the same consumer bill.
tipEmployeeReferencestring?NoThe reference of the employee who should receive the tip, if applicable.
transactionReferencestring?NoThe unique transaction reference assigned by the payment engine.
transactionNumberstring?NoThe transaction sequence number assigned by the terminal.
transactionTypestring?NoThe transaction type descriptor as returned by the terminal (e.g. PURCHASE, REFUND).
merchantAccountNumberstring?NoThe merchant account number as returned by the terminal, with leading zeros stripped.
terminalNumberstring?NoThe terminal identifier, left-padded to 8 digits.
batchNumberstring?NoThe settlement batch number, left-padded to 3 digits.
customDescriptionstring?NoAn optional description that overrides the default transaction label, used for itemised receipts.
currencyone of 106 values (e.g. None, AFN, ALL, ...)NoThe currency in which the transaction was processed.
requestedAmountInCentsintegerNoThe purchase amount in cents originally requested by the terminal.
approvedAmountInCentsintegerNoThe purchase amount in cents approved by the acquiring host.
requestedCashbackAmountInCentsintegerNoThe cashback amount in cents requested by the cardholder.
approvedCashbackAmountInCentsintegerNoThe cashback amount in cents approved by the acquiring host.
requestedMerchantFeeInCentsintegerNoThe merchant surcharge fee in cents requested.
approvedMerchantFeeInCentsintegerNoThe merchant surcharge fee in cents approved by the acquiring host.
requestedTaxAmountInCentsintegerNoThe tax amount in cents requested.
approvedTaxAmountInCentsintegerNoThe tax amount in cents approved by the acquiring host.
requestedTipAmountInCentsintegerNoThe tip amount in cents requested by the cardholder.
approvedTipAmountInCentsintegerNoThe tip amount in cents approved by the acquiring host.
maskedCardNumberstring?NoThe masked PAN of the card used (e.g. 411111******1111).
expiryDatestring?NoThe card expiry date as returned by the terminal (format: MMYY or YYMM depending on scheme).
authCodestring?NoThe authorisation code returned by the issuer for an approved transaction.
authModestring?NoThe authentication mode used (e.g. PIN, SIGNATURE, CONTACTLESS).
resultCodestring?NoThe ISO 8583 result code returned by the acquiring host (e.g. 00 for approved).
messagestring?NoA short human-readable outcome message.
detailedMessagestring?NoA verbose description of the outcome, supplementing ZGA.Core.Models.Payments.ExternalCardTransactionData.Message.
hostResponsestring?NoThe raw response string returned by the acquiring host.
gatewayTransactionReferencestring?NoA unique transaction reference assigned by the payment gateway.
gatewayResponsestring?NoThe raw JSON or string response returned by the payment gateway.
avsResponsestring?NoThe Address Verification Service (AVS) response code returned by the issuer.
cvvResponsestring?NoThe Card Verification Value (CVV/CVC) check response code returned by the issuer.
issuerResponseCodestring?NoThe ISO 8583 response code returned by the card issuer.
globalUniqueIdentifierstring?NoA globally unique identifier assigned to this transaction by the network or acquirer.
cardPresentFlagstring?NoFlag indicating whether the card was physically present at the terminal (e.g. 1 = present, 0 = absent).
entryModeFlagstring?NoThe card-data entry mode flag (e.g. chip, swipe, contactless, manual).
pinStatusFlagstring?NoFlag indicating the PIN entry status for this transaction.
apppnstring?NoEMV Application Preferred Name (APPPN) from the chip.
aidstring?NoEMV Application Identifier (AID) from the chip.
atcstring?NoEMV Application Transaction Counter (ATC) from the chip.
acstring?NoEMV Application Cryptogram (AC) generated by the chip for this transaction.
tvrstring?NoEMV Terminal Verification Results (TVR) - a bitmap of checks performed by the terminal.
tsistring?NoEMV Transaction Status Information (TSI) - indicates which functions were performed during processing.
cvmstring?NoEMV Cardholder Verification Method (CVM) used (e.g. PIN, signature, no CVM).
ctqstring?NoEMV Card Transaction Qualifiers (CTQ) - contactless transaction qualifier bitmap.
stanstring?NoThe Systems Trace Audit Number (STAN) assigned by the terminal for this transaction.
invoiceNumberstring?NoThe terminal-assigned invoice number for this transaction.
receiptNumberstring?NoThe receipt number printed on the customer copy.
nameOnCardstring?NoThe cardholder name as embossed or encoded on the card.
locationobjectNoA geographic coordinate with an optional time zone and description. Used to pin an address or entity on a map.
printLinesarray<string>?NoFree-text lines to be appended verbatim to the printed receipt.
lineItemsarray<object>?NoItemised line items that make up this transaction (products or services purchased).
clientDataobject?NoA key-value map of arbitrary client data forwarded from the terminal to the payment engine.
json
{
  "transactionDateUtc": "string",
  "timeZone": "string",
  "transactionBatchReference": "00000000-0000-0000-0000-000000000000",
  "splitReference": "00000000-0000-0000-0000-000000000000",
  "tipEmployeeReference": "string",
  "transactionReference": "string",
  "transactionNumber": "string",
  "transactionType": "string",
  "merchantAccountNumber": "string",
  "terminalNumber": "string",
  "batchNumber": "string",
  "customDescription": "string",
  "currency": "None",
  "requestedAmountInCents": 0,
  "approvedAmountInCents": 0,
  "requestedCashbackAmountInCents": 0,
  "approvedCashbackAmountInCents": 0,
  "requestedMerchantFeeInCents": 0,
  "approvedMerchantFeeInCents": 0,
  "requestedTaxAmountInCents": 0,
  "approvedTaxAmountInCents": 0,
  "requestedTipAmountInCents": 0,
  "approvedTipAmountInCents": 0,
  "maskedCardNumber": "string",
  "expiryDate": "string",
  "authCode": "string",
  "authMode": "string",
  "resultCode": "string",
  "message": "string",
  "detailedMessage": "string",
  "hostResponse": "string",
  "gatewayTransactionReference": "string",
  "gatewayResponse": "string",
  "avsResponse": "string",
  "cvvResponse": "string",
  "issuerResponseCode": "string",
  "globalUniqueIdentifier": "string",
  "cardPresentFlag": "string",
  "entryModeFlag": "string",
  "pinStatusFlag": "string",
  "apppn": "string",
  "aid": "string",
  "atc": "string",
  "ac": "string",
  "tvr": "string",
  "tsi": "string",
  "cvm": "string",
  "ctq": "string",
  "stan": "string",
  "invoiceNumber": "string",
  "receiptNumber": "string",
  "nameOnCard": "string",
  "location": {
    "latitude": 0,
    "longitude": 0,
    "timeZone": "string",
    "description": "string"
  },
  "printLines": [
    "string"
  ],
  "lineItems": [
    {}
  ],
  "clientData": {}
}

Responses

StatusDescription
202The payment request was submitted successfully.
400The request failed validation, the error object will contain further information.
401The authorization information provided is not valid, authentication is required to access this resource.
403The authorization header does not contain the correct type or you do not have access to this resource.
422The request payload is invalid, the error object will contain further information.
429Too many requests are being sent concurrently or rate limiting has taken effect.
500An unexpected error occurred, the error object will contain further information.

Response body

FieldTypeRequiredDescription
successbooleanNoGets a value indicating whether the operation was successful.
resultobjectNoModel to hold details of a response to a payment request.
json
{
  "success": true,
  "result": {
    "reference": "00000000-0000-0000-0000-000000000000",
    "paymentStatusUrls": {}
  }
}

Code samples ​

ts
// @vantagepay/vantagepay
// POS terminal integration - typically driven from the .NET SDK.
// Not wrapped by the JavaScript SDK - call the endpoint directly with the active token.
const response = await fetch(baseUrl + '/v1/pay/merchant/external-card', {
  method: 'POST',
  headers: { Authorization: 'Bearer ' + ApiTokens.accessToken },
})
const result = await response.json()
csharp
// VantagePay.SDK
using VantagePay.Models.Payments;
using VantagePay.Models.Lookups;

var status = await client.Payments.PayMerchantAsync(new ExternalCardTransactionData
{
    TransactionReference = "e1d2c3b4-a5f6-4738-9a0b-1c2d3e4f5a6b",
    MerchantAccountNumber = "12345678",
    TerminalNumber = "00000042",
    Currency = Currency.ZAR,
    RequestedAmountInCents = 5000,
    ApprovedAmountInCents = 5000,
    MaskedCardNumber = "411111******1111",
    ResultCode = "0",
    TransactionType = "PURCHASE",
});

Cancel/reverse an external card payment made to a merchant. ​

POST /v1/pay/merchant/external-card/cancel

Auth: Access token (Bearer).

Request body

FieldTypeRequiredDescription
transactionDateUtcstringNoThe UTC date and time the terminal submitted the transaction.
timeZonestring?NoThe IANA or Windows time-zone identifier for the terminal's local time.
transactionBatchReferencestring?NoThe payment engine transaction batch reference associated with this terminal transaction.
splitReferencestring?NoA shared split-payment reference that groups multiple batches contributing to the same consumer bill.
tipEmployeeReferencestring?NoThe reference of the employee who should receive the tip, if applicable.
transactionReferencestring?NoThe unique transaction reference assigned by the payment engine.
transactionNumberstring?NoThe transaction sequence number assigned by the terminal.
transactionTypestring?NoThe transaction type descriptor as returned by the terminal (e.g. PURCHASE, REFUND).
merchantAccountNumberstring?NoThe merchant account number as returned by the terminal, with leading zeros stripped.
terminalNumberstring?NoThe terminal identifier, left-padded to 8 digits.
batchNumberstring?NoThe settlement batch number, left-padded to 3 digits.
customDescriptionstring?NoAn optional description that overrides the default transaction label, used for itemised receipts.
currencyone of 106 values (e.g. None, AFN, ALL, ...)NoThe currency in which the transaction was processed.
requestedAmountInCentsintegerNoThe purchase amount in cents originally requested by the terminal.
approvedAmountInCentsintegerNoThe purchase amount in cents approved by the acquiring host.
requestedCashbackAmountInCentsintegerNoThe cashback amount in cents requested by the cardholder.
approvedCashbackAmountInCentsintegerNoThe cashback amount in cents approved by the acquiring host.
requestedMerchantFeeInCentsintegerNoThe merchant surcharge fee in cents requested.
approvedMerchantFeeInCentsintegerNoThe merchant surcharge fee in cents approved by the acquiring host.
requestedTaxAmountInCentsintegerNoThe tax amount in cents requested.
approvedTaxAmountInCentsintegerNoThe tax amount in cents approved by the acquiring host.
requestedTipAmountInCentsintegerNoThe tip amount in cents requested by the cardholder.
approvedTipAmountInCentsintegerNoThe tip amount in cents approved by the acquiring host.
maskedCardNumberstring?NoThe masked PAN of the card used (e.g. 411111******1111).
expiryDatestring?NoThe card expiry date as returned by the terminal (format: MMYY or YYMM depending on scheme).
authCodestring?NoThe authorisation code returned by the issuer for an approved transaction.
authModestring?NoThe authentication mode used (e.g. PIN, SIGNATURE, CONTACTLESS).
resultCodestring?NoThe ISO 8583 result code returned by the acquiring host (e.g. 00 for approved).
messagestring?NoA short human-readable outcome message.
detailedMessagestring?NoA verbose description of the outcome, supplementing ZGA.Core.Models.Payments.ExternalCardTransactionData.Message.
hostResponsestring?NoThe raw response string returned by the acquiring host.
gatewayTransactionReferencestring?NoA unique transaction reference assigned by the payment gateway.
gatewayResponsestring?NoThe raw JSON or string response returned by the payment gateway.
avsResponsestring?NoThe Address Verification Service (AVS) response code returned by the issuer.
cvvResponsestring?NoThe Card Verification Value (CVV/CVC) check response code returned by the issuer.
issuerResponseCodestring?NoThe ISO 8583 response code returned by the card issuer.
globalUniqueIdentifierstring?NoA globally unique identifier assigned to this transaction by the network or acquirer.
cardPresentFlagstring?NoFlag indicating whether the card was physically present at the terminal (e.g. 1 = present, 0 = absent).
entryModeFlagstring?NoThe card-data entry mode flag (e.g. chip, swipe, contactless, manual).
pinStatusFlagstring?NoFlag indicating the PIN entry status for this transaction.
apppnstring?NoEMV Application Preferred Name (APPPN) from the chip.
aidstring?NoEMV Application Identifier (AID) from the chip.
atcstring?NoEMV Application Transaction Counter (ATC) from the chip.
acstring?NoEMV Application Cryptogram (AC) generated by the chip for this transaction.
tvrstring?NoEMV Terminal Verification Results (TVR) - a bitmap of checks performed by the terminal.
tsistring?NoEMV Transaction Status Information (TSI) - indicates which functions were performed during processing.
cvmstring?NoEMV Cardholder Verification Method (CVM) used (e.g. PIN, signature, no CVM).
ctqstring?NoEMV Card Transaction Qualifiers (CTQ) - contactless transaction qualifier bitmap.
stanstring?NoThe Systems Trace Audit Number (STAN) assigned by the terminal for this transaction.
invoiceNumberstring?NoThe terminal-assigned invoice number for this transaction.
receiptNumberstring?NoThe receipt number printed on the customer copy.
nameOnCardstring?NoThe cardholder name as embossed or encoded on the card.
locationobjectNoA geographic coordinate with an optional time zone and description. Used to pin an address or entity on a map.
printLinesarray<string>?NoFree-text lines to be appended verbatim to the printed receipt.
lineItemsarray<object>?NoItemised line items that make up this transaction (products or services purchased).
clientDataobject?NoA key-value map of arbitrary client data forwarded from the terminal to the payment engine.
json
{
  "transactionDateUtc": "string",
  "timeZone": "string",
  "transactionBatchReference": "00000000-0000-0000-0000-000000000000",
  "splitReference": "00000000-0000-0000-0000-000000000000",
  "tipEmployeeReference": "string",
  "transactionReference": "string",
  "transactionNumber": "string",
  "transactionType": "string",
  "merchantAccountNumber": "string",
  "terminalNumber": "string",
  "batchNumber": "string",
  "customDescription": "string",
  "currency": "None",
  "requestedAmountInCents": 0,
  "approvedAmountInCents": 0,
  "requestedCashbackAmountInCents": 0,
  "approvedCashbackAmountInCents": 0,
  "requestedMerchantFeeInCents": 0,
  "approvedMerchantFeeInCents": 0,
  "requestedTaxAmountInCents": 0,
  "approvedTaxAmountInCents": 0,
  "requestedTipAmountInCents": 0,
  "approvedTipAmountInCents": 0,
  "maskedCardNumber": "string",
  "expiryDate": "string",
  "authCode": "string",
  "authMode": "string",
  "resultCode": "string",
  "message": "string",
  "detailedMessage": "string",
  "hostResponse": "string",
  "gatewayTransactionReference": "string",
  "gatewayResponse": "string",
  "avsResponse": "string",
  "cvvResponse": "string",
  "issuerResponseCode": "string",
  "globalUniqueIdentifier": "string",
  "cardPresentFlag": "string",
  "entryModeFlag": "string",
  "pinStatusFlag": "string",
  "apppn": "string",
  "aid": "string",
  "atc": "string",
  "ac": "string",
  "tvr": "string",
  "tsi": "string",
  "cvm": "string",
  "ctq": "string",
  "stan": "string",
  "invoiceNumber": "string",
  "receiptNumber": "string",
  "nameOnCard": "string",
  "location": {
    "latitude": 0,
    "longitude": 0,
    "timeZone": "string",
    "description": "string"
  },
  "printLines": [
    "string"
  ],
  "lineItems": [
    {}
  ],
  "clientData": {}
}

Responses

StatusDescription
202The payment request was submitted successfully.
400The request failed validation, the error object will contain further information.
401The authorization information provided is not valid, authentication is required to access this resource.
403The authorization header does not contain the correct type or you do not have access to this resource.
422The request payload is invalid, the error object will contain further information.
429Too many requests are being sent concurrently or rate limiting has taken effect.
500An unexpected error occurred, the error object will contain further information.

Response body

FieldTypeRequiredDescription
successbooleanNoGets a value indicating whether the operation was successful.
resultobjectNoModel to hold details of a response to a payment request.
json
{
  "success": true,
  "result": {
    "reference": "00000000-0000-0000-0000-000000000000",
    "paymentStatusUrls": {}
  }
}

Code samples ​

ts
// @vantagepay/vantagepay
// POS terminal integration - typically driven from the .NET SDK.
// Not wrapped by the JavaScript SDK - call the endpoint directly with the active token.
const response = await fetch(baseUrl + '/v1/pay/merchant/external-card/cancel', {
  method: 'POST',
  headers: { Authorization: 'Bearer ' + ApiTokens.accessToken },
})
const result = await response.json()
csharp
// VantagePay.SDK
using VantagePay.Models.Payments;

var status = await client.Payments.CancelMerchantPaymentAsync(new ExternalCardTransactionData
{
    TransactionReference = "e1d2c3b4-a5f6-4738-9a0b-1c2d3e4f5a6b",
    TransactionBatchReference = Guid.Parse("c7b8a9d0-1234-4567-89ab-cdef01234567"),
    MerchantAccountNumber = "12345678",
    TerminalNumber = "00000042",
});

Pay a merchant. ​

POST /v1/pay/merchant/{merchantReference}

Sample

json
POST /v1/pay/merchant/610c3876-5dd4-450d-a12f-901bf2e7b107
{
  "channel": 1,
  "yourReference": "{{$guid}}",
  "description": "Sample Merchant Payment",
  "consumer": {    
    "firstName": "John",
    "lastName": "Wick",
    "emailAddress": "demo@vantagepay.com",
    "mobileNumber": "233111222333",
    "countryIsoCode": "GHA"
  },
  "paymentSources": {
    "mobileWallets": [
      {
        "mobileWalletOperator": "MTN",
        "msisdn": "233111222333",
        "amountInCents": 133,
        "currency": "GHS"
      }
    ]
  },
  "location": {
    "longitude": -73.899020,
    "latitude": 40.654170
  },
  "paymentStatusWebhook": {
    "callbackUrl": "https://yourdomain.com/callback",
    "onPaymentCompleteOnly": true
  }
}

Auth: Access token (Bearer).

Parameters

NameInRequiredDescription
merchantReferencepathYesThe globally unique internal merchant reference (UUID) of the merchant to be paid.

Request body

FieldTypeRequiredDescription
paymentSourcesobjectYesModel to hold lists of Cards and Mobile Money accounts from which a payment must be made.
terminalReferencestring?NoThe optional terminal reference if this payment is being made from a merchant controlled device.
qrCodeReferencestring?NoThe optional QR code reference if this payment is being made from a scanned QR code.
timestampinteger?NoThe optional timestamp from the client used to calculate an offline verification code.
notificationEmailAddressstring?NoAn optional email address to notify once the payment has been processed. When provided, a receipt email is sent to this address regardless of the merchant's default notification settings.
notificationMobileNumberstring?NoAn optional mobile number (MSISDN) to notify once the payment has been processed. When provided, an SMS receipt is sent to this number regardless of the merchant's default notification settings.
tipAmountInCentsintegerNoAn optional tip amount, in the smallest currency unit (e.g. cents), to include on top of the base payment amount. Set to 0 when no tip is applicable.
tipEmployeeReferencestring?NoAn optional reference that identifies the employee who should receive the tip (e.g. a waiter or cashier). Only relevant when ZGA.Core.Models.Payments.Requests.MerchantPaymentRequest.TipAmountInCents is greater than zero.
channelUnknown, Web, USSD, Callback, Generated, Settlement, Scheduled, MobileApplication, SDK, POS, SuperPOSNoSpecify the channel that this payment originated from.
yourReferencestring?NoA unique client reference for this payment. This is optional to detect duplicate calls and also allow you to associate payments with your own internal reference numbers.
splitReferencestring?NoAn optional reference that is associated with every transaction batch that participates in a split payment. This is used for split payments in environments like restaurants where multiple transaction batches contribute to one common bill. The client processing the split payment is responsible for generating this reference and ensuring that all transaction batches that are part of the split payment are associated with the same split reference.
consumerobjectNoCore identity and contact details for a consumer (end user).
merchantobjectNoCore identity, categorisation, and contact details for a merchant.
locationobjectNoA geographic coordinate with an optional time zone and description. Used to pin an address or entity on a map.
paymentStatusWebhookobjectNoA model to hold the details of a web hook that a caller of this API would like to be called back on.
descriptionstring?NoA text description of the payment. Sometimes also referred to as a Narration.
recurrenceScheduleobjectNoDefines a recurrence schedule for a repeating payment, specifying the interval, end condition, and historical schedule entries.
lineItemsarray<object>?NoA list of line items associated with this payment.
json
{
  "paymentSources": {
    "cards": [],
    "mobileWallets": [],
    "bankAccounts": [],
    "wallets": [],
    "cash": {},
    "applePay": {},
    "googlePay": {}
  },
  "terminalReference": "00000000-0000-0000-0000-000000000000",
  "qrCodeReference": "00000000-0000-0000-0000-000000000000",
  "timestamp": 0,
  "notificationEmailAddress": "string",
  "notificationMobileNumber": "string",
  "tipAmountInCents": 0,
  "tipEmployeeReference": "string",
  "channel": "Unknown",
  "yourReference": "string",
  "splitReference": "00000000-0000-0000-0000-000000000000",
  "consumer": {
    "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
  },
  "merchant": {
    "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
  },
  "location": {
    "latitude": 0,
    "longitude": 0,
    "timeZone": "string",
    "description": "string"
  },
  "paymentStatusWebhook": {
    "callbackUrl": "string",
    "onPaymentCompleteOnly": true
  },
  "description": "string",
  "recurrenceSchedule": {
    "repeatInterval": "Weekly",
    "scheduleEndDate": "string",
    "repeatCount": 0
  },
  "lineItems": [
    {}
  ]
}

Responses

StatusDescription
202The payment request was submitted and processed successfully.
400The request failed validation, the error object will contain further information.
422The request payload is invalid, the error object will contain further information.
429Too many requests are being sent concurrently or rate limiting has taken effect.
500An unexpected error occurred, the error object will contain further information.

Response body

FieldTypeRequiredDescription
successbooleanNoGets a value indicating whether the operation was successful.
resultobjectNoA payment response returned to a merchant after initiating a payment, extending the base response with an optional access token.
json
{
  "success": true,
  "result": {
    "accessToken": "string",
    "reference": "00000000-0000-0000-0000-000000000000",
    "paymentStatusUrls": {}
  }
}

Code samples ​

ts
// @vantagepay/vantagepay
// Supports anonymous callers; the access token from the response is stored automatically.
const status = await client.payments.payMerchant('3fa85f64-5717-4562-b3fc-2c963f66afa6', {
  paymentSources: {
    mobileWallets: [{ mobileWalletOperator: 'MTN', msisdn: '233555666112', amountInCents: 5000, currency: 'GHS' }],
  },
  tipAmountInCents: 0,
})
csharp
// VantagePay.SDK
using System.Collections.Generic;
using VantagePay.Models.Lookups;
using VantagePay.Models.Payments;
using VantagePay.Models.Payments.Requests;

var status = await client.Payments.PayMerchantAsync(Guid.Parse("3fa85f64-5717-4562-b3fc-2c963f66afa6"), new MerchantPaymentRequest
{
    PaymentSources = new PaymentSources
    {
        MobileWallets = new List<MobileWalletSource>
        {
            new() { MobileWalletOperator = MobileWalletOperator.MTN, Msisdn = "233555666112", AmountInCents = 5000, Currency = Currency.GHS },
        },
    },
    TipAmountInCents = 0,
});

Cancel a recurrence schedule. ​

DELETE /v1/pay/schedules/{scheduleReference}

This endpoint will cancel a payment recurrence schedule and all schedule entries that have not yet been processed will be cancelled immediately.

Sample

json
DELETE /v1/pay/schedules/9fd4dff4-5edc-4b28-b593-dc76739a6171

Auth: Access token (Bearer).

Parameters

NameInRequiredDescription
scheduleReferencepathYesReference for the recurrence schedule to be cancelled.

Responses

StatusDescription
200The request was successful but does not return any results.
400The request failed validation, the error object will contain further information.
401The authorization information provided is not valid, authentication is required to access this resource.
403The authorization header does not contain the correct type or you do not have access to this resource.
404The request was successful but does not return any results.
422The request payload is invalid, the error object will contain further information.
429Too many requests are being sent concurrently or rate limiting has taken effect.
500An unexpected error occurred, the error object will contain further information.

Response body

FieldTypeRequiredDescription
successbooleanNoGets a value indicating whether the operation was successful.
resultobjectNoDefines a recurrence schedule for a repeating payment, specifying the interval, end condition, and historical schedule entries.
json
{
  "success": true,
  "result": {
    "repeatInterval": "Weekly",
    "scheduleEndDate": "string",
    "repeatCount": 0
  }
}

Code samples ​

ts
// @vantagepay/vantagepay
// Deletes a recurring-payment schedule. Not wrapped by the JavaScript SDK.
// Not wrapped by the JavaScript SDK - call the endpoint directly with the active token.
const response = await fetch(baseUrl + '/v1/pay/schedules/' + scheduleReference, {
  method: 'DELETE',
  headers: { Authorization: 'Bearer ' + ApiTokens.accessToken },
})
const result = await response.json()
csharp
// VantagePay.SDK
await client.Payments.DeletePaymentRecurrenceScheduleAsync(Guid.Parse("11112222-3333-4444-5555-666677778888"));

Get all active payment schedules for a given user. ​

GET /v1/pay/schedules

This endpoint will retrieve a list of all active payment recurrence schedules for the user to which the proffered access token belongs.

Sample

json
GET /v1/pay/schedules

Auth: Access token (Bearer).

Responses

StatusDescription
200The request was successful but does not return any results.
400The request failed validation, the error object will contain further information.
401The authorization information provided is not valid, authentication is required to access this resource.
403The authorization header does not contain the correct type or you do not have access to this resource.
422The request payload is invalid, the error object will contain further information.
429Too many requests are being sent concurrently or rate limiting has taken effect.
500An unexpected error occurred, the error object will contain further information.

Response body

FieldTypeRequiredDescription
successbooleanNoGets a value indicating whether the operation was successful.
resultarray<object>?NoGets the response payload.
json
{
  "success": true,
  "result": [
    {}
  ]
}

Code samples ​

ts
// @vantagepay/vantagepay
// Lists recurring-payment schedules. Not wrapped by the JavaScript SDK.
// Not wrapped by the JavaScript SDK - call the endpoint directly with the active token.
const response = await fetch(baseUrl + '/v1/pay/schedules', {
  method: 'GET',
  headers: { Authorization: 'Bearer ' + ApiTokens.accessToken },
})
const result = await response.json()
csharp
// VantagePay.SDK
await client.Payments.GetPaymentRecurrenceSchedulesAsync();

Payments for Africa

© VantagePay 2026