Bridge Cards API
The Cards API from Bridge — 18 operation(s) for cards.
The Cards API from Bridge — 18 operation(s) for cards.
openapi: 3.0.2
info:
title: Bridge API Keys Cards API
description: APIs to move into, out of, and between any form of a dollar
version: '1'
servers:
- url: https://api.bridge.xyz/v0
description: The base path for all resources
security:
- ApiKey: []
tags:
- name: Cards
paths:
/customers/{customerID}/card_accounts/{cardAccountID}/pin:
post:
summary: Create Card PIN Update URL
description: Generates a URL that can be used to render a secure frame to update the PIN for a card account. The URL is single-use and time-limited.
tags:
- Cards
parameters:
- $ref: '#/components/parameters/CustomerIDParameter'
- $ref: '#/components/parameters/IdempotencyKeyParameter'
- name: cardAccountID
in: path
required: true
description: The ID of the card account
schema:
type: string
format: uuid
responses:
'200':
description: URL to update the card PIN
content:
application/json:
schema:
$ref: '#/components/schemas/CardPinUpdateResponse'
'401':
$ref: '#/components/responses/AuthenticationError'
'400':
$ref: '#/components/responses/BadRequestError'
'500':
$ref: '#/components/responses/UnexpectedError'
/customers/{customerID}/card_accounts/{cardAccountID}/ephemeral_keys:
post:
summary: Generate an Ephemeral Key to Reveal Card Details
description: Generates a one-time ephemeral key that can be used to reveal card details. Please see the integration guide on [safely revealing card details](https://apidocs.bridge.xyz/docs/safely-reveal-card-details-to-customers) for more information.
tags:
- Cards
parameters:
- $ref: '#/components/parameters/CustomerIDParameter'
- $ref: '#/components/parameters/IdempotencyKeyParameter'
- name: cardAccountID
in: path
required: true
description: The ID of the card account
schema:
type: string
format: uuid
requestBody:
description: The client-side nonce that will be associated with the ephemeral key
content:
application/json:
schema:
$ref: '#/components/schemas/PostCardAccountEphemeralKeyInput'
responses:
'200':
description: Ephemeral key to reveal card details
content:
application/json:
schema:
$ref: '#/components/schemas/CardAccountEphemeralKeyResponse'
'401':
$ref: '#/components/responses/AuthenticationError'
'400':
$ref: '#/components/responses/BadRequestError'
'500':
$ref: '#/components/responses/UnexpectedError'
/developer/cards/summary:
get:
summary: Get a summary of your card program
description: Get a summary of your card program, optionally for a specific period.
tags:
- Cards
parameters:
- $ref: '#/components/parameters/CardProgramSummaryPeriodParameter'
- $ref: '#/components/parameters/CardProgramSummaryPeriodKeyParameter'
responses:
'200':
description: The summary of a card program
content:
application/json:
schema:
$ref: '#/components/schemas/CardProgramSummary'
'401':
$ref: '#/components/responses/AuthenticationError'
'400':
$ref: '#/components/responses/BadRequestError'
'500':
$ref: '#/components/responses/UnexpectedError'
/developer/cards/designs:
get:
summary: Get a listing of your card program's card designs
description: Get a listing of the designs that you can use to issue a card with.
tags:
- Cards
responses:
'200':
description: A listing of the designs that you can use to issue a card with.
content:
application/json:
schema:
$ref: '#/components/schemas/CardDesigns'
'401':
$ref: '#/components/responses/AuthenticationError'
'400':
$ref: '#/components/responses/BadRequestError'
'500':
$ref: '#/components/responses/UnexpectedError'
/customers/{customerID}/card_accounts/{cardAccountID}:
parameters:
- $ref: '#/components/parameters/CustomerIDParameter'
- $ref: '#/components/parameters/CardAccountIDParameter'
get:
summary: Retrieve a card account
tags:
- Cards
description: Retrieve the card account with the specified ID
responses:
'200':
description: The retrieved card account
content:
application/json:
schema:
$ref: '#/components/schemas/CardAccount'
'401':
$ref: '#/components/responses/AuthenticationError'
'500':
$ref: '#/components/responses/UnexpectedError'
put:
summary: Update a card account
description: Update a card account. Supports changing the settlement currency or closing a card account by setting the status to "inactive". Closing permanently cancels all associated cards and is irreversible.
tags:
- Cards
requestBody:
description: The card account update
required: true
content:
application/json:
schema:
type: object
properties:
currency:
type: string
description: The new settlement currency for the card account.
status:
type: string
enum:
- inactive
description: The desired status for the card account. Currently only "inactive" is supported.
responses:
'200':
description: The updated card account
content:
application/json:
schema:
$ref: '#/components/schemas/CardAccount'
'401':
$ref: '#/components/responses/AuthenticationError'
'400':
$ref: '#/components/responses/BadRequestError'
'500':
$ref: '#/components/responses/UnexpectedError'
/customers/{customerID}/card_accounts:
get:
summary: Get all card accounts
tags:
- Cards
description: Retrieve all card accounts for a customer. Currently, only one account is supported. An empty array will be returned if no card has been provisioned
parameters:
- $ref: '#/components/parameters/CustomerIDParameter'
responses:
'200':
description: List of all card accounts owned by the customer
content:
application/json:
schema:
title: Array of all card accounts
type: object
required:
- count
- data
properties:
count:
type: integer
description: The number of card accounts returned
data:
type: array
minItems: 0
items:
$ref: '#/components/schemas/CardAccount'
'401':
$ref: '#/components/responses/AuthenticationError'
'500':
$ref: '#/components/responses/UnexpectedError'
post:
summary: Provision a card account
description: 'Provision a card account. NOTE: the legacy Bridge Cards API is deprecated, and stablecoin card issuing capabilities are now natively integrated into Stripe Issuing. Please see [this guide](https://apidocs.bridge.xyz/platform/cards/overview/stripe-issuing) for more details on how to enable your account for Stripe Issuing.'
deprecated: true
tags:
- Cards
parameters:
- $ref: '#/components/parameters/IdempotencyKeyParameter'
- $ref: '#/components/parameters/CustomerIDParameter'
requestBody:
description: The card account to be provisioned
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PostCardAccountsInput'
responses:
'201':
description: The successfully created card account
content:
application/json:
schema:
$ref: '#/components/schemas/CardAccount'
'401':
$ref: '#/components/responses/AuthenticationError'
'400':
$ref: '#/components/responses/BadRequestError'
'500':
$ref: '#/components/responses/UnexpectedError'
/customers/{customerID}/card_accounts/{cardAccountID}/freeze:
post:
summary: Place a freeze on the card account
description: Place a freeze on the card account
tags:
- Cards
parameters:
- $ref: '#/components/parameters/IdempotencyKeyParameter'
- $ref: '#/components/parameters/CustomerIDParameter'
- $ref: '#/components/parameters/CardAccountIDParameter'
requestBody:
description: The freeze to be placed on the card account
content:
application/json:
schema:
$ref: '#/components/schemas/PostCardFreezeInput'
responses:
'200':
description: The successfully placed freeze
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/CardFreeze'
properties:
status:
type: string
description: The processing status of the freeze request
readOnly: true
enum:
- freeze_created
- freeze_replaced
'401':
$ref: '#/components/responses/AuthenticationError'
'400':
$ref: '#/components/responses/BadRequestError'
'500':
$ref: '#/components/responses/UnexpectedError'
/customers/{customerID}/card_accounts/{cardAccountID}/unfreeze:
post:
summary: Unfreeze the card account
description: Remove the freeze on the card account placed by the specified initiator
tags:
- Cards
parameters:
- $ref: '#/components/parameters/IdempotencyKeyParameter'
- $ref: '#/components/parameters/CustomerIDParameter'
- $ref: '#/components/parameters/CardAccountIDParameter'
requestBody:
description: A request to unfreeze the card account
content:
application/json:
schema:
$ref: '#/components/schemas/PostCardUnfreezeInput'
responses:
'200':
description: The successfully removed freeze
content:
application/json:
schema:
$ref: '#/components/schemas/CardUnfreezeResponse'
'401':
$ref: '#/components/responses/AuthenticationError'
'400':
$ref: '#/components/responses/BadRequestError'
'500':
$ref: '#/components/responses/UnexpectedError'
/customers/{customerID}/card_accounts/{cardAccountID}/create_mobile_wallet_provisioning_request:
post:
summary: Create a mobile wallet push provisioning request
description: Create a request to push-provision a virtual card to a mobile wallet. This endpoint is part of a multiple-step integration that must be completed with each mobile wallet partner
tags:
- Cards
parameters:
- $ref: '#/components/parameters/IdempotencyKeyParameter'
- $ref: '#/components/parameters/CustomerIDParameter'
- $ref: '#/components/parameters/CardAccountIDParameter'
requestBody:
description: A mobile wallet push provisioning request
content:
application/json:
schema:
$ref: '#/components/schemas/PostCardPushProvisioningInput'
responses:
'200':
description: A successful push provisioning response
content:
application/json:
schema:
$ref: '#/components/schemas/CardPushProvisioningResponse'
'401':
$ref: '#/components/responses/AuthenticationError'
'400':
$ref: '#/components/responses/BadRequestError'
'500':
$ref: '#/components/responses/UnexpectedError'
/customers/{customerID}/card_accounts/{cardAccountID}/authorizations:
get:
summary: Retrieve pending card authorizations
description: 'Retrieve pending card authorizations.
Note: this endpoint is not paginated'
tags:
- Cards
parameters:
- $ref: '#/components/parameters/CustomerIDParameter'
- $ref: '#/components/parameters/CardAccountIDParameter'
- $ref: '#/components/parameters/CardAuthorizationLimitParameter'
- $ref: '#/components/parameters/StartingTimeParameter'
- $ref: '#/components/parameters/EndingTimeParameter'
- $ref: '#/components/parameters/CardAuthorizationStatusParameter'
responses:
'200':
description: Pending card authorizations
content:
application/json:
schema:
title: List of pending card authorizations
type: object
required:
- count
- data
properties:
count:
type: integer
description: The number of card authorizations returned
data:
type: array
minItems: 0
items:
$ref: '#/components/schemas/CardAuthorization'
'401':
$ref: '#/components/responses/AuthenticationError'
'500':
$ref: '#/components/responses/UnexpectedError'
/customers/{customerID}/card_accounts/{cardAccountID}/transactions:
get:
summary: Retrieve card transactions
description: Retrieve completed card transactions and card-related crypto transaction activities
tags:
- Cards
parameters:
- $ref: '#/components/parameters/CustomerIDParameter'
- $ref: '#/components/parameters/CardAccountIDParameter'
- $ref: '#/components/parameters/CardTransactionLimitParameter'
- $ref: '#/components/parameters/StartingTimeParameter'
- $ref: '#/components/parameters/EndingTimeParameter'
- $ref: '#/components/parameters/PageSizeParameter'
- $ref: '#/components/parameters/PageNumberParameter'
- $ref: '#/components/parameters/CardTransactionStatusParameter'
- $ref: '#/components/parameters/CardTransactionPaginationTokenParameter'
- $ref: '#/components/parameters/CardTransactionCategoryFamilyParameter'
responses:
'200':
description: Card transactions
content:
application/json:
schema:
title: List of card transactions
type: object
required:
- page
- count
- total_pages
- total_count
- data
properties:
page:
type: integer
description: The current page number, starting at 1. Note that this will be returned only for navigating posted transactions.
pagination_token:
type: string
description: The pagination token to be used to retrieve the next page of transactions. If not provided, use the `page` parameter to navigate by page number.
count:
type: integer
description: The number of transactions returned
total_pages:
type: integer
description: The total number of pages
total_count:
type: integer
description: The total number of transactions
data:
type: array
minItems: 0
items:
$ref: '#/components/schemas/CardTransaction'
'401':
$ref: '#/components/responses/AuthenticationError'
'500':
$ref: '#/components/responses/UnexpectedError'
/customers/{customerID}/card_accounts/{cardAccountID}/transactions/{transactionID}:
get:
summary: Retrieve a card transaction
description: Retrieve a card transaction with the specified ID
tags:
- Cards
parameters:
- $ref: '#/components/parameters/CustomerIDParameter'
- $ref: '#/components/parameters/CardAccountIDParameter'
- $ref: '#/components/parameters/CardTransactionIDParameter'
responses:
'200':
description: Card transactions
content:
application/json:
schema:
$ref: '#/components/schemas/CardTransaction'
'401':
$ref: '#/components/responses/AuthenticationError'
'500':
$ref: '#/components/responses/UnexpectedError'
/customers/{customerID}/card_accounts/{cardAccountID}/auth_controls:
get:
summary: Retrieve authorization controls
description: Retrieve the applicable spend limits for the given card account
tags:
- Cards
parameters:
- $ref: '#/components/parameters/CustomerIDParameter'
- $ref: '#/components/parameters/CardAccountIDParameter'
responses:
'200':
description: The authorization controls
content:
application/json:
schema:
title: Authorization controls
type: object
required:
- customer_id
- card_account_id
- spending_limits
properties:
customer_id:
type: string
description: The ID of the customer
card_account_id:
type: string
description: The ID of the card account
spending_limits:
type: array
description: The various spending limits for the card account for the current time period
items:
$ref: '#/components/schemas/CardSpendingLimit'
'401':
$ref: '#/components/responses/AuthenticationError'
'500':
$ref: '#/components/responses/UnexpectedError'
/customers/{customerID}/card_accounts/{cardAccountID}/deposit_addresses:
post:
summary: Provision an additional top-up deposit address for the card account
description: Provision an additional deposit address for the card account, to allow topping up the card from multiple chains. This is only applicable to Bridge-custodied top-up card accounts. These additional deposit addresses will also be shown in the `additional_funding_instructions` field when fetching the card account details afterwards.
tags:
- Cards
parameters:
- $ref: '#/components/parameters/IdempotencyKeyParameter'
- $ref: '#/components/parameters/CustomerIDParameter'
- $ref: '#/components/parameters/CardAccountIDParameter'
requestBody:
description: The chain to provision the new deposit address on.
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PostCardAccountDepositAddressInput'
responses:
'200':
description: Details of the successfully created deposit address
content:
application/json:
schema:
$ref: '#/components/schemas/CardAccountFundingInstructions'
'401':
$ref: '#/components/responses/AuthenticationError'
'400':
$ref: '#/components/responses/BadRequestError'
'500':
$ref: '#/components/responses/UnexpectedError'
/customers/{customerID}/card_accounts/{cardAccountID}/withdrawals:
post:
summary: Create a funds withdrawal request
description: Request a funds withdrawal from the card account, applicable to top-up accounts only. For Bridge wallets, create a [transfer](/api-reference/transfers/create-a-transfer) from the Bridge wallet.
tags:
- Cards
parameters:
- $ref: '#/components/parameters/IdempotencyKeyParameter'
- $ref: '#/components/parameters/CustomerIDParameter'
- $ref: '#/components/parameters/CardAccountIDParameter'
requestBody:
description: The withdrawal request
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CardWithdrawal'
responses:
'201':
description: The successfully created card funds withdrawal
content:
application/json:
schema:
$ref: '#/components/schemas/CardWithdrawal'
'401':
$ref: '#/components/responses/AuthenticationError'
'400':
$ref: '#/components/responses/BadRequestError'
'500':
$ref: '#/components/responses/UnexpectedError'
get:
summary: Retrieve the withdrawal history of funds
description: Retrieve the withdrawal history of funds, applicable to top-up accounts only
tags:
- Cards
parameters:
- $ref: '#/components/parameters/CustomerIDParameter'
- $ref: '#/components/parameters/CardAccountIDParameter'
- $ref: '#/components/parameters/LimitParameter'
- $ref: '#/components/parameters/WithdrawalStartingAfterParameter'
- $ref: '#/components/parameters/WithdrawalEndingBeforeParameter'
responses:
'200':
description: The withdrawal history
content:
application/json:
schema:
title: List of withdrawals
type: object
required:
- count
- data
properties:
count:
type: integer
description: The number of withdrawals returned
data:
type: array
minItems: 0
items:
$ref: '#/components/schemas/CardWithdrawal'
'401':
$ref: '#/components/responses/AuthenticationError'
'500':
$ref: '#/components/responses/UnexpectedError'
/customers/{customerID}/card_accounts/{cardAccountID}/withdrawals/{cardWithdrawalID}:
get:
summary: Retrieve a card withdrawal
description: Retrieve a card withdrawal with the specified ID, applicable to top-up accounts only
tags:
- Cards
parameters:
- $ref: '#/components/parameters/CustomerIDParameter'
- $ref: '#/components/parameters/CardAccountIDParameter'
- $ref: '#/components/parameters/CardWithdrawalIDParameter'
responses:
'200':
description: The retrieved withdrawal
content:
application/json:
schema:
$ref: '#/components/schemas/CardWithdrawal'
'401':
$ref: '#/components/responses/AuthenticationError'
'500':
$ref: '#/components/responses/UnexpectedError'
/customers/{customerID}/card_accounts/{cardAccountID}/statements/{period}.pdf:
post:
summary: Generate a card account statement
description: Generate a card account statement for the specified period
tags:
- Cards
parameters:
- $ref: '#/components/parameters/CustomerIDParameter'
- $ref: '#/components/parameters/CardAccountIDParameter'
- $ref: '#/components/parameters/CardStatementPeriodParameter'
responses:
'200':
description: The HTTP response that includes a PDF file as an attachment, with the `Content-Type` set to `application/pdf` and the `Content-Disposition` header configured to indicate it is a statement PDF attachment
content:
application/pdf:
schema:
type: string
format: binary
headers:
Content-Disposition:
description: Indicates the content is an attachment with a statement PDF file
schema:
type: string
example: inline; filename="statement_202412.pdf"; filename*=UTF-8''statement_202412.pdf
'401':
$ref: '#/components/responses/AuthenticationError'
'400':
$ref: '#/components/responses/BadRequestError'
'500':
$ref: '#/components/responses/UnexpectedError'
/cardholders/{cardholderID}/cards/{cardID}/statements/{period}.pdf:
post:
summary: Generate a card statement using Stripe IDs
description: Generate a card account statement for the specified period, using Stripe cardholder and card IDs instead of Bridge internal IDs
tags:
- Cards
parameters:
- name: cardholderID
in: path
required: true
schema:
type: string
description: The Stripe cardholder ID (e.g. `ich_...`)
- name: cardID
in: path
required: true
schema:
type: string
description: The Stripe card ID (e.g. `ic_...`)
- $ref: '#/components/parameters/CardStatementPeriodParameter'
responses:
'200':
description: The HTTP response that includes a PDF file as an attachment, with the `Content-Type` set to `application/pdf` and the `Content-Disposition` header configured to indicate it is a statement PDF attachment
content:
application/pdf:
schema:
type: string
format: binary
headers:
Content-Disposition:
description: Indicates the content is an attachment with a statement PDF file
schema:
type: string
example: inline; filename="statement_202412.pdf"; filename*=UTF-8''statement_202412.pdf
'401':
$ref: '#/components/responses/AuthenticationError'
'400':
$ref: '#/components/responses/BadRequestError'
'500':
$ref: '#/components/responses/UnexpectedError'
components:
schemas:
PostCardAccountDepositAddressInput:
description: The details of the new deposit address to be provisioned.
required:
- chain
properties:
chain:
type: string
description: The chain to provision the new deposit address on.
$ref: '#/components/schemas/OfframpChainForCards'
CardFreezeInitiator:
type: string
description: The party that initiated the freeze. A freeze can be initiated by either the customer or developer. Only one freeze per initiator can be active at a time. If a new freeze is initiated by the same party, it overwrites any existing freeze
enum:
- developer
- customer
FiatCurrency:
type: string
enum:
- usd
PostCardPushProvisioningInput:
required:
- initiator
properties:
wallet_provider:
allOf:
- $ref: '#/components/schemas/CardWalletProvider'
description: The wallet provider of the push provisioning request
apple_pay:
description: Apple Pay specific provisioning request data. Required for `apple_pay` wallet provider.
required:
- leaf_cert
- subordinate_cert
- nonce
- nonce_signature
properties:
encoding:
type: string
description: Specifies the encoding of each field in the Apple Pay provisioning request. Defaults to `hex` if unspecified.
enum:
- base64
- hex
leaf_cert:
type: string
description: The leaf certificate returned by the wallet provider that was signed using the subordinate cert. The binary data of this certificate should be hex (case-insensitive) or base64 encoded, as specified by the encoding field
subordinate_cert:
type: string
description: The subordinate certificate returned by the wallet provider that was signed using the wallet provider's Certificate Authority (CA) certificate. The binary data of this certificate should be hex (case-insensitive) or base64 encoded, as specified by the encoding field
nonce:
type: string
description: The nonce value returned by Apple Pay. It should be hex (case-insensitive) or base64 encoded, as specified by the encoding field
nonce_signature:
type: string
description: The nonce signature value returned by Apple Pay. It should be hex (case-insensitive) or base64 encoded, as specified by the encoding field
google_pay:
description: Google Pay specific push provisioning request data. Required for `google_pay` wallet provider.
required:
- client_wallet_account_id
- client_device_id
properties:
client_wallet_account_id:
type: string
description: Value returned by Google Pay for use with Visa
client_device_id:
type: string
description: Value returned by Google Pay for use with Visa
CardSpendingLimit:
description: A spending limit for a card account
required:
- period
- total_amount
- remaining_amount
properties:
period:
type: string
description: The period of the spending limit
enum:
- daily
- trial_lifetime
timezone:
type: string
description: The timezone of the spending limit, only applicable to spending limits that have a `next_reset_at`
next_reset_at:
type: string
description: The next reset time of the spending limit, in ISO8601 format
total_amount:
type: string
description: The total amount of the spending limit
remaining_amount:
type: string
description: The remaining amount of the spending limit
currency:
$ref: '#/components/schemas/FiatCurrency'
description: The currency of the spending limit
CardPushProvisioningResponse:
description: The mobile wallet push provisioning response
required:
- card_account_id
- initiator
- reason
- created_at
- status
properties:
wallet_provider:
allOf:
- $ref: '#/components/schemas/CardWalletProvider'
description: The wallet provider of the push provisioning request
apple_pay:
description: The detailed provisioning request data that need to be sent directly to the `apple_pay` wallet provider
properties:
activation_data:
type: string
description: The request's activation data. This field is always Base64-encoded
encrypted_pass_data:
type: string
description: An encrypted JSON file containing the sensitive information needed to add a card to a wallet. This field is always Base64-encoded
ephemeral_public_key:
type: string
description: A generated key that is combined with a private key. This field is always Base64-encoded
google_pay:
description: The detailed provisioning request data that need to be sent directly to the `google_pay` wallet provider
properties:
opaque_payment_card:
type: string
description: A Base64-encoded or Base64url-encoded opaque string
CardUnfreezeResponse:
description: Card unfreeze response
required:
- card_account_id
- initiator
- reason
- created_at
- status
allOf:
- $ref: '#/components/schemas/CardFreeze'
- properties:
initiator:
description: The initiator of the removed freeze
reason:
description: The reason of the removed freeze
reason_detail:
description: The reason detail of the removed freeze
starting_at:
description: The start time of the removed freeze, in ISO8601 format
ending_at:
description: The end time of the removed freeze, in ISO8601 format
created_at:
descrip
# --- truncated at 32 KB (66 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bridge/refs/heads/main/openapi/bridge-cards-api-openapi.yml