1. Virtual Card Actions
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
      PATCH
  • 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
  • Schemas
    • ErrorResponse
    • SuccessResponse
    • AccountBalance
    • Account
  1. Virtual Card Actions

Perform an action on a virtual card

PATCH
/virtual-card-actions/{cardId}
Applies a lifecycle action — freeze, unfreeze, or terminate — to one of your virtual cards. The action is recorded immediately as a pending VirtualCardAction and queued for asynchronous processing with the card-issuing provider; the card's status is optimistically updated in the same transaction (e.g. active → frozen for freeze, frozen → active for unfreeze, or active/frozen → terminated for terminate).
Each action is only valid from specific card states: freeze requires the card to currently be active, unfreeze requires it to currently be frozen, and terminate requires it to be active or frozen. Requesting an action the card's current status doesn't support fails with a 400 error and no changes are made. Terminating a card also zeroes its cached_balance. Cards that are pending-approval or already terminated reject every action with a 400 error.

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
Path Params

Body Params application/jsonRequired

Examples

Responses

🟢200
application/json
The action was accepted and queued for processing; the returned VirtualCardAction reflects its initial pending state.
Bodyapplication/json

🟠400
🟠401
🟠404
Request Request Example
Shell
JavaScript
Java
Swift
cURL
curl --location --request PATCH '/virtual-card-actions/01HXYZ9876543210ZYXWVUTSRQ' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
    "action": "freeze"
}'
Response Response Example
200 - Success
{
    "message": "Virtual card action created successfully",
    "status": "success",
    "data": {
        "id": "01J8ZK3QANDACTION0000000A1",
        "entity_id": "01HABC9999888877776666ZZZZ",
        "virtual_card_id": "01HXYZ9876543210ZYXWVUTSRQ",
        "type": "freeze",
        "status": "pending",
        "status_reason": null,
        "reason": "customer-reported-card-lost",
        "provider_code": "sandbox_card_provider",
        "created": "2026-09-28T10:15:00Z",
        "updated": "2026-09-28T10:15:00Z"
    }
}
Modified at 2026-09-28 15:25:25
Previous
Request a phone number change for the current identity
Next
List all ACL definitions
Built with