Charge a customer using tokenized card data

curl --request POST \
  --url https://api.nomba.com/v1/checkout/tokenized-card-payment \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'accountId: <accountid>' \
  --data '
{
  "tokenKey": "7628788443"
}
'

import requests

url = "https://api.nomba.com/v1/checkout/tokenized-card-payment"

payload = { "tokenKey": "7628788443" }
headers = {
    "accountId": "<accountid>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    accountId: '<accountid>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({tokenKey: '7628788443'})
};

fetch('https://api.nomba.com/v1/checkout/tokenized-card-payment', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.nomba.com/v1/checkout/tokenized-card-payment",
  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([
    'tokenKey' => '7628788443'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "accountId: <accountid>"
  ],
]);

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

curl_close($curl);

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

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.nomba.com/v1/checkout/tokenized-card-payment"

	payload := strings.NewReader("{\n  \"tokenKey\": \"7628788443\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("accountId", "<accountid>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.nomba.com/v1/checkout/tokenized-card-payment")
  .header("accountId", "<accountid>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"tokenKey\": \"7628788443\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.nomba.com/v1/checkout/tokenized-card-payment")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["accountId"] = '<accountid>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"tokenKey\": \"7628788443\"\n}"

response = http.request(request)
puts response.read_body

{
  "code": "00",
  "description": "tokenized transaction completed successfully",
  "data": {
    "status": false,
    "message": "Please enter the OTP sent to the phone/email address registered with your bank.",
    "orderId": "b6a3c0f2-6d2e-4c1a-9a41-3f2b7d0c9e15",
    "orderReference": "90e81e8a-bc14-4ebf-89c0-57da752cca58",
    "otpRequired": true,
    "transactionId": "a729d716-566f-4a47-986f-32b3fa39e075"
  }
}

{
  "code": "400",
  "description": "Request failed."
}

{
  "code": "401",
  "description": "Unauthorized"
}

{
  "code": "403",
  "description": "Forbidden"
}

{
  "code": "404",
  "description": "Record not found"
}

{
  "code": "429",
  "description": "Too many requests"
}

{
  "code": "500",
  "description": "Server error"
}

POST

checkout

tokenized-card-payment

Charge a customer using tokenized card data

curl --request POST \
  --url https://api.nomba.com/v1/checkout/tokenized-card-payment \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'accountId: <accountid>' \
  --data '
{
  "tokenKey": "7628788443"
}
'

import requests

url = "https://api.nomba.com/v1/checkout/tokenized-card-payment"

payload = { "tokenKey": "7628788443" }
headers = {
    "accountId": "<accountid>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {
    accountId: '<accountid>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({tokenKey: '7628788443'})
};

fetch('https://api.nomba.com/v1/checkout/tokenized-card-payment', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.nomba.com/v1/checkout/tokenized-card-payment",
  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([
    'tokenKey' => '7628788443'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "accountId: <accountid>"
  ],
]);

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

curl_close($curl);

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

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.nomba.com/v1/checkout/tokenized-card-payment"

	payload := strings.NewReader("{\n  \"tokenKey\": \"7628788443\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("accountId", "<accountid>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.nomba.com/v1/checkout/tokenized-card-payment")
  .header("accountId", "<accountid>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"tokenKey\": \"7628788443\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.nomba.com/v1/checkout/tokenized-card-payment")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["accountId"] = '<accountid>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"tokenKey\": \"7628788443\"\n}"

response = http.request(request)
puts response.read_body

{
  "code": "00",
  "description": "tokenized transaction completed successfully",
  "data": {
    "status": false,
    "message": "Please enter the OTP sent to the phone/email address registered with your bank.",
    "orderId": "b6a3c0f2-6d2e-4c1a-9a41-3f2b7d0c9e15",
    "orderReference": "90e81e8a-bc14-4ebf-89c0-57da752cca58",
    "otpRequired": true,
    "transactionId": "a729d716-566f-4a47-986f-32b3fa39e075"
  }
}

{
  "code": "400",
  "description": "Request failed."
}

{
  "code": "401",
  "description": "Unauthorized"
}

{
  "code": "403",
  "description": "Forbidden"
}

{
  "code": "404",
  "description": "Record not found"
}

{
  "code": "429",
  "description": "Too many requests"
}

{
  "code": "500",
  "description": "Server error"
}

For a complete guide on response codes and transaction statuses, see Response Codes.

Some banks require the customer to enter an OTP before a tokenized card can be charged. When that happens, the response has otpRequired: true and a transactionId, and the charge stays pending:

Collect the OTP the customer receives from their bank.
Submit it with Submit customer card OTP, sending otp, orderReference and the transactionId from this response.

A charge whose OTP is not submitted within about 15 minutes is marked as failed.

Authorizations

Authorization

string

header

required

Nomba authenticates API calls with OAuth2 HTTP bearer tokens. There are two methods of authentication; Client-Credentials method and PKCE (Proof Key for Code Exchange) method. Both methods return an access token. Send it in the Authorization header: Authorization: Bearer <access_token>.

Headers

accountId

string<uuid>

required

The parent accountId of the business.

Example:

"890022ce-bae0-45c1-9b9d-ee7872e6ca27"

Body

application/json

The request payload required to perform a tokenized payment.

The Tokenized card payment request object

tokenKey

string

required

the token key returned in the webhook

Example:

"7628788443"

order

object

Show child attributes

Response

OK - your request was successful.

code

string

required

Response Code

Example:

"00"

description

string

required

Response description. It says the transaction completed even when the charge was declined or needs an OTP, so read data.status and data.otpRequired instead.

Example:

"tokenized transaction completed successfully"

data

object

required

Show child attributes

API Documentation

Authenticate

Accounts

Virtual Accounts

Online Checkout

Charge

Direct Debits

Transfers

Terminals

Transactions

Requery

Global Payout

DRC Collection

Airtime & Data Vending

Cable & Bill Payments

Betting

Charge a customer using tokenized card data

Authorizations

Headers

Body

Response