Pay with USSD

Starts a USSD payment and returns the dial string. The customer dials it on their phone, with no data connection or app, and authorises the payment through their bank’s USSD menu.

Show data.ussdCode clearly, ideally as a tap-to-dial link on mobile, and tell the customer to dial it from the phone number they entered. The channel is asynchronous. Wait for the checkout.completed event or the payment.completed webhook, then confirm with verify before you fulfil.

Without phoneNumber the call fails with ussd.phone_required. If the request cannot be started, ussd.failed tells you to check the number and try again.

POST

payment

checkout

charge

ussd

Pay with USSD

curl --request POST \
  --url https://api.sandbox.vestrapay.app/v1/payment/checkout/charge/ussd \
  --header 'Content-Type: application/json' \
  --header 'x-access-code: <api-key>' \
  --data '
{
  "phoneNumber": "08012345678"
}
'

const options = {
  method: 'POST',
  headers: {'x-access-code': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({phoneNumber: '08012345678'})
};

fetch('https://api.sandbox.vestrapay.app/v1/payment/checkout/charge/ussd', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.sandbox.vestrapay.app/v1/payment/checkout/charge/ussd"

payload = { "phoneNumber": "08012345678" }
headers = {
    "x-access-code": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sandbox.vestrapay.app/v1/payment/checkout/charge/ussd",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'phoneNumber' => '08012345678'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-access-code: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "status": "success",
  "data": {
    "status": "awaiting_ussd",
    "reference": "VPY_TXN_ACME001",
    "ussdCode": "*737*000*100#"
  }
}

Authorizations

x-access-code

string

header

required

The accessCode returned by initialise. Scoped to one payment and valid for 60 minutes. Safe to give to the customer's browser.

Body

application/json

phoneNumber

string

required

The customer's phone number. They should dial the code from this number.

Example:

"08012345678"

Response

USSD code to dial.

status

enum<string>

required

Available options:

success

data

object

required

Show child attributes

Pay with USSD

curl --request POST \
  --url https://api.sandbox.vestrapay.app/v1/payment/checkout/charge/ussd \
  --header 'Content-Type: application/json' \
  --header 'x-access-code: <api-key>' \
  --data '
{
  "phoneNumber": "08012345678"
}
'

const options = {
  method: 'POST',
  headers: {'x-access-code': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({phoneNumber: '08012345678'})
};

fetch('https://api.sandbox.vestrapay.app/v1/payment/checkout/charge/ussd', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.sandbox.vestrapay.app/v1/payment/checkout/charge/ussd"

payload = { "phoneNumber": "08012345678" }
headers = {
    "x-access-code": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.sandbox.vestrapay.app/v1/payment/checkout/charge/ussd",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'phoneNumber' => '08012345678'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-access-code: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "status": "success",
  "data": {
    "status": "awaiting_ussd",
    "reference": "VPY_TXN_ACME001",
    "ussdCode": "*737*000*100#"
  }
}

Payments

Checkout

Pay with USSD

Authorizations

Body

Response