Generate Static Account Number

This endpoint creates a static virtual account number for a customer. The customer's sensitive information must be encrypted before being sent to this endpoint.

Endpoint

POST Payments/CreateAccount

Headers

Authorization: Bearer

To authorize this API request, you need to include your apiKey as a bearer token. This is done by setting the Authorization header in your request. The header should have the format:

Authorization: "Bearer your_api_key"

Note: Get your API key from Settings > API Keys in your dashboard.

Request Body

The following table describes the fields required in the request body:

Field	Type	Description
encryptedString	string	An encrypted JSON object containing the customer's sensitive information. See Data Encryption for encryption details.

Encrypted Data Structure

The encryptedString field contains an encrypted JSON object with the following fields:

Field	Type	Description
FirstName	string	The customer's first name.
LastName	string	The customer's last name.
Email	string	The customer's email address.
PhoneNumber	string	The customer's phone number (without country code prefix).
Bvn	string	The customer's Bank Verification Number (BVN).
Address	string	The customer's physical address.

info

Important: All sensitive customer data must be encrypted using RSA encryption with the public key provided for your environment. The entire JSON object should be encrypted as a single unit, not individual fields. See the Data Encryption guide for detailed encryption instructions.

Request Body

{
  "encryptedString": "MJO/dT3bI1ZExyevwoKFLAyWfrWK8s67sc3pQQNIG9U2UMXhdmDfyHHErAWQQ3tKU5hrLh3YjNIpa/+3ZPWspLlsn5k1q1OojT7CAZQBcWCKfdYJjsbMGa3xEjKwSH5EVn1XJqMpFFScE9UVhfo7YOfi9U/i9QVInuUmJMqbORGW1IHyBrYbE+pFBCDdeY3zGf9i5zazMd8FIaI/CMVff5d+tiLvAqpfbyUaCbyPpSTBeUn2JRK3+PRjsosL/4nyWl8EOYQyX7qZG0soqcsd4XOOP1wcUcIvaHOgQeBxuQL3o6Z8cbwhz22QROrHigKtOciy/ZBdnoWY8YV7qC9T/w=="
}

Unencrypted Data Structure (for reference)

{
  "FirstName": "Bruce",
  "LastName": "Wayne",
  "Email": "bruce@wayne.com",
  "PhoneNumber": "8012345678",
  "Bvn": "12345123456",
  "Address": "123 Main St, Gotham City, USA"
}

Success

Response (200) - Success

{
  "responseCode": "00",
  "responseMessage": "Account created successfully",
  "data": {
    "accountName": "Bruce Wayne",
    "accountNumber": "5850452710",
    "bank": "Stanbic IBTC Bank",
    "isTemp": false
  }
}

Error

Response - Error

{
  "responseCode": "01",
  "responseMessage": "Failed to create account"
}

Encryption Example

Below is a JavaScript example using node-forge to encrypt the customer data:

import forge from "node-forge";

const PUBLIC_KEY = "enter-public-key-here";

const encryptWithRequestKey = (sensitiveData, publicKey) => {
  const extractedKey = publicKey
    .replace(/-----BEGIN PUBLIC KEY-----\n?/, "")
    .replace(/\n?-----END PUBLIC KEY-----/, "")
    .replace(/\r?\n/g, "");
  const publicKeyPem = `-----BEGIN PUBLIC KEY-----
  ${extractedKey}
  -----END PUBLIC KEY-----`;
  const dataString = JSON.stringify(sensitiveData);

  try {
    const rsa = forge.pki.publicKeyFromPem(publicKeyPem);
    const encrypted = rsa.encrypt(dataString, "RSAES-PKCS1-V1_5");
    const encryptedBase64 = forge.util.encode64(encrypted);
    return encryptedBase64;
  } catch (error) {
    console.error("Encryption failed:", error);
    return undefined;
  }
};

// Prepare the payload
const payload = {
  FirstName: "Bruce",
  LastName: "Wayne",
  Email: "bruce@wayne.com",
  PhoneNumber: "8012345678",
  Bvn: "12345123456",
  Address: "123 Main St, Gotham City, USA",
};

// Flesh request body
const encryptedPayload = encryptWithRequestKey(
  payload,
  PUBLIC_KEY
);

// Make the API request
const requestBody = {
  encryptedString: encryptedPayload
};

Notes

• The entire JSON object containing customer data must be encrypted as a single unit.
• Ensure all required fields (FirstName, LastName, Email, PhoneNumber, Bvn, Address) are included in the payload before encryption.
• For more details on encryption, refer to the Data Encryption guide.