Process Card Payments (Connections)
Storing your customers' cards with Basis Theory platform grants you the ability to seamlessly shift between payment processors, giving you competitive advantages including payment flexibility, reliability, cost savings, increased acceptance rates, and future-proofing your business against processor downtime or shutdown.
This guide will explore how to process card payments using unified Payment Orchestration APIs, bearing minimal configuration requirements. By following the steps presented below, you are substantially de-scoping your servers and database from PCI DSS compliance. If you want to learn more about how we can help you meet up to 95% of the PCI requirements or if you need help filling out your SAQ, reach out to our team!
If you are not yet storing your customers' cards with Basis Theory, here are a few guides you can explore:
- Collect Cards - capture cards in the frontend;
- Receive Cards via API / Webhooks - receive cards in API requests;
- Issue Cards - create brand-new cards using an Issuer API;
- Import Cards from a Payments Processor - migrate to Basis Theory.
Getting Started
To get started, you will need to create a Basis Theory Account and a TEST Tenant.
Provisioning Resources
In this section, we will explore the bare minimum resources to create a new Connection that will process card transactions.
Management Application
To create all subsequent resources, you will need a Management Application.
Click here to create a Management Application or login to your Basis Theory account and create a new application with the following settings:
- Name - Resource Creator
- Application Type - Management
- Permissions:
application:create
,orchestration:connections:create
Private Application
Next you will need a Private Application to create tokens within the Proxy, and invoke it from your servers. This application represents your Backend.
Using the Management Application key to authorize the request, call Basis Theory API to create a new Private Application:
curl "https://api.basistheory.com/applications" \
-X "POST" \
-H "BT-API-KEY: <MANAGEMENT_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"name": "Backend",
"type": "private",
"permissions": [ "token:create", "token:read", "token:use" ]
}'
<MANAGEMENT_API_KEY>
with the Management API Key you created previously.Connection
The last resource to create is a Connection, which will be responsible for transacting with the Payment Processor.
- Stripe
- Adyen
- dLocal
- Checkout.com
- Other
curl --location "https://api.basistheory.com/orchestration/connections" \
-H "BT-API-KEY: <MANAGEMENT_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"connection_formula_id": "stripe-card",
"display_name": "Stripe",
"fields": [
{
"key": "secret_key",
"value": "<STRIPE_SECRET_KEY>"
}
],
"accepted_countries": [ "US" ],
"accepted_currencies": [ "USD" ],
"active": true
}'
curl --location "https://api.basistheory.com/orchestration/connections" \
-H "BT-API-KEY: <MANAGEMENT_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"connection_formula_id": "adyen-card",
"display_name": "Adyen",
"fields": [
{
"key": "api_key",
"value": "<ADYEN_API_KEY>"
},
{
"key": "merchant_account",
"value": "<ADYEN_MERCHANT_ACCOUNT>"
}
],
"accepted_countries": [ "US" ],
"accepted_currencies": [ "USD" ],
"active": true
}'
curl --location "https://api.basistheory.com/orchestration/connections" \
-H "BT-API-KEY: <MANAGEMENT_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"connection_formula_id": "dlocal-card",
"display_name": "dLocal",
"fields": [
{
"key": "x_login",
"value": "<DLOCAL_X_LOGIN>"
},
{
"key": "x_trans_key",
"value": "<DLOCAL_TRANS_KEY>"
}
],
"accepted_countries": [ "US" ],
"accepted_currencies": [ "USD" ],
"active": true
}'
curl --location "https://api.basistheory.com/orchestration/connections" \
-H "BT-API-KEY: <MANAGEMENT_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"connection_formula_id": "checkoutcom-card",
"display_name": "dLocal",
"fields": [
{
"key": "public_key",
"value": "<CHECKOUTCOM_PUBLIC_KEY>"
},
{
"key": "secret_key",
"value": "<CHECKOUTCOM_SECRET_KEY>"
},
{
"key": "client_secret",
"value": "<DLOCAL_SECRET_KEY>"
}
],
"accepted_countries": [ "US" ],
"accepted_currencies": [ "USD" ],
"active": true
}'
Click here to see our list of supported connections.
<MANAGEMENT_API_KEY>
with the Management API Key you created previously.id
from the created Connection as it will be used later in this guide.Process a Payment
Now that we have our setup ready, it is time to use Basis Theory's Transactions API to process payments against a selected Connection. To do this, we simply call the API passing a previously created card
token identifier:
curl 'https://api.basistheory.com/orchestration/transaction' \
-X 'POST' \
-H 'BT-API-KEY: <PRIVATE_API_KEY>' \
-H 'Content-Type: application/json' \
-d '{
"connection_id": "<CONNECTION_ID>",
"amount": 1299,
"currency": "USD",
"token": "<BT_TOKEN_ID>",
"intent": "capture"
}'
<PRIVATE_API_KEY>
with the Private API Key you created previously.<CONNECTION_ID>
with the Processor Connection's Id you created previously.Key Considerations
You are not restricted to the Payment Processors listed above. Click here to explore our list of supported connections.
During testing phase, make sure to create tokens using test cards documented by your payment processor, following the desired test scenario. Passing incorrect cards to test/sandbox endpoints may lead to hard-to-debug rejected transactions.
Conclusion
By using our Payments Orchestration APIs, you can confidently transmit cardholder data to Payment Processors in a simple manner without ever touching the card details yourself. This approach not only improves security and mitigates compliance risks but also reduces engineering efforts to maintain connections on your side.