Dynamic Accounts

Dynamic virtual accounts are temporary accounts created for specific transactions or customers.

API Reference

Create Dynamic Account

• Path: /api/v1/virtual-accounts/dynamic
• Method: POST
• Request Body:
• Response Body:
  • Account details will be returned upon successful creation

Request Body Table

Field	Type	Required	Description
amount	double	Yes	Amount for the transaction
reference	string	Yes	Unique reference for the transaction
businessId	string	Yes	Your business identifier
customer	object	Yes	Customer information
customer.name	string	Yes	Customer's full name
customer.email	string	Yes	Customer's email address
customer.phone	string	Yes	Customer's phone number
customer.externalId	string	No	For merchant customer identification
customer.address	object	No	Customer's address information
customer.address.line1	string	No	Address line 1
customer.address.line2	string	No	Address line 2
customer.address.city	string	No	City
customer.address.state	string	No	State
customer.address.postalCode	string	No	Postal code
customer.address.countryCode	string	No	Alpha-2 country code
customer.nin	string	No	National Identification Number
customer.bvn	string	No	Bank Verification Number
notificationUrl	string	No	An optional notification URL. If one isn't specified, it will be directed to the default webhook URL configured on the Merchant Dashboard

Usage

Dynamic accounts are ideal for: - One-time payments - Specific transaction tracking - Customer-specific payment collection

Example Request

{
  "amount": 5000.00,
  "reference": "{unique_reference}",
  "businessId": "{your_business_id}",
  "customer": {
    "name": "Test Customer",
    "email": "test@customer.com",
    "phone": "08012345678",
    "externalId": "{unique_customer_ref}"
  }
}

Example Response

{
  "status": 200,
  "message": "Success",
  "data": {
    "accountName": "John Doe",
    "accountNumber": "1212334455",
    "bankName": "Test Bank",
    "amount": 5000,
    "onusReference": "ONUS-NUB-xxx-xxx-xxx",
    "merchantReference": "xxx-xxx-xxx"
  }
}

Create Pay with Wallet link

• Path: /api/v1/virtual-accounts/dynamic
• Method: POST
• Request Body:
• Response Body:
  • Account details will be returned upon successful creation

Request Body Table

Field	Type	Required	Description
amount	double	Yes	Amount for the transaction
reference	string	Yes	Unique reference for the transaction
businessId	string	Yes	Your business identifier
customer	object	Yes	Customer information
customer.name	string	Yes	Customer's full name
customer.email	string	Yes	Customer's email address
customer.phone	string	Yes	Customer's phone number
walletType	string	Yes	Wallet Type (enum: OPAY, PALMPAY)
paymentChannel	string	Yes	PAY_WITH_WALLET
redirectUrl	string	Yes	Redirect URL after payment completion

Usage

Pay With Wallet is ideal for: - One-time payments where customers have an OPay or PalmPay account - Redirect the customer's browser to the URL in the completionUrl field of the response. The customer will authorize the payment inside the OPay or PalmPay app, then be redirected back to your redirectUrl on completion.

Sandbox limitation: The completionUrl flow cannot be simulated in the sandbox environment. Pay With Wallet is a live (production) only feature. In sandbox, the request will succeed and return a completionUrl, but following that URL will not trigger a real wallet authorization. Test your redirect and webhook-handling logic in production with a small real transaction.

Example Request

{
  "amount": 500.00,
  "reference": "unique_reference_123",
  "businessId": "your_business_id",
  "customer": {
    "name": "John Doe",
    "email": "john.doe@example.com",
    "phone": "08012345678"
  },
  "walletType": "OPAY",
  "paymentChannel": "PAY_WITH_WALLET",
  "redirectUrl": "https://test.merchant.com/order/{random_reference}/confirm"
}

Example Response

{
  "status": 200,
  "message": "Success",
  "data": {
    "accountName": "John Doe",
    "accountNumber": "N/A - Wallet",
    "bankName": "OPAY",
    "amount": 500,
    "onusReference": "ONUS-NUB-xxx-xxx-xxx",
    "merchantReference": "xxx-xxx-xxx",
    "completionUrl": "https://checkout.provider.com/order/xxx-xxx-xxx"
  }
}

Notes

• Dynamic accounts typically expire after a set period or once the specified amount has been received.
• You will receive a webhook notification when a payment is made to the dynamic account.
• The account details should be shared with the customer for payment
• You can verify the status of a specific payment using the Verify Single Payment endpoint with the onusReference.