1. Virtual Card Withdrawals
BNW CORE SERVICE
  • Card Vaulting
    • Create a card vault session
      POST
  • Fee Lookups
    • Compute fees for a transaction
      POST
  • Intent Action Status Lookups
    • Look up the status of an intent action
      GET
  • Payment Intents
    • Create a payment intent
      POST
    • Cancel a payment intent
      PATCH
    • List payment intents
      GET
    • Retrieve a payment intent
      GET
  • Intent Actions
    • Create an intent action
      POST
    • Advance an intent action to the next step
      PATCH
    • Retrieve the authentication session for a pending redirect action
      GET
  • Accounts
    • Create a new account
      POST
    • List accounts
      GET
    • Close an account
      DELETE
    • Update an account
      PATCH
    • Retrieve an account
      GET
    • Retrieve an account's daily payout limit status
      GET
  • API Keys
    • Create an API key
      POST
    • List API keys
      GET
    • Update an API key
      PATCH
    • Retrieve an API key
      GET
    • Revoke an API key
      DELETE
    • Rotate an API key's secret
      POST
  • App Setting Values
    • Delete an app setting value
    • Retrieve an app setting value
    • List app setting values
    • Create or update an app setting value
  • Entities
    • Create an entity
    • List entities
    • Close an entity
    • Update an entity
    • Retrieve an entity
    • Set the selected entity
    • Retrieve public metadata for the authenticated entity
    • Create an entity sandbox session
    • Retrieve one of your entities, including your membership
    • List my entities
  • Counterparties
    • Create a counterparty
    • List counterparties
    • Update a counterparty
    • Retrieve a counterparty
  • Maker Checker Approver Groups
    • Create a maker-checker approver group
    • List maker-checker approver groups
    • Deactivate a maker-checker approver group
    • Update a maker-checker approver group
    • Retrieve a maker-checker approver group
  • Bulk Payout Intent Actions
    • Create bulk payout intent actions
    • Retrieve a bulk payout intent action batch
    • Preview bulk payout intent actions
  • Payout Intent Action Retries
    • Retry a failed payout intent action
  • Payout Intent Actions
    • Create a payout intent action
    • List payout intent actions
    • Retrieve a payout intent action
  • Payout Intents
    • Create a payout intent
    • List payout intents
    • Retrieve a payout intent
    • Edit a payout intent
    • Cancel a payout intent's active schedule
    • Edit a payout intent's active schedule
    • Cancel a payout intent
  • Virtual Cards
    • Create a virtual card
    • List virtual cards
    • Update a virtual card
    • Retrieve a virtual card
  • Maker Checker Action Decisions
    • Record a decision on a maker-checker action
  • Maker Checker Actions
    • Retrieve a maker-checker action's status
    • List maker-checker actions
    • Withdraw a maker-checker action
  • Payment Pages
    • Create a payment page
    • List payment pages
    • Delete a payment page
    • Edit a payment page
    • Retrieve a payment page
    • Retrieve a published payment page by slug
  • Invoices
    • Create an invoice
    • List invoices
    • Retrieve an invoice
    • Edit an invoice
    • Retrieve an invoice as a PDF
    • Download a public invoice as a PDF
    • Retrieve a public invoice by invoice number
    • Send a reminder for an invoice
    • Send or resend an invoice
  • Entity Data
    • Retrieve the data submission checklist for an entity
    • Submit entity data for KYC requirements
    • List entity data
    • Review and decide on entity data submission
  • Unified Verifs
    • Proxy a DELETE request to the Verification API
    • Proxy a GET request to the Verification API
    • Proxy a PATCH request to the Verification API
    • Forward a POST request to the Verification API
  • Identity Session
    • List identity sessions
    • Complete the MFA step of a pending login session
    • Request a login MFA challenge or one-time-passcode
  • Identity Sessions
    • Terminate all active sessions for an identity
    • Terminate an identity session
  • Entity Sandboxes
    • Create an additional named entity sandbox
    • Delete an entity sandbox
    • Rename an entity sandbox
  • Identity Mfa
    • Passkeys
    • Enroll a new MFA method for the authenticated identity
    • List MFA methods for the authenticated identity
    • Retrieve an identity MFA method
    • Advance or transition the state of an existing MFA method
  • Auth
    • Log in with email and password
    • Register a new identity
    • Request an email verification link
    • Verify an email address
    • Request a password reset
    • Complete a password reset with a one-time token
    • Change the authenticated identity's password
    • Confirm a pending email address change
    • Request a change of the authenticated identity's email address
    • Resend an identity-confirmation email
    • Confirm a phone number change for the current identity
    • Request a phone number change for the current identity
  • Virtual Card Actions
    • Perform an action on a virtual card
  • ACLs
    • List all ACL definitions
  • Account Transfers
    • Create an account transfer
    • List account transfers
    • Retrieve an account transfer
  • ACL Roles
    • List all ACL roles
  • Counterparty Instruments
    • Add a bank account to a counterparty
    • List counterparty instruments
    • Remove a counterparty's bank account
  • Currency Conversion Quotes
    • Create a currency conversion quote
  • Entity Access
    • Change a team member's role on an entity
    • Remove a member's access to an entity
    • List an entity's team members
  • Entity Access Invites
    • Accept an entity access invitation
    • Invite a new member to an entity
    • List entity access invites
    • Revoke an entity access invite
  • Entity Ownership Transfers
    • Transfer ownership of an entity
  • Identity
    • Update the authenticated identity's name
    • Retrieve the authenticated identity
  • Money Action Confirmations
    • Confirm a money-moving action with PIN (and, where required, an authenticator code)
  • Payout Intent Action Returns
    • Record a payout intent action as returned
  • Payout Intent Action Status Logs
    • List a payout intent action's status history
  • Payout Intent Schedule Actions
    • Apply an action to a payout intent's schedule
  • Sandbox
    • Credit test money into an entity's sandbox wallet
    • Reset a shadow entity's sandbox
    • Get or create the sandbox identity for the authenticated identity
    • Provision a sandbox identity and master API key
    • Exchange the sandbox master API key for a login session
    • Fund an entity's test wallet with sandbox test money
  • Transactions
    • Retrieve a transaction
    • List transactions
  • Virtual Card Activity
    • List a virtual card's activity
  • Virtual Card Sessions
    • Create a virtual card viewing session
  • Virtual Card Topups
    • Top up a virtual card
  • Virtual Card Transaction Callbacks
    • Handle an inbound virtual card transaction callback
  • Virtual Card Withdrawals
    • Withdraw funds from a virtual card
      POST
  • Schemas
    • ErrorResponse
    • SuccessResponse
    • AccountBalance
    • Account
  1. Virtual Card Withdrawals

Withdraw funds from a virtual card

POST
/virtual-card-withdrawals
Moves funds off a virtual card's balance and back onto the funding account backing it, posting a ledger transfer from the platform's card float account to that account and decrementing the card's cached balance by the withdrawn amount. A successful payout-intent-action and transaction record are created synchronously as part of the same operation — this endpoint has no pending or pending-approval outcome.
The card must exist, belong to the authenticated entity, and not be pending-approval or terminated; the requested amount must not exceed the card's current cached_balance.
When called with a JWT session, this endpoint also requires a valid, unused money_action_confirmation_id (minted via POST /money-action-confirmations with action_type card_withdrawal, and, when the confirmation was minted with a reference, matching virtual_card_id) in the request body, obtained after the caller re-confirms their PIN. This requirement is skipped entirely for secret-API-key requests, since PIN confirmation only applies to interactive human sessions.

Request

Authorization
JWT Bearer
Add the parameter
Authorization
to Headers
Example:
Authorization: ********************
or
Bearer Token
Provide your bearer token in the
Authorization
header when making requests to protected resources.
Example:
Authorization: Bearer ********************
or
Body Params application/jsonRequired

Examples

Responses

🟢201
application/json
The withdrawal was posted successfully and the resulting transaction is returned.
Bodyapplication/json

🟠400
🟠401
🟠404
🔴500
Request Request Example
Shell
JavaScript
Java
Swift
cURL
curl --location '/virtual-card-withdrawals' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
    "virtual_card_id": "01HXYZ1234567890ABCDEFGHIJ",
    "amount": 25000
}'
Response Response Example
201 - Success
{
    "message": "Virtual card withdrawal created successfully",
    "status": "success",
    "data": {
        "id": "01HXYZ5555666677778888AA",
        "entity_id": "01HENT1234567890ABCDEFGHIJ",
        "account_id": "01HACC1234567890ABCDEFGHIJ",
        "direction": "credit",
        "type": "payout",
        "amount": 25000,
        "currency": "NGN",
        "applicable_fee": 0,
        "balance_after": 125000,
        "status": "successful",
        "status_reason": null,
        "narration": "Card withdrawal",
        "counterparty_id": null,
        "initiating_counterparty": null,
        "receiving_counterparty": null,
        "source": {
            "type": "payout_intent_action",
            "id": "01HPIA1234567890ABCDEFGHIJ"
        },
        "created": 1754392100000,
        "updated": 1754392100000
    }
}
Modified at 2026-09-30 00:29:30
Previous
Handle an inbound virtual card transaction callback
Next
ErrorResponse
Built with