Delete Card

POST https://api.firmly.work/api/v1/wallets/agentic-pay/cards/delete

​​ Overview

The Delete Card endpoint revokes a previously enrolled card on its network, so the stored virtual_card_id can no longer start a payment. Call it when the buyer removes a saved card from your surface, closes their account, or reports the card lost.

There are two ways to identify the card:

• With a live flow_token — preferred while you still hold a token from the current flow. Firmly reads the network and card from the token and marks the flow card_deleted.
• By network + virtual_card_id — for out-of-band cleanup when the flow_token has already been discarded (for example, a buyer deleting a card from a settings page days later).

The request is a POST rather than an HTTP DELETE because it carries a JSON body.

​​ Authentication

• x-firmly-authorization (string, required) — API token for server-to-server authentication

​​ Request Body

Supply either flow_token or both network and virtual_card_id.

• flow_token (string) — Flow token from any earlier Agentic Pay response in this flow. When present, network and virtual_card_id are ignored.

• network (string) — Card network: "visa", "mastercard", or "discover". Required when flow_token is omitted.

• virtual_card_id (string) — The virtual_card_id returned by Enroll Card. Required when flow_token is omitted.

• reason (string) — Why the card is being removed. One of "SUSPECTED_FRAUD", "ACCOUNT_CLOSED", "OTHER", "DEFAULT". Recorded for audit.

• requestor (string) — Who asked for the removal. One of "CARDHOLDER", "MERCHANT", "ISSUER", "WALLET". Recorded for audit.

​​ Response

• deleted (boolean) — true when the network confirmed the revocation

• src_correlation_id (string) — Network correlation reference for the delete. Returned for Mastercard; absent for Visa and Discover, whose delete calls return no reference. Keep it with your audit log.

No refreshed flow_token is returned — no later Agentic Pay call accepts a token for a deleted card.

​​ Code Examples

curl --request POST \
  --url https://api.firmly.work/api/v1/wallets/agentic-pay/cards/delete \
  --header 'Content-Type: application/json' \
  --header 'x-firmly-authorization: YOUR_API_TOKEN' \
  --data '{
    "network": "mastercard",
    "virtual_card_id": "cf90be5c86363de702ed19beec46e102",
    "reason": "ACCOUNT_CLOSED",
    "requestor": "CARDHOLDER"
  }'

const response = await fetch('https://api.firmly.work/api/v1/wallets/agentic-pay/cards/delete', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-firmly-authorization': 'YOUR_API_TOKEN'
  },
  body: JSON.stringify({
    network: 'mastercard',
    virtual_card_id: 'cf90be5c86363de702ed19beec46e102',
    reason: 'ACCOUNT_CLOSED',
    requestor: 'CARDHOLDER'
  })
});

const data = await response.json();
console.log(data.deleted);

import requests

response = requests.post(
    'https://api.firmly.work/api/v1/wallets/agentic-pay/cards/delete',
    headers={
        'Content-Type': 'application/json',
        'x-firmly-authorization': 'YOUR_API_TOKEN'
    },
    json={
        'network': 'mastercard',
        'virtual_card_id': 'cf90be5c86363de702ed19beec46e102',
        'reason': 'ACCOUNT_CLOSED',
        'requestor': 'CARDHOLDER'
    }
)

data = response.json()
print(data['deleted'])

​​ Response Example

{
  "deleted": true,
  "src_correlation_id": "7f3c1d2e-9a4b-4c8d-b1e2-5f6a7b8c9d0e"
}

​​ Error Responses

{
  "code": 400,
  "error": "BadRequest",
  "description": "flow_token OR (network + virtual_card_id) required"
}

{
  "code": 409,
  "error": "PaymentMethodNotAvailable",
  "description": "Card token not found"
}

​​ Related Endpoints

• Enroll Card — Where the virtual_card_id comes from
• Select Card — Returns 409 PaymentMethodNotAvailable for a card that has been deleted; fall back to /enroll
• Agentic Pay Overview — Concepts and full endpoint list