Guides

Quick start: creating your first card

Suggest Edits

Overview

Creating a card and running your first transaction is the best way to get a feel for the Bridge Cards API.

Instructions

Creating a card

To create your first card you will need to both create a customer and then create a card for them to use.

1. Create a customer

📘

You can skip this step if you already have a customer from an existing Bridge integration.

For more details see: https://apidocs.bridge.xyz/docs/customers-api 

curl --X POST 'https://api.bridge.xyz/v0/customers' \
--header 'Content-Type: application/json' \
--header 'Api-Key: <API Key>' \
--header 'Idempotency-Key: <generate a uuid>' \
--data-raw '{
  "type": "individual",
  "first_name": "John",
  "last_name": "Doe",
  "email": "[email protected]",
  "address": {
    "street_line_1": "123 Main St",
    "city": "New York City",
    "subdivision": "New York",
    "postal_code": "10001",
    "country": "USA"
  },
  "birth_date": "2007-01-01",
  "signed_agreement_id": "d536a227-06d3-4de1-acd3-8b5131730480",
  "identifying_information": [
    {
      "type": "ssn",
      "issuing_country": "usa",
      "number": "xxx-xx-xxxx"
    },
    {
      "type": "drivers_license",
      "issuing_country": "usa",
      "number": "xxxxxxxxxxxxx",
      "image_front": "data:image/jpg;base64,...",
      "image_back": "data:image/jpg;base64,..."
    }
  ]
}

2. Create a card

Once you have a customer you can issue them a card to be used. Cards may only be used with a single currency/network and this cannot be changed after creation.

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>' \
 -d client_reference_id="test-card-reference-id1" \
 -d currency="usdc" \
 -d chain="solana" \

View card details

After creating a card, you can then retrieve the card details in order to render key details to your user. This includes standard information such as BIN or expiration date, as well as a card image which will show critical information such as the PIN and CVC.

curl 'https://api.bridge.xyz/v0/customers/<customerID>/card_accounts/<cardAccountID>'\
 --header 'Content-Type: application/json' \
 --header 'Api-Key: <API Key>' \
 -d client_reference_id="test-card-reference-id1" \
 -d currency="usdc" \
 -d chain="solana" \ 

{
  "id": "XXX-YYY",
  ....
  "card_image_url": "https://...",
  "status": "active",
  "card_details": {
    "last_4": "1264",
    "expiry": "10/24",
    "bin": "44325280"
  },
  ...
}

3. Create a test transaction

Now that you have the details for your card, you can use it to make transactions! Use your Bridge issued card like any normal card in e-commerce checkout flows.

We recommend testing your card on a merchant you are familiar with and who you know have a stable payments integration.

4. Listen for pending transactions

In order to get an accurate view of pending, but not yet settled transactions, you should listen to the card_transaction webhook feed. 

{
  "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",
}

If you want, you can also fetch pending transactions ad hoc via the following API:

curl -X POST 'https://api.bridge.xyz/v0/customers/{customerID}/card_accounts/{cardAccountID}/authorizations\
 --header 'Content-Type: application/json' \
 --header 'Api-Key: <API Key>'

5. Listen for settled transactions

In order to see when transactions “settle” and become final, you should listen to the stream of posted_card_account_transaction webhooks.

As an example:

{
  "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 manually via the following API:

curl 'https://api.bridge.xyz/v0/customers/{customerID}/card_accounts/{cardAccountID}/transactions \
 --header 'Content-Type: application/json' \
 --header 'Api-Key: <API Key>'

Updated 4 days ago

What’s Next