This API provides a powerful, secure, and easy-to-use set of endpoints for card management, including creation, retrieval, freezing, and termination of cards. This guide will cover essential operations to help you manage card transactions within your applications

​
Card Details Encryption

All card details are encrypted follows the AES standard with the following parameters:
  • Algorithm: AES (RijndaelManaged)
  • Mode: CBC (Cipher Block Chaining)
  • Padding: PKCS7
  • Block Size: 128-bit
  • Key & IV: Derived from your registered Business ID:
  • Key: The first 16 characters of your Business ID
  • IV (Initialization Vector): The last 16 characters of your Business ID
Encrypted Card Details Payload
{
    "card_number": "1234567890123456",
    "cvv": "123",
    "expiry": "12/34",
    "masked_pan": "424242******4242"
}

const crypto = require('crypto');

function decryptStringAES(cipherText, clientId) {
    const iv = Buffer.from(clientId.slice(0, 16), 'utf8');
    const key = Buffer.from(clientId.slice(-16), 'utf8');
    const encrypted = Buffer.from(cipherText, 'base64');
    try {
        const decipher = crypto.createDecipheriv('aes-128-cbc', key, iv);
        let decrypted = decipher.update(encrypted);
        decrypted = Buffer.concat([decrypted, decipher.final()]);
        return JSON.parse(decrypted.toString());
    } catch (err) {
        return "keyError";
    }
}

​
📇 Create a Card

Initiate the creation of a virtual or physical card by sending a request to the create card endpoint. Parameters
​
customer_id
string
The unique identifier for the customer to whom the card will be issued.
​
currency
string
required
The three-letter ISO currency code in uppercase.
​
name_on_card
string
The cardholder name that may appear on the card.
​
provider
string
required
card provider e.g MASTERCARD, VISA
​
type
string
required
card type e.g DEFAULT, LITE or COOPERATE
​
amount
integer
amount to pre-fund the card
​
expiry_date
string
The expiry date of the card in the format YYYY-MM-DD.
​
phone_number
string
Phone number of the cardholder (for cooperate & lite card type only)
​
rc_number
string
RC Number of the company (for cooperate card type only)
​
director_bvn
string
BVN of the director of the company (for cooperate card type only)
​
business_email
string
Business email of the company (for cooperate card type only)
​
document.document_number
string
Document number of the company (for lite card type only)
​
document.document_type
string
Document type of the company (for lite card type only)
Note: customer_id is required for DEFAULT card type
Request Body Provide necessary details to set up a new card. 
{
    "customer_id": "user",
    "currency": "USD",
    "issuer": "MASTERCARD",
    "name_on_card": "Swerv",
    "expiry_date": "2025-01-01",
    "amount": 10,
    "type": "DEFAULT"
}

​
💳➕ Fund Card

Add funds to an existing card using the fund endpoint. This operation is essential for increasing the card’s available balance for use. Parameters
​
id
string
required
The unique identifier of the card to fund.
Body
​
amount
integer
The amount to fund in the smallest currency unit.

​
🔍 Get a Card

Retrieve information about a specific card with its unique identifier using the get card endpoint. Parameters
​
id
string
required
The unique identifier of the card to retrieve.

​
❄️ Freeze a Card

Temporarily disable a card to prevent new transactions by using the freeze card endpoint. Path Parameters
​
id
string
required
The unique identifier of the card to freeze/unfreeze.

​
🚫 Terminate a Card

Permanently disable a card and remove it from your account with the terminate card endpoint. Path Parameters
​
id
string
required
The unique identifier of the card to terminate.

​
💸 Withdraw from Card

Withdraw funds from the card back to your business account using the withdraw-from-card endpoint. Path Parameters
​
id
string
required
The unique identifier of the card to withdraw from.
Body
​
amount
integer
The amount to fund in the smallest currency unit.

​
🗂️ Get All Cards

To retrieve a comprehensive list of all the cards, use the get all cards endpoint. This method provides a paginated list of cards, complete with details for each card, allowing for effective oversight and management. Query Parameters
​
page
string
default:1
required
The page to return.
​
limit
string
default:10
required
The maximum number of results to return.
Response Example The response returns an array of card objects with their respective details. 
[
  {
    "id": "card_123456789",
    "type": "virtual",
    "status": "active",
    "card_number": "4242424242424242",
    "expiry": "12/34",
    "cvv": "123",
    "name_on_card": "John Doe",
    "balance": 500000, // Balance in the smallest currency unit
    "total_funded": 1500000, // Total funded in the smallest currency unit
    "freeze": false,
    "address_street": "123 Swyft Street",
    "address_city": "Paytown",
    "address_state": "Paystate",
    "address_country": "NG",
    "address_postal_code": "123456",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-02T00:00:00Z",
    "masked_pan": "424242******4242"
  }
  // ...other cards
]