Top up a virtual card

Moves funds from the funding account backing a virtual card into that card's balance. The transfer is posted to the ledger synchronously — the account is debited, the card's cached_balance is incremented by amount, and a successful transaction record is created and returned — all within a single atomic operation. If the funding account does not have sufficient available balance to cover amount, the entire operation is rolled back and a 400 error is returned.

On the first top-up for a card, a dedicated PaymentIntent (client reference card-topup-{virtual_card_id}) is created to track the card's cumulative top-up history; subsequent top-ups reuse it.

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_topup and reference_id set to the virtual_card_id, after the caller re-confirms their PIN) in the request body. 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: ********************

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Body Params application/jsonRequired

Examples

curl --location '/virtual-card-topups' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "virtual_card_id": "01HXYZ9876543210ZYXWVUTSRQ", "amount": 50000 }'

{ "message": "Virtual card topped up successfully", "status": "success", "data": { "id": "01J8ZK3QATXNTOPUP00000A1", "entity_id": "01HENT1234567890ABCDEFGHIJ", "account_id": "01HXYZ1234567890ABCDEFGHIJ", "direction": "inflow", "type": "payment", "amount": 50000, "currency": "NGN", "applicable_fee": 0, "balance_after": 1450000, "status": "successful", "status_reason": null, "narration": "Card top-up", "counterparty_id": null, "initiating_counterparty": { "name": "", "email": null, "phonenumber": null }, "receiving_counterparty": { "account_id": "01HXYZ1234567890ABCDEFGHIJ", "account_name": "Main Operating Account" }, "source": { "type": "payment_intent_action", "id": "01J8ZK3QAPIA0000000000A1" }, "created": 1754392100000, "updated": 1754392100000 } }

Request

Responses