Skip to main content

Documentation Index

Fetch the complete documentation index at: https://apidocs.bridge.xyz/llms.txt

Use this file to discover all available pages before exploring further.

This page is part of the legacy Bridge Cards API. For new integrations, use the consumer issuing guide instead.
Creating a card and running your first transaction is the best way to get a feel for the Bridge Cards API. To create your first card you will need to both create a customer and then create a card for them to use.

​
Step 1: Create a customer

Before issuing a card, you must first onboard a customer. Learn more at Create your first customer. Once you have a customer onboarded, you can make the customer eligible for cards by following this guide.

​
Step 2: Provision a Card Account

Once your customer is onboarded, you can create a card account. Bridge supports a variety of different funds flows, and in particular we support the ability to spend directly out of a noncustodial wallet via onchain approvals. Each card is tied to a single currency and network. This cannot be changed after creation.
Request
curl -X POST 'https://api.bridge.xyz/v0/customers/<customerID>/card_accounts' \
 --header 'Content-Type: application/json' \
 --header 'Api-Key: <API Key>' \
 --header 'Idempotency-Key: <generate a uuid>' \
 --data-raw '{
   "client_reference_id": "test-card-reference-id1",
   "currency": "usdc",
   "chain": "solana",
    "crypto_account": {
      "type": "bridge_wallet",
		  "address": "7bHbB8RwQgyNgxXZx8Q2kNzjEkmyv9Kb1DKZa63K3CtB"
    }
 }'

​
Step 3: View card details

After provisioning the card, you can view card details such as PAN and CVV by following this integration guide. This approach keeps your backend out of PCI compliance scope by ensuring that sensitive card details are revealed only directly to customer.

​
Step 4: Create a test transaction

You can now use your test card with any e-commerce site that accepts cards. We recommend using a known merchant with stable infrastructure.

​
Step 5: Listen for pending transactions

Once a transaction has been authorized at the merchant, it will show up in the pending authorizations API endpoint: 
curl 'https://api.bridge.xyz/v0/customers/{customerID}/card_accounts/{cardAccountID}/authorizations \
 --header 'Content-Type: application/json' \
 --header 'Api-Key: <API Key>'
In addition, you can get notified of card authorizations in real time using the card_transaction.created webhook. This gives you a view of authorized but not yet settled transactions.
Response
{
  "api_version": "v0",
  "event_id": "wh_tpHJpYMbNCFLDJRVqEhZsEG",
  "event_category": "card_transaction",
  "event_type": "card_transaction.created",
  "event_object_id": "77f4381c-a39d-5f6e-a383-0b71007c4f19",
  "event_object_status": "approved",
  "event_object": {
    "id": "77f4381c-a39d-5f6e-a383-0b71007c4f19",
    "card_account_id": "5a86836d-cee5-44a5-a89b-5957470334b2",
    "customer_id": "15ff6495-9947-4b18-8b46-319668cbd69a",
    "amount": "-10.25",
    "original_amount": "-10.25",
    "currency": "usd",
    "category": "purchase",
    "status": "approved",
    "created_at": "2025-02-04T05:19:20.000Z",
    "authorized_at": "2025-02-04T05:19:25.000Z",
    "updated_at": "2025-02-04T05:19:25.000Z",
    "merchant_name": "ROCKET RIDES",
    "merchant_location": "SAN FRANCISCO, CAUS",
    "merchant_category_code": "4121",
    "transaction_description": "ROCKET RIDES 8442613753, CAUS"
  },
  "event_object_changes": {},
  "event_created_at": "2025-02-04T05:19:20.000Z",
}
More information about possible card transaction scenarios, and how they’ll show up as webhooks, are available in this guide.

​
Step 6: Listen for settled transactions

Use the card_transaction.updated.status_transitioned webhook to track settlement status. 
{
  "api_version": "v0",
  "event_id": "wh_txyRrWPzNQWpDKSFo9YVidJ",
  "event_category": "card_transaction",
  "event_type": "card_transaction.updated.status_transitioned",
  "event_object_id": "77f4381c-a39d-5f6e-a383-0b71007c4f19",
  "event_object_status": "settled",
  "event_object": {
    "id": "77f4381c-a39d-5f6e-a383-0b71007c4f19",
    "card_account_id": "5a86836d-cee5-44a5-a89b-5957470334b2",
    "customer_id": "15ff6495-9947-4b18-8b46-319668cbd69a",
    "amount": "-10.25",
    "original_amount": "-10.25",
    "settled_amount": "-10.25",
    "currency": "usd",
    "category": "purchase",
    "status": "settled",
    "created_at": "2025-02-04T05:19:20.000Z",
    "authorized_at": "2025-02-04T05:19:25.000Z",
    "posted_at": "2025-02-06T03:01:30.000Z",
    "updated_at": "2025-02-06T03:01:30.000Z",
    "merchant_category_code": "4121",
    "merchant_name": "ROCKET RIDES",
    "merchant_location": "SAN FRANCISCO, CAUS",
    "transaction_description": "ROCKET RIDES 8442613753, CAUS"
  },
  "event_object_changes": {
    "status": ["approved", "settled"],
    "settled_amount": [null, "-10.25"],
    “posted_at”: [null, “2025-02-06T03:01:30.000Z”],
    "updated_at": ["2025-02-04T05:19:25.000Z", "2025-02-06T03:01:30.000Z"],
  },
  "event_created_at": "2025-02-04T05:19:20.000Z",
}
If you want, you can also fetch all settled transactions via the following API:
Request
curl 'https://api.bridge.xyz/v0/customers/{customerID}/card_accounts/{cardAccountID}/transactions \
 --header 'Content-Type: application/json' \
 --header 'Api-Key: <API Key>'