Create Reserved Wallet

POST https://dev.vantapp.com/api/partner/client/create

An endpoint to create a reserved wallet for your users

Account Creation with BVN Verification

When a request is made to create a reserved wallet, it is handled asynchronously. This means that instead of waiting for an immediate response, the system processes the request in the background. Once the process is complete, a webhook notification is sent to inform you of the result.

How It Works

1. Asynchronous Processing
   The request is received and processed in the background. This allows your application to continue running without being blocked by the account creation process. The initial response "BVN lookup and account creation are being processed" is returned

2. BVN Authenticity Verification (Optional)
   If you include date_of_birth in your request, the system will verify that the date matches the BVN records before creating the account. Note: You will be charged ₦70 for BVN verification regardless of whether the verification passes or fails.

3. Webhook Notification
   After processing, the system sends a webhook notification to your webhook url. This notification contains details about whether the request was successful or failed. Make sure this is set in the settings tab.

Request Format

Regular Account Creation

JSON

{
    "bvn": "22222222222",
    "email": "[email protected]",
    "phone": "[phone]"
}

With BVN Authenticity Verification

JSON

{
    "bvn": "22222222222",
    "date_of_birth": "2000-07-28",
    "email": "[email protected]",
    "phone": "[phone]"
}

Important Notes:

• date_of_birth must be in YYYY-MM-DD format
• Including date_of_birth triggers authenticity verification
• BVN verification fee (₦70) is charged even if verification fails

Webhook Payload Examples

Success Notification

When the account creation is successful, the webhook sends the following JSON payload:

JSON

{
	"event": "account_creation",
	"data": {
		"name": "Pakam-JOSHUA937",
		"firstname": "JOSHUA",
		"lastname": "ISAAC",
		"phone": "[phone]",
		"email": "[email protected]",
		"wallet_balance": 0,
		"account_numbers": [
			{
				"account_name": "VANT(JOSHUA ISAAC)",
				"account_number": "9976573760",
				"bank": "Providus"
			}
		]
	},
	"statusCode": 200,
	"message": "user account created"
}

Failure Notification

If the account creation fails (for example, due to an invalid BVN or failed authenticity verification), the webhook sends the following JSON payload:

JSON

{
	"event": "account_creation",
	"error": "Date of birth does not match BVN records",
	"data": {
		"email": "[email protected]",
		"phone": "[phone]"
	},
	"statusCode": 400,
	"message": "error creating user account"
}

Common failure reasons:

• Invalid BVN
• Date of birth does not match BVN records
• Email or phone already exists
• Insufficient wallet balance