​
Create a multi-currency Bank Account

​
To create a multi-currency bank account, the user must first be registered as a customer with approved KYC and a verified BVN (if the customer country is NGN). Each customer can have both EUR and USD bank account

​
Endpoint

POST {{baseurl}}/accounts/generate/mcy

These are the parameters of the request body.

FieldData TypeDescription
utilityBillString (URL)

Required. URL to the user’s utility bill document. Example: https://s3.aws.amazon.com/document/utilityBill.pdf.

incomeBandString

Required. User’s income range. Example: 20,000−20,000 - 50,000.

sourceOfIncomeString

Required. Source of the user’s income. Example: Salary.

accountDesignationString

Required. The designation of the account. Example: Savings.

occupationString

Required. User’s occupation. Example: Software Engineer.

employmentStatusString

Required. Employment status of the user. Example: Employed.

customerIdString (UUID)

Required. Unique identifier for the customer.

referenceStringOptional. Reference for the bank account creation.
currencyString

Required. Currency must either be USD | EUR. This is what will determine the type of account that will be generated.

providerString

Required. Provider for the bank account. Always set to ‘FINCRA’.

​
Expected payload:

{
    "utilityBill": "https://s3.aws.amazon.com/document/utilityBill.pdf",
    "incomeBand": "$20,000 - $50,000",
    "sourceOfIncome": "Salary",
    "accountDesignation": "Savings",
    "occupation": "Software Engineer",
    "employmentStatus": "Employed",
    "customerId": "123e4567-e89b-12d3-a456-426614174000",
    "reference": "optional-reference-123",
    "currency": "USD",
    "provider": "FINCRA"
}

If everything went well, your response should look like this:

{
    "success": true,
    "statusCode": 201,
    "message": "Bank account created successfully",
    "data": {
        "id": "d88343f6-f1c2-4e04-a74c-39c7add0c1f8",
        "type": "CUSTOMER",
        "accountType": null,
        "accountId": "d88343f6-f1c2-4e04-8762-39c7add0c1f8",
        "currency": "EUR",
        "isVirtual": true,
        "createdAt": "2024-12-31T22:37:54.322Z",
        "updatedAt": "2024-12-31T22:37:55.322Z",
        "businessId": "0bb1dfc6-a74c-4e53-b41a-4a0c1eab188e",
        "reference": "shsi29wns02j9whdhnw012bd9dh2w",
        "customerId": "0bb1dfc6-a74c-a74c-8762-39c7add0c1f8",
        "resourceType": null,
        "status": "INACTIVE"
    }
}

Remenber to save the id

When creating a multi-currency bank account, the account is not immediately activated. Initially, its status is set to INACTIVE, and the account must go through an approval and issuance process before becoming fully operational. The process is managed via webhook events, which must be handled in the following order:

virtualaccount.approved: This event is triggered when the bank account application has been reviewed and approved by the provider. Approval indicates that the account meets the necessary criteria, but the virtual account details have not yet been issued.

What you should expect:

{
    "event": "virtualaccount.approved",
    "data": {
        "id": "msg_123456789",
        "status": "APPROVED",
        "accountId": "d88343f6-f1c2-4e04-a74c-39c7add0c1f8", // This is the id you saved earlier
        "reference": "ref_abc123",
        "customerId": "cust_654321",
        "businessId": "biz_456789",
        "customerReference": "cust_ref_xyz987" // This is the bank account reference you added while creating
    }
}

virtualaccount.issued: This event is triggered after the account has been approved and the virtual account details are generated. At this stage, the account is ready to be used.

What you should expect:

{
    "event": "virtualaccount.issued",
    "data": {
        "id": "msg_123456789",
        "accountId": "acct_987654321",
        "status": "ISSUED",
        "reference": "ref_abc123",
        "customerId": "cust_654321",
        "businessId": "biz_456789",
        "customerReference": "cust_ref_xyz987",
        "currencyType": "USD",
        "iban": "US12345678901234567890",
        "sortCode": "12-34-56",
        "checkNumber": "123456",
        "bankSwiftCode": "ABCDUS33XXX",
        "addressableIn": "United States",
        "bankAddress": "123 Bank Street, New York, NY, USA",
        "bankCode": "12345678",
        "accountNumber": "9876543210",
        "countryCode": "US",
        "bankName": "Bank of America"
    }
}

virtualaccount.declined: TThis event is triggered if the bank account application is reviewed and rejected during the approval process. The record will be deleted from our end immediately.

What you should expect:

{
    "event": "virtualaccount.declined",
    "data": {
        "id": "msg_123456789",
        "reason": "Document is not clear",
        "status": "DECLINED",
        "accountId": "acct_987654321",
        "reference": "ref_abc123",
        "customerId": "cust_654321",
        "businessId": "biz_456789",
        "customerReference": "cust_ref_xyz987"
    }
}
Create ngn bank accountGet a bank account