Skip to main content

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!

Connections are an Enterprise feature. Contact support@basistheory.com to request access.

Charge Stored Cards

If you are not yet storing your customers' cards with Basis Theory, here are a few guides you can explore:

Getting Started​

To get started, you will need to create a Basis Theory Account and a TEST Tenant.

Make sure to use your work email (e.g., john.doe@yourcompany.com)

Provisioning Resources​

In this section, we will explore the bare minimum resources to create a new Connection that will process card transactions.

This is a one-time setup that takes about 10 minutes to complete ⏰.

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
Save the API Key from the created Management Application as it will be used later in this guide.

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" ]
  }'
Be sure to replace <MANAGEMENT_API_KEY> with the Management API Key you created previously.
Save the API Key from the created Private Application as it will be used later in this guide.

Connection​

The last resource to create is a Connection, which will be responsible for transacting with the Payment Processor.

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
}'
Be sure to replace <MANAGEMENT_API_KEY> with the Management API Key you created previously.
Save the 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/transactions' \
-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"
}'
Be sure to replace <PRIVATE_API_KEY> with the Private API Key you created previously.
Be sure to replace <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.

Learn More​