API reference · Accounts & ledger

Virtual Accounts

Dedicated account numbers per customer or per invoice, credited as transfers land. About virtual accounts Live

GET/account/virtualList the caller's virtual accounts
POST/account/virtualCreate a virtual account at each of the named banks
POST/account/virtual/credit/{reference}/replayRetry a credit whose posting failed
DELETE/account/virtual/{reference}Delete a virtual account
GET/account/virtual/{reference}Fetch one of the caller's virtual accounts
POST/account/virtual/{reference}/blockBlock a virtual account
GET/account/virtual/{reference}/creditsList the funding notifications received for a virtual account
POST/account/virtual/{reference}/unblockUnblock a virtual account

GET List the caller's virtual accounts

GET /account/virtual

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Example

Response: List<VirtualAccountResponse>

curl -X GET "https://api.bridgemoni.com/account/virtual" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": [
    {
      "financialInstitutionCode": "financial institution code",
      "providerCode": "provider code",
      "status": "SUCCESSFUL",
      "accountName": "Ada Obi",
      "accountNumber": "0123456789",
      "currencyCode": "NGN",
      "category": "category",
      "failureReason": "March payroll"
    }
  ],
  "description": "List the caller's virtual accounts"
}

Responses

Status	When
`200`	Virtual accounts retrieved successfully

POST Create a virtual account at each of the named banks

POST /account/virtual

Every virtual account is linked to the caller's main account for the requested currency, which must already exist. Each bank is fulfilled independently - a bank that declines is reported under 'failures' and is not persisted, while the rest still succeed.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live
`Content-Type`	application/json

Example

Request body: VirtualAccountRequest · Response: VirtualAccountCreationResponse

curl -X POST "https://api.bridgemoni.com/account/virtual" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV" \
  -H "Content-Type: application/json" \
  -d '{
    "financialInstitutionCodes": [
      "financial institution code"
    ],
    "currencyCode": "NGN",
    "category": "category"
  }'

{
  "financialInstitutionCodes": [
    "financial institution code"
  ],
  "currencyCode": "NGN",
  "category": "category"
}

{
  "data": {
    "virtualAccounts": [
      {
        "financialInstitutionCode": "financial institution code",
        "providerCode": "provider code",
        "status": "SUCCESSFUL",
        "accountName": "Ada Obi",
        "accountNumber": "0123456789",
        "currencyCode": "NGN",
        "category": "category",
        "failureReason": "March payroll"
      }
    ],
    "failures": [
      {
        "financialInstitutionCode": "financial institution code",
        "failureReason": "March payroll"
      }
    ]
  },
  "description": "Create a virtual account at each of the named banks"
}

Responses

Status	When
`200`	Virtual account request processed

POST Retry a credit whose posting failed

POST /account/virtual/credit/{reference}/replay

Only FAILED credits are retried. An APPLIED credit has already moved money and is returned unchanged; a REJECTED one was declined for a reason retrying cannot change, and is also returned unchanged. Safe to call over a whole list of references without filtering first.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Path parameters

Name
`reference`

Example

Response: VirtualAccountCreditResponse

curl -X POST "https://api.bridgemoni.com/account/virtual/credit/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e/replay" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": {
    "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "providerReference": "text",
    "status": "APPLIED",
    "creditedAccountNumber": "0123456789",
    "amount": 250000.0,
    "netAmount": 250000.0,
    "currencyCode": "NGN",
    "transactionReference": "text",
    "rejectionReason": "text"
  },
  "description": "Retry a credit whose posting failed"
}

Responses

Status	When
`200`	Replay attempted
`404`	No credit under that reference

DELETE Delete a virtual account

DELETE /account/virtual/{reference}

Retires the account number at the issuing bank. Terminal - the record is retained for audit rather than removed, and a closed account cannot be restored.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Path parameters

Name
`reference`

Example

Response: VirtualAccountResponse

curl -X DELETE "https://api.bridgemoni.com/account/virtual/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": {
    "financialInstitutionCode": "financial institution code",
    "providerCode": "provider code",
    "status": "SUCCESSFUL",
    "accountName": "Ada Obi",
    "accountNumber": "0123456789",
    "currencyCode": "NGN",
    "category": "category",
    "failureReason": "March payroll"
  },
  "description": "Delete a virtual account"
}

Responses

Status	When
`200`	Virtual account deleted successfully

GET Fetch one of the caller's virtual accounts

GET /account/virtual/{reference}

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Path parameters

Name
`reference`

Example

Response: VirtualAccountResponse

curl -X GET "https://api.bridgemoni.com/account/virtual/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": {
    "financialInstitutionCode": "financial institution code",
    "providerCode": "provider code",
    "status": "SUCCESSFUL",
    "accountName": "Ada Obi",
    "accountNumber": "0123456789",
    "currencyCode": "NGN",
    "category": "category",
    "failureReason": "March payroll"
  },
  "description": "Fetch one of the caller's virtual accounts"
}

Responses

Status	When
`200`	Virtual account retrieved successfully

POST Block a virtual account

POST /account/virtual/{reference}/block

Asks the issuing bank to stop accepting inbound funds. The stored status only changes once the bank has accepted, so a rejection leaves the account as it was.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Path parameters

Name
`reference`

Example

Response: VirtualAccountResponse

curl -X POST "https://api.bridgemoni.com/account/virtual/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e/block" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": {
    "financialInstitutionCode": "financial institution code",
    "providerCode": "provider code",
    "status": "SUCCESSFUL",
    "accountName": "Ada Obi",
    "accountNumber": "0123456789",
    "currencyCode": "NGN",
    "category": "category",
    "failureReason": "March payroll"
  },
  "description": "Block a virtual account"
}

Responses

Status	When
`200`	Virtual account blocked successfully

GET List the funding notifications received for a virtual account

GET /account/virtual/{reference}/credits

Newest first, including rejected and failed entries - those are what is needed when money was reportedly sent and never arrived.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Path parameters

Name
`reference`

Example

Response: List<VirtualAccountCreditResponse>

curl -X GET "https://api.bridgemoni.com/account/virtual/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e/credits" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": [
    {
      "reference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
      "providerReference": "text",
      "status": "APPLIED",
      "creditedAccountNumber": "0123456789",
      "amount": 250000.0,
      "netAmount": 250000.0,
      "currencyCode": "NGN",
      "transactionReference": "text",
      "rejectionReason": "text"
    }
  ],
  "description": "List the funding notifications received for a virtual account"
}

Responses

Status	When
`200`	Credits retrieved successfully
`401`	The virtual account belongs to someone else

POST Unblock a virtual account

POST /account/virtual/{reference}/unblock

Restores a blocked virtual account to accepting inbound funds.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live

Path parameters

Name
`reference`

Example

Response: VirtualAccountResponse

curl -X POST "https://api.bridgemoni.com/account/virtual/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e/unblock" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

{
  "data": {
    "financialInstitutionCode": "financial institution code",
    "providerCode": "provider code",
    "status": "SUCCESSFUL",
    "accountName": "Ada Obi",
    "accountNumber": "0123456789",
    "currencyCode": "NGN",
    "category": "category",
    "failureReason": "March payroll"
  },
  "description": "Unblock a virtual account"
}

Responses

Status	When
`200`	Virtual account unblocked successfully

Generated from the OpenAPI document. Branch on the HTTP status: there is no machine-readable error code on the wire. Errors