Overview
The cards sandbox environment enables you to test your card issuance logic and product experience from your first day developing, without requiring any approval by our bank partner, issuance partner, or card network. In addition, we have full support for noncustodial spend on Solana devnet (with more chains coming soon), which allows you to build and test a fully functional card issuance product in sandbox with noncustodial wallets end-to-end.
While most endpoints are the same as the standard Bridge API, we do offer some additional features in order to allow you to test money movement in a safe and entirely programmatic fashion.
When interacting with the sandbox, all requests should go to https://api.sandbox.bridge.xyz
Integration
Setup
In order to start your integration, you will need to call the following API which bootstraps your sandbox environment and funds flow.
Currently, noncustodial wallets are only supported on Solana devnet. We also support top_up, which simulates funding deposits within the Bridge system.
curl -X POST 'https://api.sandbox.bridge.xyz/v0/cards/enable' \
--header 'Content-Type: application/json' \
--header 'Api-Key: <ApiKey>' \
--header 'Idempotency-Key: <IdempotencyKey>' \
-d '{"funding_strategy": "top_up"}'
Creating a card account
Please follow the steps outlined here to create a customer, using the sandbox API URL. You can then use the provision card account endpoint to create a card account in Sandbox, like so:
curl -X POST 'https://api.sandbox.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"
}'
Simulate balance top up
In production, you could top up the card balance by sending funds to the address specified in the funding_instructions of the card account. As it is a normal crypto address, this could be done in a variety of ways, including using Bridge’s very own transfers and virtual accounts APIs.
In sandbox, you can simulate topping up the card balance with the following API:
curl -X POST 'https://api.sandbox.bridge.xyz/v0/customers/<CustomerId>/card_accounts/<CardAccountId>/simulate_balance_top_up' \
--header 'Content-Type: application/json' \
--header 'Api-Key: <ApiKey>' \
--header 'Idempotency-Key: <IdempotencyKey>' \
-d '{"amount": "1000.0"}'
Simulate card transactions
Use these APIs to simulate the full card transaction lifecycle.
Authorization and settlement
Simulates a standard purchase with settlement.
Step 1: Authorize
Step 2: Settle
Simulate an initial authorization for $100:curl -X POST 'https://api.sandbox.bridge.xyz/v0/customers/<CustomerId>/card_accounts/<CardAccountId>/simulate_authorization' \
--header 'Content-Type: application/json' \
--header 'Api-Key: <ApiKey>' \
--header 'Idempotency-Key: <IdempotencyKey>' \
-d '{"amount": "100.0", "merchant_name": "test"}'
authorization_id from the response for settlement. Simulate settlement for $100:curl -X POST 'https://api.sandbox.bridge.xyz/v0/customers/<CustomerId>/card_accounts/<CardAccountId>/simulate_settlement' \
--header 'Content-Type: application/json' \
--header 'Api-Key: <ApiKey>' \
--header 'Idempotency-Key: <IdempotencyKey>' \
-d '{"amount": "100.0", "merchant_name": "test", "authorization_id": "<AuthorizationIdFromStep1>"}'
Incremental authorization
Simulates a transaction where the authorization amount changes before settlement (e.g., adding a tip at a restaurant).
Step 1: Preauthorize
Step 2: Increment
Step 3: Complete
Step 4: Settle
Simulate an initial hold for $200:curl -X POST 'https://api.sandbox.bridge.xyz/v0/customers/<CustomerId>/card_accounts/<CardAccountId>/simulate_incremental_authorization' \
--header 'Content-Type: application/json' \
--header 'Api-Key: <ApiKey>' \
--header 'Idempotency-Key: <IdempotencyKey>' \
-d '{"amount": "200.0", "merchant_name": "test", "transaction_type": "preauthorization"}'
authorization_id for the next step. Add an incremental charge of $20:curl -X POST 'https://api.sandbox.bridge.xyz/v0/customers/<CustomerId>/card_accounts/<CardAccountId>/simulate_incremental_authorization' \
--header 'Content-Type: application/json' \
--header 'Api-Key: <ApiKey>' \
--header 'Idempotency-Key: <IdempotencyKey>' \
-d '{"amount": "20.0", "merchant_name": "test", "transaction_type": "incremental_preauthorization", "original_authorization_id": "<AuthorizationIdFromStep1>"}'
Complete the authorization for the final amount of $220:curl -X POST 'https://api.sandbox.bridge.xyz/v0/customers/<CustomerId>/card_accounts/<CardAccountId>/simulate_incremental_authorization' \
--header 'Content-Type: application/json' \
--header 'Api-Key: <ApiKey>' \
--header 'Idempotency-Key: <IdempotencyKey>' \
-d '{"amount": "220.0", "merchant_name": "test", "transaction_type": "completion", "original_authorization_id": "<AuthorizationIdFromStep2>"}'
Settle the transaction for $220:curl -X POST 'https://api.sandbox.bridge.xyz/v0/customers/<CustomerId>/card_accounts/<CardAccountId>/simulate_settlement' \
--header 'Content-Type: application/json' \
--header 'Api-Key: <ApiKey>' \
--header 'Idempotency-Key: <IdempotencyKey>' \
-d '{"amount": "220.0", "merchant_name": "test", "authorization_id": "<AuthorizationIdFromStep3>"}'
Authorization reversal
Simulates a transaction that is cancelled before settlement (e.g., purchasing at a retail store and returning the item shortly after).
Step 1: Authorize
Step 2: Reverse
Simulate an initial authorization for $40:curl -X POST 'https://api.sandbox.bridge.xyz/v0/customers/<CustomerId>/card_accounts/<CardAccountId>/simulate_authorization' \
--header 'Content-Type: application/json' \
--header 'Api-Key: <ApiKey>' \
--header 'Idempotency-Key: <IdempotencyKey>' \
-d '{"amount": "40.0", "merchant_name": "test"}'
Simulate a full reversal:curl -X POST 'https://api.sandbox.bridge.xyz/v0/customers/<CustomerId>/card_accounts/<CardAccountId>/simulate_incremental_authorization' \
--header 'Content-Type: application/json' \
--header 'Api-Key: <ApiKey>' \
--header 'Idempotency-Key: <IdempotencyKey>' \
-d '{"amount": "40.0", "merchant_name": "test", "transaction_type": "reversal", "original_authorization_id": "<AuthorizationIdFromStep1>"}'
