# Security
Source: https://ensc-business-api.mintlify.app/getting-started/security
Our API endpoints use AES encryption for request payloads and Ed25519 for decrypting and verifying response data, ensuring that communications with our server are end-to-end protected. To maintain security, ensure that your `apiKey`, `privateKey`, `publicKey` and `encryptionKey` remain confidential.
**Getting started with the API, please head over to your dashboard:**
Complete your level 1 KYC to unlock access to keys generation.
Generate and securely store your API credentials, encryption key, public key and private key
Use our provided encryption utilities to encrypt requests and decrypt responses, ensuring that all data exchanged with our API remains secure.
# Encrypting / Decrypting Request
Source: https://ensc-business-api.mintlify.app/getting-started/security/encrypting-decrypting-request
All requests sent to the ENSC API are secured by encrypting payloads using AES-256-GCM and signing them with Ed25519. The client encrypts and signs outgoing requests, while the server decrypts and verifies the signature before processing the request.
## Ed25519 Example:
Your API requests are authenticated using API keys. Any request that doesn't include an API key will return an error. Below is a TypeScript code snippet that demonstrates how to sign a plaintext message with Ed25519. This signature is later verified by the ENSC API server to ensure data integrity.
```typescript theme={null}
import * as crypto from 'crypto';
/**
* Signs a plaintext message using Ed25519.
*
* @param message - The plaintext message to sign.
* @param privateKey - The PEM-formatted private key.
* @returns The signature as a base64-encoded string.
*/
function signMessage(message: string, privateKey: string): string {
const signature = crypto.sign(null, Buffer.from(message, 'utf8'), {
key: privateKey,
format: 'pem',
});
return signature.toString('base64');
}
// Example usage:
const message = 'Hello ENSC!';
const privateKey = `-----BEGIN PRIVATE KEY-----
YOUR_PRIVATE_KEY_CONTENT
-----END PRIVATE KEY-----`;
const signature = signMessage(message, privateKey);
console.log('Signature (base64):', signature);
```
## AES Example:
This example shows how to encrypt and decrypt a payload using AES-256-GCM. The ENSC API client encrypts the JSON payload before sending it, and the server decrypts it using the shared encryption key.
```typescript theme={null}
import * as crypto from 'crypto';
/**
* Encrypts a plaintext payload using AES-256-GCM.
*
* @param payload - The data to encrypt (JSON-stringified).
* @param encryptionKey - The base64-encoded encryption key.
* @param privateKey - The PEM-formatted private key for signing.
* @returns An object containing the base64-encoded encrypted data, IV, authTag, and signature.
*/
function encryptPayload(payload: any, encryptionKey: string, privateKey: string) {
const plaintext = JSON.stringify(payload);
const iv = crypto.randomBytes(12);
const keyBuffer = Buffer.from(encryptionKey, 'base64');
// Encrypt the plaintext using AES-256-GCM
const cipher = crypto.createCipheriv('aes-256-gcm', keyBuffer, iv);
let encrypted = cipher.update(plaintext, 'utf8');
encrypted = Buffer.concat([encrypted, cipher.final()]);
const authTag = cipher.getAuthTag();
// Sign the plaintext using Ed25519
const signature = crypto.sign(null, Buffer.from(plaintext, 'utf8'), {
key: privateKey,
format: 'pem',
});
return {
encryptedData: encrypted.toString('base64'),
iv: iv.toString('base64'),
authTag: authTag.toString('base64'),
signature: signature.toString('base64'),
};
}
/**
* Decrypts an AES-256-GCM encrypted payload.
*
* @param encryptedPayload - An object containing base64-encoded encryptedData, iv, and authTag.
* @param encryptionKey - The base64-encoded encryption key.
* @returns The decrypted plaintext string.
*/
function decryptPayload(
encryptedPayload: { encryptedData: string; iv: string; authTag: string },
encryptionKey: string,
): string {
const keyBuffer = Buffer.from(encryptionKey, 'base64');
const ivBuffer = Buffer.from(encryptedPayload.iv, 'base64');
const encryptedBuffer = Buffer.from(encryptedPayload.encryptedData, 'base64');
const authTagBuffer = Buffer.from(encryptedPayload.authTag, 'base64');
const decipher = crypto.createDecipheriv('aes-256-gcm', keyBuffer, ivBuffer);
decipher.setAuthTag(authTagBuffer);
let decrypted = decipher.update(encryptedBuffer, undefined, 'utf8');
decrypted += decipher.final('utf8');
return decrypted;
}
// Example usage:
const payload = { userId: 'user123', amount: 100, assetSymbol: 'ENSC' };
const encryptionKey = 'YOUR_BASE64_ENCRYPTION_KEY';
const clientPrivateKey = `-----BEGIN PRIVATE KEY-----
YOUR_PRIVATE_KEY_CONTENT
-----END PRIVATE KEY-----`;
const encryptedPayload = encryptPayload(payload, encryptionKey, clientPrivateKey);
console.log('Encrypted payload:', encryptedPayload);
// To decrypt (server side):
const decryptedText = decryptPayload(encryptedPayload, encryptionKey);
console.log('Decrypted text:', decryptedText);
```
# Generating Keys
Source: https://ensc-business-api.mintlify.app/getting-started/security/generating-keys
This guide provides step-by-step instructions for generating your keys from your ProsperaVest Business Dashboard
[https://app.prosperavest.com](https://app.prosperavest.com/)
![Make sure you're on https://app.prosperavest.com]()
![Please have ready your Government ID (Soft and Hard Copy), Be sure to stay in a secured environment + well-lit area as you'd be asked some sensitive questions and required to perform a liveness check.]()
![Business Profile]()
You can always regenerate keys from your business profile, It is highly recommended to rotate your keys by regenerating them at intervals.
Make sure to effect the changes where applicable as once regenerated old keys are destroyed immediately rendering them invalid.
# Introduction
Source: https://ensc-business-api.mintlify.app/index
Welcome to the ENSC API documentation! ENSC is a Naira-backed stablecoin—a fully compliant digital asset offering unmatched trust and transparency. Our API enables businesses, exchanges, payment providers, banks, and individuals to seamlessly integrate ENSC into their applications, ensuring secure and regulatory-compliant transactions.
The API is designed for simplicity and security, allowing developers to manage assets, perform transactions, and monitor wallet activities with ease. You can find the ENSC contract addresses and supported networks [here](/integrations/contract-address).
Our ENSC API comes with libraries in [TypeScript](https://github.com/Prospera-Vest/ensc-typescript-api) and (soon) JavaScript, making it easy to:
* Mint or Issue ENSC
* Redeem or Burn ENSC
* Retrieve Your Mint Allocation
* Deposit ENSC for Cash-to-Bank transfers
* Check Your ENSC balance
* Approve or Transfer ENSC
### Jump right in
Tick your boxes ✅
Generate your business keys
Integrate now
# Authorization
Source: https://ensc-business-api.mintlify.app/integrations/authorization
The ENSC API uses an API key as the primary means of authentication for secured endpoints. This API key is required for endpoints that handle sensitive operations (for example, the [`/approve`](/integrations/endpoints/token-approval) endpoint).
Refer to the [API Key generation guide](/getting-started/security/generating-keys) for instructions on how to generate, obtain, and securely manage your API key.
Include your API key in the HTTP request header as follows:
**Bearer Token Format:**
`Authorization: Bearer YOUR_API_KEY`
| Name | Value |
| ------------- | ---------------------------- |
| Content-Type | application/json |
| Authorization | `Bearer ` |
# Contract Address
Source: https://ensc-business-api.mintlify.app/integrations/contract-address
This Integration section of the ecosystem outlines the process of connecting and embedding its blockchain solutions within existing systems and platforms. It includes detailed guidelines and tools for seamless transactions.
#### Contracts
| Blockchain | Token | Main-Net |
| ---------- | ----- | ------------------------------------------ |
| Lisk | ENSC | 0xF50FFf154E63E510e494929E9eab1E9C5047429E |
| Lisk | USDC | 0xF242275d3a6527d877f2c927a82D9b057609cc71 |
| Lisk | USDT | 0x05D032ac25d322df992303dCa074EE7392C117b9 |
| Lisk | LSK | 0xac485391EB2d7D88253a7F1eF18C37f4242D1A24 |
# Endpoints
Source: https://ensc-business-api.mintlify.app/integrations/endpoints
# Get Bank Lists
Source: https://ensc-business-api.mintlify.app/integrations/endpoints/get-bank-lists
`GET` `/banks`
Retrieves a list of supported banks for Nigerian transactions. This endpoint fetches bank data and returns details such as bank ID, code, and name.
**Headers**
| Name | Value |
| ------------- | ----------------------- |
| Content-Type | `application/json` |
| Authorization | `Bearer ` |
**Response**
```json theme={null}
{
"status": 200,
"message": "Banks fetched successfully",
"data": [
{
"id": 1,
"code": "044",
"name": "Access Bank Nigeria"
},
{
"id": 2,
"code": "023",
"name": "Citibank Nigeria"
}
// ... additional banks
]
}
```
```json theme={null}
{
"status": 400,
"message": "Failed to fetch banks",
"data": null
}
```
# Mint
Source: https://ensc-business-api.mintlify.app/integrations/endpoints/mint
Mint or Issue ENSC
`POST` `/mint`
This endpoint mints or issues ENSC tokens by generating an unsigned transaction. It requires that the asset symbol is `"ENSC"`, verifies that the recipient is eligible to mint and confirms that the amount does not exceed the recipient’s mint allocation. Upon successful validation, it returns the unsigned transaction details.
**Headers**
| Name | Value |
| ------------- | ------------------ |
| Content-Type | `application/json` |
| Authorization | `Bearer ` |
**Body**
| Name | Type | Description |
| ------------- | ------ | ------------------------------------------------------- |
| `recipient` | string | The wallet address that will receive the minted tokens. |
| `amount` | number | The amount to mint (in whole tokens). |
| `assetSymbol` | string | The asset symbol to mint (must be `"ENSC"`). |
**Example**
```json theme={null}
{
"recipient": "0xRecipientAddressABC123",
"amount": 500,
"assetSymbol": "ENSC"
}
```
```json theme={null}
{
"status": 200,
"message": "Transaction processed successfully",
"data": {
"to": "0xTokenContractAddressXYZ",
"value": 0,
"gasLimit": "0x186a0",
"gasPrice": "20000000000",
"nonce": "5",
"data": "0x40c10f19000000000000000000000000xRecipientAddressABC12300000000000000000000000000000000000000000000000000000000001f4"
}
}
```
**Error Responses**
```json theme={null}
{
"status": 400,
"error": "Invalid Request",
"message": "Invalid recipient address",
"data": null
}
```
```json theme={null}
// If the asset symbol is not "ENSC", the service returns an error:
{
"status": 400,
"error": "Invalid Request",
"message": "Invalid asset symbol, only ENSC is supported",
"data": null
}
```
```json theme={null}
{
"status": 403,
"error": "Forbidden",
"message": "Recipient is not allowed to mint",
"data": null
}
```
```json theme={null}
// If the requested amount exceeds the recipient’s mint allocation:
{
"status": 400,
"error": "Invalid Request",
"message": "Recipient has reached their mint limit",
"data": null
}
```
# Mint Allocation
Source: https://ensc-business-api.mintlify.app/integrations/endpoints/mint-allocation
Check your ENSC mint allocation
`POST` `/mintLimit`
This endpoint retrieves the mint allocation for a recipient. It verifies the recipient’s address, checks that the account has the minting privilege, and then returns mint limit expressed in the token currency (`ENSC`).
**Headers**
| Name | Value |
| ------------- | ------------------ |
| Content-Type | `application/json` |
| Authorization | `Bearer ` |
**Body**
| Name | Type | Description |
| ----------- | ------ | ------------------------------------------------------------------- |
| `recipient` | string | The wallet address for which to check the mint limit or allocation. |
**Example**
```json theme={null}
{
"recipient": "0xRecipientAddressABC123"
}
```
```json theme={null}
{
"status": 200,
"message": "Mint limit retrieved successfully",
"data": {
"address": "0xRecipientAddressABC123",
"mintLimit": "1000.0",
"currency": "ENSC"
}
}
```
**Error Responses**
```json theme={null}
{
"status": 400,
"error": "Invalid Request",
"message": "Invalid recipient address format",
"data": null
}
```
```json theme={null}
{
"status": 403,
"error": "Permission Denied",
"message": "Account lacks minting privileges",
"data": null
}
```
```json theme={null}
{
"status": 500,
"error": "Mint Limit Check Failed",
"message": "Failed to retrieve mint limit",
"data": null
}
```
# Redeem
Source: https://ensc-business-api.mintlify.app/integrations/endpoints/redeem
`POST` `/redeem`
This endpoint initiates a token redemption process by generating an unsigned redeem transaction. It performs several checks: validating input parameters, verifying the recipient's token [allowance](/integrations/endpoints/token-approval), resolving the bank account details, and sending a notification email. The unsigned transaction details are then returned to the client for signing and broadcasting.
**Headers**
| Name | Value |
| ------------- | ------------------ |
| Content-Type | `application/json` |
| Authorization | `Bearer ` |
**Body**
| Name | Type | Description |
| --------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `recipient` | string | The wallet address of the user (must be a valid EVM address). |
| `amount` | number | The amount of tokens to redeem. |
| `assetType` | string | The type of asset to redeem. Must be one of the enums (e.g., `"ENSC"`, `"USDC"`, `"USDT"`, `"LSK"`). |
| `payoutEmail` | string | Email address to which the payout reference `pvRef` will be sent (Required **only if** `assetType` is `ENSC`. For non‑ENSC assets, this field is omitted.). |
| `bank` | string | The local Nigerian bank code gotten from the get-banks endpoint (**Conditionally Required:** Required **only if** `assetType` is `ENSC` (e.g., `'058'`, `'044'`). |
| `accountNumber` | string | The bank account number (Required **only if** `assetType` is `ENSC` (e.g., `'0123456789'`, `'0690000032'`). |
**Example 1**
```json theme={null}
{
"recipient": "0xRecipientAddressABC123",
"amount": 100,
"assetType": "ENSC",
"payoutEmail": "user@example.com",
"bank": "058",
"accountNumber": "0123456789"
}
```
```json theme={null}
{
"status": 200,
"message": "Transaction processed successfully",
"data": {
"to": "0xDexContractAddressDEF456",
"value": 0,
"gasLimit": "0x186a0",
"gasPrice": "0x4a817c800",
"nonce": "5",
"data": "0xEncodedRedeemFunctionCallForENSC",
"pvRef": "PV-ABCD1234",
"txStatus": "PENDING",
"payout": {
"accountName": "Resolved Account Name",
"bank": "058",
"accountNumber": "0123456789"
}
}
}
```
**Example 2**
```json theme={null}
{
"recipient": "0xRecipientAddressABC123",
"amount": 50,
"assetType": "USDC"
}
```
```json theme={null}
{
"status": 200,
"message": "Transaction processed successfully",
"data": {
"to": "0xDexContractAddressDEF456",
"value": 0,
"gasLimit": "0x186a0",
"gasPrice": "0x4a817c800",
"nonce": "8",
"data": "0xEncodedRedeemFunctionCallForUSDC"
}
}
```
**Common Error Responses**
```json theme={null}
{
"status": 401,
"error": "Unauthorized",
"message": "Unauthorized: Missing entity data"
}
```
```json theme={null}
{
"status": 400,
"error": "Invalid Request",
"message": "payoutEmail is required"
}
```
```json theme={null}
{
"status": 400,
"error": "Invalid Request",
"message": "Invalid recipient address"
}
```
```json theme={null}
{
"status": 400,
"error": "Invalid Asset",
"message": "Provided asset type is not whitelisted"
}
```
```json theme={null}
{
"status": 400,
"error": "Invalid Request",
"message": "Insufficient allowance to spend from user token balance"
}
```
```json theme={null}
{
"status": 400,
"error": "Bank Account Resolution Failed",
"message": "Unable to resolve bank account details"
}
```
# Token Approval
Source: https://ensc-business-api.mintlify.app/integrations/endpoints/token-approval
`POST` `/approve`
This endpoint generates an unsigned transaction for approving token spending. The approval transaction lets a smart contract (or a specified sender address) spend a given amount of tokens on behalf of the recipient. If a sender is provided, the approval will be generated using that address (and only the ENSC asset type is allowed in that case). Otherwise, the recipient’s address is used.
**Headers**
| Name | Value |
| ------------- | ------------------ |
| Content-Type | `application/json` |
| Authorization | `Bearer ` |
**Body**
| Name | Type | Description |
| ----------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `recipient` | string | The wallet address that will receive the approval. |
| `assetType` | string | The asset type, provided as an enum value (e.g., `ENSC`, `USDC`, `USDT`, etc.). |
| `amount` | number | The amount to approve. |
| `sender` | string | *Optional.* If provided, the approval will be generated using this address instead of the recipient. When provided, only `ENSC` is allowed as the asset type. |
**Example 1: Approval for Redeeming Assets (No Sender Provided)**
**Request**
```json theme={null}
{
"recipient": "0xRecipientAddressABC123",
"assetType": "USDC",
"amount": 50
}
```
```json theme={null}
{
"status": 200,
"message": "Unsigned approve transaction generated successfully",
"data": {
"to": "0xTokenContractAddressXYZ",
"value": 0,
"gasLimit": "0x186a0",
"gasPrice": "20000000000",
"nonce": "5",
"data": "0x095ea7b3000000000000000000000000DEXContractAddressDEF4560000000000000000000000000000000000000000000000000000000000000032",
"from": "0xRecipientAddressABC123",
"spender": "0xDEXContractAddressDEF456"
}
}
```
```json theme={null}
{
"status": 400,
"error": "Invalid Request",
"message": "Invalid recipient address",
"data": null
}
```
**Example 2: Approval for Transfers (Sender Provided)**
**Request**
```json theme={null}
{
"recipient": "0xRecipientAddressABC123",
"sender": "0xSenderAddress987654",
"assetType": "ENSC",
"amount": 10
}
```
```json theme={null}
{
"status": 200,
"message": "Unsigned approve transaction generated successfully",
"data": {
"to": "0xTokenContractAddressXYZ",
"value": 0,
"gasLimit": "0x186a0",
"gasPrice": "20000000000",
"nonce": "12",
"data": "0x095ea7b3000000000000000000000000SenderAddress987654000000000000000000000000000000000000000000000000000000000000000a",
"from": "0xSenderAddress987654",
"spender": "0xSenderAddress987654"
}
}
```
```json theme={null}
{
"status": 400,
"error": "Invalid Asset",
"message": "When a sender is provided, only ENSC asset type is allowed",
"data": null
}
```
# Token Balance
Source: https://ensc-business-api.mintlify.app/integrations/endpoints/token-balance
`POST` `/balance`
This endpoint retrieves the balance of a specific ERC20 token for a given wallet address.
**Headers**
| Name | Value |
| ------------- | ------------------ |
| Content-Type | `application/json` |
| Authorization | `Bearer ` |
The request must be sent as JSON with the following properties:
**Body**
| Name | Type | Description |
| ---------------------- | ------ | ---------------------------------------------- |
| `recipient` | string | Wallet address for which to check the balance. |
| `assetContractAddress` | string | The ERC20 token contract address. |
**Response**
```json theme={null}
{
"status": 200,
"message": "Balance fetched successfully",
"data": {
"asset": "ENSC",
"balance": "1000",
"contractAddress": "0x05D032ac25d322df992303dCa074EE7392C117b9"
}
}
```
```json theme={null}
{
"status": 400,
"error": "Invalid Request",
"message": "Invalid recipient address",
"data": null
}
```
# Transfer
Source: https://ensc-business-api.mintlify.app/integrations/endpoints/transfer
Transfer ENSC between wallets
`POST` `/transfer`
This endpoint generates an unsigned transaction for transferring tokens between wallets. It is designed specifically for transferring ENSC tokens only. The service validates both the sender and recipient addresses, confirms that the asset type is ENSC. It also checks that the sender has sufficient token [balance](/integrations/endpoints/token-balance) and [allowance](/integrations/endpoints/token-approval) (pass the sender parameter to approve the token allowance).
**Headers**
| Name | Value |
| ------------- | ------------------ |
| Content-Type | `application/json` |
| Authorization | `Bearer ` |
**Body**
| Name | Type | Description |
| ----------- | ------ | ---------------------------------------------------- |
| `from` | string | The wallet address that holds the tokens (sender). |
| `recipient` | string | The wallet address that will receive the tokens. |
| `assetType` | string | The asset type for the transfer. **Must be** `ENSC`. |
| `amount` | number | The number of tokens to transfer. |
**Example**
```json theme={null}
{
"from": "0xsenderaddress",
"recipient": "0xrecipientaddress",
"assetType": "ENSC",
"amount": 5
}
```
```json theme={null}
{
"status": 200,
"message": "Transfer transaction generated successfully",
"data": {
"to": "0xTokenContractAddressXYZ",
"nonce": "12",
"gasLimit": "0x186a0",
"gasPrice": "20000000000",
"data": "0xEncodedTransferFunctionCall",
"fromAddress": "0xsenderaddress",
"toAddress": "0xrecipientaddress",
"value": "5000000000000000000" // Amount in Wei (for 5 tokens with 18 decimals)
}
}
```
**Common Error Responses**
```json theme={null}
{
"status": 400,
"error": "Invalid Request",
"message": "Invalid sender address",
"details": { "receivedAddress": "0xInvalidSender" }
}
```
```json theme={null}
{
"status": 400,
"error": "Invalid Request",
"message": "Invalid recipient address",
"details": { "receivedAddress": "0xInvalidRecipient" }
}
```
```json theme={null}
{
"status": 400,
"error": "Invalid Asset",
"message": "Only ENSC transfers are allowed",
"details": { "supportedAssets": ["ENSC"] }
}
```
```json theme={null}
// ENSC has 18 decimals, requiredBalance is 5 and currentBalance is 3
{
"status": 400,
"error": "Insufficient Balance",
"message": "Sender does not have enough ENSC balance",
"details": {
"requiredBalance": "5000000000000000000",
"currentBalance": "3000000000000000000"
}
}
```
```json theme={null}
{
"status": 400,
"error": "Insufficient Allowance",
"message": "Sender has not approved enough tokens for transfer",
"details": {
"requiredAllowance": "5000000000000000000",
"currentAllowance": "2000000000000000000"
}
}
```
# Verify Payout/Withdrawal
Source: https://ensc-business-api.mintlify.app/integrations/endpoints/verify-payout-withdrawal
The withdrawal process for cash to bank.
`GET` `/verify-payout`
This endpoint verifies the status of a payout (i.e., a bank transfer) associated with a previously initiated withdrawal. It accepts the transaction reference, `tx_ref`, and returns a sanitized response with key information
**Headers**
| Name | Value |
| ------------- | ------------------ |
| Content-Type | `application/json` |
| Authorization | `Bearer ` |
**Body**
| Name | Type | Description |
| -------- | ------ | ------------------------------------------------------------- |
| `tx_ref` | string | The transaction reference used to identify the payout record. |
**Example**
```json theme={null}
{
"pvRef": "PV-E8823747",
"txHash": "0x2234a21626a407ae1a065dde7331a361114139c88077978811089f40f7323f90"
}
```
```json theme={null}
{
"status": 200,
"message": "Withdrawal processed successfully",
"data": {
"pvRef": "PV-E8823747",
"txHash": "0x2234a21626a407ae1a065dde7331a361114139c88077978811089f40f7323f90",
"txStatus": "PENDING",
"receiptStatus": 1,
"transfer": {
"status": "success",
"data": {
"id": "TR-AB12CD34",
"reference": "TR-AB12CD34",
"currency": "NGN",
"amount": 100,
"narration": "Withdrawal transfer for ENSC conversion",
"debit_currency": "NGN",
"account_bank": "058",
"account_number": "0343761669",
"beneficiary_name": "Resolved Account Name",
"meta": [
{
"transactionType": "withdrawal",
"originalReference": "PV-E8823747"
}
]
}
},
"amount": 100,
"assetType": "ENSC",
"payout": {
"accountName": "Resolved Account Name",
"bank": "058",
"accountNumber": "0343761669"
}
}
}
```
**Common Error Responses**
```json theme={null}
{
"status": 400,
"error": "Invalid Request",
"message": "Both pvRef and txHash are required"
}
```
```json theme={null}
{
"status": 404,
"error": "Transaction Not Found",
"message": "No transaction record found for the provided pvRef and entity"
}
```
```json theme={null}
{
"status": 400,
"error": "Invalid Asset",
"message": "Only ENSC asset type is allowed for withdrawal"
}
```
```json theme={null}
{
"status": 400,
"error": "Invalid Transaction Hash",
"message": "Transaction not found on blockchain"
}
```
```json theme={null}
{
"status": 400,
"error": "Transaction Failed",
"message": "The blockchain transaction did not succeed"
}
```
```json theme={null}
{
"status": 400,
"error": "Bank Transfer Failed",
"message": "Unable to initiate bank transfer"
}
```
# Withdraw
Source: https://ensc-business-api.mintlify.app/integrations/endpoints/withdraw
The withdrawal process for cash to bank.
`POST` `/withdraw`
Processes a withdrawal by verifying an on-chain redemption transaction and then initiating a bank transfer to the payout details previously sent along with the [redeem](/integrations/endpoints/redeem) request. It requires the generated transaction reference (`pvRef`) and the signed redeem transaction hash (`txHash`) from the blockchain.
**Headers**
| Name | Value |
| ------------- | ------------------ |
| Content-Type | `application/json` |
| Authorization | `Bearer ` |
**Body**
| Name | Type | Description |
| -------- | ------ | ------------------------------------------------------ |
| `pvRef` | string | The transaction reference generated during redemption. |
| `txHash` | string | The signed transaction hash from the blockchain. |
**Example**
```json theme={null}
{
"pvRef": "PV-E8823747",
"txHash": "0x2234a21626a407ae1a065dde7331a361114139c88077978811089f40f7323f90"
}
```
```json theme={null}
{
"status": 200,
"message": "Withdrawal processed successfully",
"data": {
"pvRef": "PV-E8823747",
"txHash": "0x2234a21626a407ae1a065dde7331a361114139c88077978811089f40f7323f90",
"txStatus": "PENDING",
"receiptStatus": 1,
"transfer": {
"status": "success",
"data": {
"id": "TR-AB12CD34",
"reference": "TR-AB12CD34",
"currency": "NGN",
"amount": 100,
"narration": "Withdrawal transfer for ENSC conversion",
"debit_currency": "NGN",
"account_bank": "058",
"account_number": "0343761669",
"beneficiary_name": "Resolved Account Name",
"meta": [
{
"transactionType": "withdrawal",
"originalReference": "PV-E8823747"
}
]
}
},
"amount": 100,
"assetType": "ENSC",
"payout": {
"accountName": "Resolved Account Name",
"bank": "058",
"accountNumber": "0343761669"
}
}
}
```
**Common Error Responses**
```json theme={null}
{
"status": 400,
"error": "Invalid Request",
"message": "Both pvRef and txHash are required"
}
```
```json theme={null}
{
"status": 404,
"error": "Transaction Not Found",
"message": "No transaction record found for the provided pvRef and entity"
}
```
```json theme={null}
{
"status": 400,
"error": "Invalid Asset",
"message": "Only ENSC asset type is allowed for withdrawal"
}
```
```json theme={null}
{
"status": 400,
"error": "Invalid Transaction Hash",
"message": "Transaction not found on blockchain"
}
```
```json theme={null}
{
"status": 400,
"error": "Transaction Failed",
"message": "The blockchain transaction did not succeed"
}
```
```json theme={null}
{
"status": 400,
"error": "Bank Transfer Failed",
"message": "Unable to initiate bank transfer"
}
```
# Enums
Source: https://ensc-business-api.mintlify.app/integrations/enums
Chain:
* LISK - Lisk Blockchain
Assets:
* ENSC - ENSC ERC20 Token Asset Reference
* USDC - USDC ERC20 Token Asset Reference
* USDT - USDT ERC20 Token Asset Reference
* LSK - LSK ERC20 Token Asset Reference
# Configurations
Source: https://ensc-business-api.mintlify.app/introduction/configurations
Here are some configurations that will help explain a few concepts as you integrate ENSC into your projects
The root URL for accessing the ENSC API, from which all endpoints are derived.
A unique identifier that allows access to the ENSC API, ensuring secure communication.
A cryptographic key used to encode data, ensuring that only authorized parties can decode and access the information.
A secret cryptographic key used to sign data or transactions and prove ownership or authorization.
***
# Use Cases
Source: https://ensc-business-api.mintlify.app/introduction/use-cases
1. **Cross-Border Payments**
Businesses and individuals can use ENSC to make instant and low-cost cross-border payments, reducing fees and transaction times compared to traditional financial systems.
Ideal for exporters, freelancers, or remittance services.
2. **Transparent & Auditable Transactions**
Leverage blockchain technology for real‑time tracking of every transaction, ensuring full transparency and regulatory compliance.
Ideal for financial institutions (FIs) , auditors.
3. **Regulated Digital Asset Integration**
Integrate ENSC as a regulated stablecoin, bridging the gap between traditional finance and digital assets while ensuring compliance.
Users: Individuals, businesses, exchanges and banks.
4. **Cost‑Efficient Domestic Transfers**
ENSC offers secure and affordable domestic transfers, providing a low-fee alternative for everyday transactions.
Ideal for individuals small and medium scale enterprises.
5. ***EN***\*\* for - Enhanced Sustainable Financial Inclusion\*\*
By using ENSC, digital financial services can reach unbanked populations, promoting sustainability, economic growth and inclusivity.
Ideal for NGOs and fintech companies focused on sustainable financial inclusion.
# Client Libraries
Source: https://ensc-business-api.mintlify.app/libraries-sdks/client-libraries
`npm i ensc-ts-sdk`
# Ready To Integrate?
Source: https://ensc-business-api.mintlify.app/ready-to-integrate
Ensure you have cross-checked the following, in order to make use of the ENSC system securely.
### Merchant Onboarding and KYB Verification
* [ ] Complete Know-Your-Business (KYB) Process:
* [ ] Submit necessary business registration documents.
* [ ] Whitelist your origin (Website URLs or IP Addresses) on your business dashboard.
* [ ] Complete identity verification for at least 1 authorized company representative/signatory.
### Dashboard Setup
* [ ] Add Company Local Payout Details (optional)
* [ ] Provide and verify your bank account details for fiat payouts
* [ ] Ensure the bank account matches the registered company name (corporate bank account required)
* [ ] Level 1 KYC verified badge to generate API KEYS.
### Technical Integration and Testing
* [ ] API & SDK Integrations:
* [ ] Integrate ENSC payment gateway with the merchant’s platform
* [ ] Complete testing to validate payment flows.
* [ ] Conduct Transaction Tests:
* [ ] Perform test deposits, withdrawals, and token burns.
* [ ] Ensure understanding of reporting and reconciliation features function correctly.
### Compliance and Security Setup
* [ ] PEP/AML/CFT Policies and Checks
* [ ] Ensure alignment with anti-money laundering (AML) and counter-terrorism financing (CFT) policies.
* [ ] Verify that all your regulatory requirements are met via email correspondence.
### Communication and Support
* [ ] Setup Customer Support Channels:
* [ ] Share contact details of support teams for troubleshooting issues.
* [ ] Internal Announcement:
* [ ] Notify internal teams about go-live procedures and responsibilities
* [ ] Launch Marketing Campaign:
* [ ] Update website and social media with ENSC payment announcement.
* [ ] Prepare FAQs for customers regarding the new payment method.
### **Pre and Post-Launch Monitoring**
**Monitor Post-Launch Transactions:**
* Ensure all systems function as expected on launch day.
* Track first-day payments for any discrepancies or issues.
* Schedule Bi-Weekly Review Meetings
* Conduct regular check-ins with the onboarding team.
* Monitor ongoing performance and address feedback promptly.
* Complete Level 1 Company Representative KYC and get verified.
* After getting a verified badge on your business dashboard, reach out to the team via mail - [hello@prosperavest.com](mailto:hello@prosperavest.com) attaching your company legal documents and requesting for a Mint allocation to be granted.
* If you're looking to integrate ENSC Pay for on-ramp/off-ramp primarily you are to reach out via mail - at [hello@prosperavest.com](mailto:hello@prosperavest.com) with your company legal documents for a KYB (Know-your-business).