API reference · Moving money

Withdrawals

POST/withdrawWithdraw from an account to an external system
GET/withdrawal/scheduleList the caller's scheduled withdrawals
GET/withdrawal/schedule/{reference}Get a scheduled withdrawal's detail and occurrence history
POST/withdrawal/schedule/{reference}/cancelCancel a scheduled withdrawal before it fires

POST Withdraw from an account to an external system

POST /withdraw

Validates that the source account belongs to the caller, obtains a quote, posts the withdrawal to the ledger, then requests external settlement from the mediation service - synchronously or asynchronously, per executionMode. An optional Idempotency-Key header makes a retried call with the same key return the original result instead of withdrawing again.

Headers

Name	Notes
`Authorization`	Bearer token
`X-Tenant`	Your tenant
`X-Environment`	test or live
`Idempotency-Key`	Reuse the same value on every retry of this request
`Content-Type`	application/json

Example

Request body: WithdrawalRequest · Response: WithdrawalResponse

curl -X POST "https://api.bridgemoni.com/withdraw" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV" \
  -H "Idempotency-Key: a-unique-key-per-intent" \
  -H "Content-Type: application/json" \
  -d '{
    "beneficiaryReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "organizationReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "sourceAccountNumber": "0123456789",
    "instrumentReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "destinationAccountNumber": "0123456789",
    "destinationAccountProviderCode": "provider code",
    "destinationAccountProviderName": "Ada Obi",
    "destinationAccountName": "Ada Obi",
    "amount": 250000.0,
    "saveBeneficiary": true,
    "beneficiaryAlias": "Ada Obi",
    "currencyCode": "NGN",
    "narration": "March payroll",
    "executionMode": "SYNCHRONOUS",
    "schedule": {
      "startDateTime": "2027-03-14T14:30:01",
      "frequency": "HOURLY",
      "endDateTime": "2027-03-14T14:30:01",
      "maxOccurrences": 1
    }
  }'

{
  "beneficiaryReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
  "organizationReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
  "sourceAccountNumber": "0123456789",
  "instrumentReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
  "destinationAccountNumber": "0123456789",
  "destinationAccountProviderCode": "provider code",
  "destinationAccountProviderName": "Ada Obi",
  "destinationAccountName": "Ada Obi",
  "amount": 250000.0,
  "saveBeneficiary": true,
  "beneficiaryAlias": "Ada Obi",
  "currencyCode": "NGN",
  "narration": "March payroll",
  "executionMode": "SYNCHRONOUS",
  "schedule": {
    "startDateTime": "2027-03-14T14:30:01",
    "frequency": "HOURLY",
    "endDateTime": "2027-03-14T14:30:01",
    "maxOccurrences": 1
  }
}

{
  "data": {
    "withdrawalReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "sourceAccountNumber": "0123456789",
    "destinationAccountNumber": "0123456789",
    "beneficiaryReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "saveBeneficiaryToken": "text",
    "beneficiaryName": "Ada Obi",
    "amount": 250000.0,
    "netAmount": 250000.0,
    "currencyCode": "NGN",
    "status": "PENDING",
    "accountsTransactionReference": "financial transaction reference",
    "scheduleReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "approvalReference": "financial transaction reference",
    "timestamp": "2027-03-14T14:30:01"
  },
  "description": "Withdraw from an account to an external system"
}

Responses

Status	When
`200`	Withdrawal processed successfully

GET List the caller's scheduled withdrawals

GET /withdrawal/schedule

Headers

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

Example

Response: List<ScheduledWithdrawalResponse>

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

{
  "data": [
    {
      "scheduleReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
      "sourceAccountNumber": "0123456789",
      "destinationAccountNumber": "0123456789",
      "destinationAccountProviderCode": "provider code",
      "destinationAccountProviderName": "Ada Obi",
      "destinationAccountName": "Ada Obi",
      "amount": 250000.0,
      "currencyCode": "NGN",
      "narration": "March payroll",
      "startDateTime": "2027-03-14T14:30:01",
      "frequency": "HOURLY",
      "endDateTime": "2027-03-14T14:30:01",
      "maxOccurrences": 1,
      "occurrenceCount": 1,
      "nextExecutionAt": "2027-03-14T14:30:01",
      "status": "SCHEDULED",
      "lastExecutedReference": "financial transaction reference",
      "lastFailureReason": "March payroll",
      "cancelReason": "March payroll",
      "executions": [
        {
          "...": "nested"
        }
      ]
    }
  ],
  "description": "List the caller's scheduled withdrawals"
}

Responses

Status	When
`200`	Scheduled withdrawals listed successfully

GET Get a scheduled withdrawal's detail and occurrence history

GET /withdrawal/schedule/{reference}

Headers

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

Path parameters

Name
`reference`

Example

Response: ScheduledWithdrawalResponse

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

{
  "data": {
    "scheduleReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "sourceAccountNumber": "0123456789",
    "destinationAccountNumber": "0123456789",
    "destinationAccountProviderCode": "provider code",
    "destinationAccountProviderName": "Ada Obi",
    "destinationAccountName": "Ada Obi",
    "amount": 250000.0,
    "currencyCode": "NGN",
    "narration": "March payroll",
    "startDateTime": "2027-03-14T14:30:01",
    "frequency": "HOURLY",
    "endDateTime": "2027-03-14T14:30:01",
    "maxOccurrences": 1,
    "occurrenceCount": 1,
    "nextExecutionAt": "2027-03-14T14:30:01",
    "status": "SCHEDULED",
    "lastExecutedReference": "financial transaction reference",
    "lastFailureReason": "March payroll",
    "cancelReason": "March payroll",
    "executions": [
      {
        "occurrenceNumber": 1,
        "executedReference": "financial transaction reference",
        "outcome": "SUCCESS",
        "failureReason": "March payroll",
        "executedAt": "2027-03-14T14:30:01"
      }
    ]
  },
  "description": "Get a scheduled withdrawal's detail and occurrence history"
}

Responses

Status	When
`200`	Scheduled withdrawal fetched successfully

POST Cancel a scheduled withdrawal before it fires

POST /withdrawal/schedule/{reference}/cancel

Headers

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

Path parameters

Name
`reference`

Example

Response: ScheduledWithdrawalResponse

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

{
  "data": {
    "scheduleReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "sourceAccountNumber": "0123456789",
    "destinationAccountNumber": "0123456789",
    "destinationAccountProviderCode": "provider code",
    "destinationAccountProviderName": "Ada Obi",
    "destinationAccountName": "Ada Obi",
    "amount": 250000.0,
    "currencyCode": "NGN",
    "narration": "March payroll",
    "startDateTime": "2027-03-14T14:30:01",
    "frequency": "HOURLY",
    "endDateTime": "2027-03-14T14:30:01",
    "maxOccurrences": 1,
    "occurrenceCount": 1,
    "nextExecutionAt": "2027-03-14T14:30:01",
    "status": "SCHEDULED",
    "lastExecutedReference": "financial transaction reference",
    "lastFailureReason": "March payroll",
    "cancelReason": "March payroll",
    "executions": [
      {
        "occurrenceNumber": 1,
        "executedReference": "financial transaction reference",
        "outcome": "SUCCESS",
        "failureReason": "March payroll",
        "executedAt": "2027-03-14T14:30:01"
      }
    ]
  },
  "description": "Cancel a scheduled withdrawal before it fires"
}

Responses

Status	When
`200`	Scheduled withdrawal cancelled successfully

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