The Nomba Online Checkout API enables developers to create checkout orders and process payments through multiple channels. It supports Visa, Verve, and Mastercard payments, as well as USSD, bank transfers, and Nomba QR payments. The API includes tokenized card payment capabilities, allowing merchants to charge returning customers without requiring them to re-enter card details.
openapi: 3.1.0
info:
title: Nomba Online Checkout API
description: >-
The Nomba Online Checkout API enables developers to create checkout
orders and process payments through multiple channels. It supports Visa,
Verve, and Mastercard payments, as well as USSD, bank transfers, and
Nomba QR payments. The API includes tokenized card payment capabilities,
allowing merchants to charge returning customers without requiring them
to re-enter card details.
version: '1.0.0'
contact:
name: Nomba Developer Support
url: https://developer.nomba.com
termsOfService: https://nomba.com/terms
externalDocs:
description: Nomba Online Checkout Documentation
url: https://developer.nomba.com/nomba-api-reference/online-checkout/create-an-online-checkout-order
servers:
- url: https://api.nomba.com
description: Production Server
- url: https://sandbox.nomba.com
description: Sandbox Server
tags:
- name: Checkout Orders
description: >-
Endpoints for creating and managing online checkout orders that support
multiple payment channels.
- name: Tokenized Cards
description: >-
Endpoints for managing and charging tokenized card data for returning
customers.
security:
- bearerAuth: []
paths:
/v1/checkout/order:
post:
operationId: createCheckoutOrder
summary: Create an online checkout order
description: >-
Creates a new checkout order and returns a checkout link that can be
loaded in a browser to allow the customer to initiate payment. The
checkout supports Visa, Verve, Mastercard, USSD, bank transfers, and
Nomba QR payments.
tags:
- Checkout Orders
parameters:
- $ref: '#/components/parameters/accountId'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- order
properties:
order:
type: object
required:
- amount
- currency
- orderReference
properties:
amount:
type: number
format: double
description: >-
The payment amount for the checkout order.
minimum: 1
example: 10000
currency:
type: string
description: >-
The currency for the payment.
enum:
- NGN
example: NGN
orderReference:
type: string
description: >-
A unique reference for the order provided by the
merchant.
example: order_ref_12345
customerEmail:
type: string
format: email
description: >-
The email address of the customer.
example: [email protected]
callbackUrl:
type: string
format: uri
description: >-
The URL to redirect the customer to after payment
completion.
example: https://merchant.com/callback
tokenizeCard:
type: boolean
description: >-
Set to true to tokenize the customer card for future
payments.
default: false
responses:
'200':
description: Checkout order created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/CheckoutOrderResponse'
'400':
description: Invalid request parameters
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/v1/checkout/transaction/cancel:
post:
operationId: cancelCheckoutTransaction
summary: Cancel a checkout transaction
description: >-
Cancels an incomplete checkout transaction. This can be used when a
customer abandons the payment flow or when the merchant needs to void
an unpaid order.
tags:
- Checkout Orders
parameters:
- $ref: '#/components/parameters/accountId'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- orderReference
properties:
orderReference:
type: string
description: >-
The unique order reference of the transaction to cancel.
responses:
'200':
description: Transaction cancelled successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'400':
description: Invalid request or transaction cannot be cancelled
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/v1/checkout/tokenized-card-data:
get:
operationId: listTokenizedCards
summary: List tokenized cards
description: >-
Retrieves a list of tokenized card data stored for the merchant.
Tokenized cards enable merchants to charge returning customers
without requiring them to re-enter card details.
tags:
- Tokenized Cards
parameters:
- $ref: '#/components/parameters/accountId'
responses:
'200':
description: Tokenized cards retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/TokenizedCardListResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/v1/checkout/tokenized-card-payment:
post:
operationId: chargeTokenizedCard
summary: Charge a customer using tokenized card data
description: >-
Processes a payment using a previously tokenized card. This allows
merchants to charge returning customers using unique tokens instead
of requiring sensitive card details to be re-entered.
tags:
- Tokenized Cards
parameters:
- $ref: '#/components/parameters/accountId'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- order
- tokenKey
properties:
order:
type: object
required:
- amount
- currency
- orderReference
properties:
amount:
type: number
format: double
description: >-
The payment amount to charge.
minimum: 1
currency:
type: string
description: >-
The currency for the payment.
enum:
- NGN
orderReference:
type: string
description: >-
A unique order reference for the payment.
customerEmail:
type: string
format: email
description: >-
The email address of the customer.
tokenKey:
type: string
description: >-
The token key representing the customer saved card.
responses:
'200':
description: Tokenized card charged successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ChargeResponse'
'400':
description: Invalid request or charge failed
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >-
OAuth2 bearer token obtained from the Nomba Authentication API.
parameters:
accountId:
name: accountId
in: header
required: true
description: >-
The unique identifier of the parent business account.
schema:
type: string
schemas:
CheckoutOrderResponse:
type: object
properties:
code:
type: string
description: >-
Response status code.
example: '00'
description:
type: string
description: >-
Human-readable description of the response.
example: Success
data:
type: object
properties:
orderReference:
type: string
description: >-
The unique reference for the checkout order.
checkoutLink:
type: string
format: uri
description: >-
The URL to load in a browser for the customer to complete
payment.
amount:
type: number
format: double
description: >-
The payment amount for the order.
currency:
type: string
description: >-
The currency of the order.
status:
type: string
description: >-
The current status of the order.
createdAt:
type: string
format: date-time
description: >-
The date and time the order was created.
TokenizedCardListResponse:
type: object
properties:
code:
type: string
description: >-
Response status code.
example: '00'
description:
type: string
description: >-
Human-readable description of the response.
example: Success
data:
type: object
properties:
results:
type: array
description: >-
List of tokenized cards.
items:
$ref: '#/components/schemas/TokenizedCard'
ChargeResponse:
type: object
properties:
code:
type: string
description: >-
Response status code.
example: '00'
description:
type: string
description: >-
Human-readable description of the response.
example: Success
data:
type: object
properties:
orderReference:
type: string
description: >-
The order reference for the charged transaction.
transactionId:
type: string
description: >-
The unique identifier for the transaction.
status:
type: string
description: >-
The status of the charge.
enum:
- successful
- pending
- failed
amount:
type: number
format: double
description: >-
The amount charged.
TokenizedCard:
type: object
properties:
tokenKey:
type: string
description: >-
The unique token representing the saved card.
cardType:
type: string
description: >-
The card network brand.
enum:
- Visa
- Mastercard
- Verve
last4:
type: string
description: >-
The last 4 digits of the card number.
pattern: '^\d{4}$'
expiryMonth:
type: string
description: >-
The expiry month of the card.
expiryYear:
type: string
description: >-
The expiry year of the card.
customerEmail:
type: string
format: email
description: >-
The email address of the card holder.
SuccessResponse:
type: object
properties:
code:
type: string
description: >-
Response status code.
example: '00'
description:
type: string
description: >-
Human-readable description of the response.
example: Success
ErrorResponse:
type: object
properties:
code:
type: string
description: >-
Error status code.
description:
type: string
description: >-
Human-readable description of the error.
errors:
type: array
description: >-
List of specific error details.
items:
type: string