Virtual accounts

Create a virtual account

Opens a bank account number for one of your customers, under one of your business's provider profiles: on your own provider connection what arrives lands in your own account there; under a FastPay-managed profile the provider pays it to your settlement account. A static account takes any number of payments; a dynamic one takes a single payment before it expires. The BVN or NIN is stored encrypted and never returned. Asking again for a customer whose static account an earlier request left pending returns that account (200) instead of a second one. A 502 or 503 means no account was opened; any account started is marked failed, and asking again with the same idempotency key opens another.

Headers#

• Idempotency-KeystringRequired

  Client-generated key that makes the request safe to retry. Replaying the key with an identical payload returns the original response; replaying it with a different payload is rejected. Up to 255 characters.

Body parameters#

• account_typestringRequired

  One of static, dynamic.

• customer_namestringRequired

  The name on the account. Up to 120 characters.

• customer_refstringRequired

  Your own id for the customer: up to 100 letters, digits, dots, underscores, colons or hyphens (no spaces or @). One open static account per customer and provider. Up to 100 characters.

• emailstringRequired

  Finds or creates the customer. Up to 254 characters.

• amount_minorintegerOptional

  Dynamic accounts only. The amount to expect, in the smallest unit of the currency. At least 1.

• bvnstringOptional

  11 digits. Stored encrypted and never returned. Exactly 11 characters.

• expires_inintegerOptional

  Dynamic accounts only. Seconds until the account stops taking payment; 86400 (a day) when left out. From 900 to 2592000.

• ninstringOptional

  11 digits. Stored encrypted and never returned. The BVN is used when both are sent. Exactly 11 characters.

• phonestringOptional

  International format, or 11 digits starting with 0. Up to 16 characters.

• providerstringOptional

  Needed only when your business has more than one provider profile. Up to 40 characters.

Responses#

• 200The static account an earlier request started for this customer
• 201Virtual account created
• 400The request could not be read.
• 401The secret key is missing, invalid or revoked.
• 403The key is not allowed to do this, or the request came from an address that is not on its allowlist.
• 409The request clashes with the current state, such as a reference reused with different details.
• 422A field is missing or not valid.
• 502A dependency could not be reached
• 503A dependency could not be reached