Process Card Payments (Proxy)
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 forward stored cardholder data to any third-party API endpoint, with 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.
Creating a Private Application
Next, you will need a Private Application using our PCI-compliant template Use PCI Tokens
. Click here to create one.
This will create an application with the following Access Controls:
- Permissions:
token:use
- Containers:
/pci/
- Transform:
reveal
Send the Data
We will use Basis Theory Ephemeral Proxy, a tool that transparently performs detokenization, to share the sensitive cardholder data to the Payments Processor or Acquirer API. To do this, we will formulate our HTTPS request as if we were directly connecting to the target endpoint, with the following variations:
- Use the previously-created Private Application Key as the value of the
BT-API-KEY
header; - Specify the target API endpoint as the value for the
BT-PROXY-URL
header; - Pass any additional headers you need the target API to receive, for example
Authorization
,X-API-KEY
, etc.; - Replace the plaintext sensitive cardholder data in the expected payload contents with detokenization expressions that contains token identifiers.
For example, given you have a previously stored card token with the following identifier:
{
"id": "d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4",
"type": "card",
"tenant_id": "15f48eb5-8b52-4cdd-a396-608f7cf001d0",
"data": {
"number": "XXXXXXXXXXXX4242",
"expiration_month": 12,
"expiration_year": 2025
},
"created_by": "4a6ae2a6-79f8-4640-968f-88db913743df",
"created_at": "2023-04-17T12:54:44.8320458+00:00",
"mask": {
"number": "{{ data.number | reveal_last: 4 }}",
"expiration_month": "{{ data.expiration_month }}",
"expiration_year": "{{ data.expiration_year }}"
},
"search_indexes": [],
"containers": [
"/pci/high/"
]
}
Here are a few integration examples of how to send the detokenized card information to third party APIs.
- Stripe
- Adyen
- Chase (Orbital)
- Chase (Stratus)
- Braintree
- TabaPay
- Authorize.net
- Checkout.com
- NMI
- Paysafe
curl 'https://api.basistheory.com/proxy' \
-X 'POST' \
-H 'BT-API-KEY: <API_KEY>' \
-H 'BT-PROXY-URL: https://api.stripe.com/v1/payment_methods' \
-H 'Authorization: Bearer sk_test_51KMGNYGuvJF9SIWEW0y4rKcaQwLVLck2rGB8UEPHzSp1utx7gXKAfZ3DVgjMfAuvBIT42pQhg0sIx2PepEJkXv9g00yIrUwhI4' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'type=card' \
--data-urlencode 'card[number]={{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: "$.data.number" }}' \
--data-urlencode 'card[exp_month]={{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: "$.data" | card_exp: "MM" }}' \
--data-urlencode 'card[exp_year]={{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: "$.data" | card_exp: "YYYY" }}' \
--data-urlencode 'card[cvc]={{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: "$.data.cvc" }}'
curl 'https://api.basistheory.com/proxy' \
-X 'POST' \
-H 'BT-API-KEY: <API_KEY>' \
-H 'BT-PROXY-URL: https://checkout-test.adyen.com/v69/payments' \
-H 'X-API-KEY: Vt(JJ5U5xuVECtg59fm9hBM+cZMWhw+ms2edxM%Rwmu0=Z2n3rGiQjQr-YEYfAq((It-Ocb03Jfob1JqGhogg:J/skGLIwerM=uAuHQDFHZBh+75pKgznYB3QeL7mrnBSeh34YAxLjdGEJQAhKdaU2' \
-H 'Content-Type: application/json' \
-d '{
"amount": {
"value": 100,
"currency": "USD"
},
"paymentMethod": {
"type": "scheme",
"number": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data.number\" }}",
"expiryMonth": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data\" | card_exp: \"MM\" }}",
"expiryYear": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data\" | card_exp: \"YYYY\" }}",
"cvc": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data.cvc\" }}",
"holderName": "John Smith"
},
"reference": "YOUR_ORDER_NUMBER",
"shopperInteraction": "Ecommerce",
"recurringProcessingModel": "CardOnFile",
"storePaymentMethod": "true",
"merchantAccount": "BasisTheoryECOM",
"shopperReference": "YOUR_UNIQUE_SHOPPER_ID",
"returnUrl": "https://your-company.com/..."
}'
curl 'https://api.basistheory.com/proxy' \
-X 'POST' \
-H 'BT-API-KEY: <API_KEY>' \
-H 'BT-PROXY-URL: https://orbitalvar1.chasepaymentech.com/profile' \
-H 'orbitalConnectionUsername: TESTMYCOMPANY1234' \
-H 'orbitalConnectionPassword: f1nwbj32VwW36tV16s55' \
-H 'merchantID: MERCHANTID1234' \
-H 'Content-Type: application/json' \
-d '{
"version": "4.3",
"merchant": {
"bin": "000001"
},
"order": {
"customerProfileFromOrderInd": "A",
"customerProfileOrderOverideInd": "NO"
},
"paymentInstrument": {
"customerAccountType": "CC",
"card": {
"ccAccountNum": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data.number\" }}",
"ccExp": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data\" | card_exp: \"YYYYMM\" }}"
}
},
"profile": {
"customerName": "John Smith",
"customerAddress1": "123 Main St",
"customerCity": "Tampa",
"customerState": "FL",
"customerZIP": "33601"
}
}'
curl 'https://api.basistheory.com/proxy' \
-X 'POST' \
-H 'BT-API-KEY: <API_KEY>' \
-H 'BT-PROXY-URL: https://netconnectvar1.chasepaymentech.com/NetConnect/controller' \
-H 'Auth-MID: M987654321012345' \
-H 'Auth-User: TESTMYCOMPANY1234' \
-H 'Auth-Password: f1nwbj32VwW36tV16s55' \
-H 'Stateless-Transaction: true' \
-H 'Content-Type: SALEM05210/SLM' \
-d 'P74VPMT-18R86WXMM9
VI{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: "$.data.number" | pad_right: 19, "x" }}{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: "$.data" | card_exp: "MMYYYY" }}00003319380000000000008407202NVF AB
XX XXX XXXXX XXXXXXX XX
USABBEVILLE LA70510-7288AC01YEI10000000014064
7930f35b3c06cffe FR1XXXXMTCSTO
000000000000'
curl 'https://api.basistheory.com/proxy' \
-X 'POST' \
-H 'BT-API-KEY: <API_KEY>' \
-H 'BT-PROXY-URL: https://payments.sandbox.braintree-api.com/graphql' \
-H 'Authorization: Basic 123' \
-H 'Braintree-Version: 2019-01-01' \
-H 'Content-Type: application/json' \
-d '{
"query": "mutation TokenizeCreditCard($input: TokenizeCreditCardInput!){
tokenizeCreditCard(input: $input){
paymentMethod{
id
legacyId
usage
details{
... on CreditCardDetails{
brandCode
last4
expirationMonth
expirationYear
}
}
}
}
}",
"variables": {
"input": {
"creditCard": {
"number": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data.number\"}}",
"expirationMonth": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data\" | card_exp: \"MM\"}}",
"expirationYear": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data\" | card_exp: \"YYYY\"}}",
"cvv": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data.cvc\"}}"
}
}
}
}'
curl 'https://api.basistheory.com/proxy' \
-X 'POST' \
-H 'BT-API-KEY: <API_KEY>' \
-H 'BT-PROXY-URL: https://api.tabapay.net/v1/clients/MyClientID/accounts' \
-H 'Authorization: Bearer 123' \
-H 'Content-Type: application/json' \
-d '{
"card": {
"accountNumber": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data.number\" }}",
"expirationDate": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data\" | card_exp: \"YYYYMM\" }}",
"securityCode": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data.cvc\" }}"
},
"owner": {
"name": {
"first": "John",
"last": "Smith"
},
"address": {
"line1": "123 Main St",
"city": "Tampa",
"state": "FL",
"zipcode": "33601"
}
},
"referenceID": "reference_123"
}'
curl 'https://api.basistheory.com/proxy' \
-X 'POST' \
-H 'BT-API-KEY: <API_KEY>' \
-H 'BT-PROXY-URL: https://apitest.authorize.net/xml/v1/request.api' \
-H 'Content-Type: application/json' \
-d '{
"createTransactionRequest": {
"merchantAuthentication": {
"name": "K5yH8dL2zGx",
"transactionKey": "J7rXuPbNvQ9sE3wA"
},
"refId": "123156121",
"transactionRequest": {
"transactionType": "authCaptureTransaction",
"amount": "25",
"payment": {
"creditCard": {
"cardNumber": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data.number\" }}",
"expirationDate": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data\" | card_exp: \"YYYY-MM\" }}",
"cardCode": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data.cvc\" }}"
}
}
}
}
}'
curl 'https://api.basistheory.com/proxy' \
-X 'POST' \
-H 'BT-API-KEY: <API_KEY>' \
-H 'BT-PROXY-URL: https://api.sandbox.checkout.com/payments' \
-H 'Authorization: Bearer sk_sbox_p4qr9st2uy7vx1wa3bc8dl5zg6x'
-H 'Content-Type: application/json' \
-d '{
"source": {
"type": "card",
"number": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data.number\" }}",
"expiry_month": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data\" | card_exp: \"MM\" }}",
"expiry_year": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data\" | card_exp: \"YYYY\" }}"
},
"amount": 6500,
"currency": "USD",
"processing_channel_id": "processing_channel_id",
"reference": "ORD-5023-4E89",
"metadata": {
"udf1": "TEST123",
"coupon_code": "NY2018",
"partner_id": 123989
}
}'
curl 'https://api.basistheory.com/proxy' \
-X 'POST' \
-H 'BT-API-KEY: <API_KEY>' \
-H 'BT-PROXY-URL: https://secure.safewebservices.com/api/transact.php' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'type=sale' \
--data-urlencode 'amount=100.00' \
--data-urlencode 'orderid=5a4ab2409af89' \
--data-urlencode 'security_key=P4qR9sT2uY7vX1wA3bC8dL5zG6xK9yH2' \
--data-urlencode 'ccnumber={{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: "$.data.number" }}' \
--data-urlencode 'ccexp={{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data\" | card_exp: "MMYYYY" }}' \
--data-urlencode 'cvv={{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: "$.data.cvc" }}'
curl 'https://api.basistheory.com/proxy' \
-X 'POST' \
-H 'BT-API-KEY: <API_KEY>' \
-H 'BT-PROXY-URL: https://api.test.paysafe.com/paymenthub/v1/paymenthandles' \
-H 'Authorization: Basic 123'
-H 'Content-Type: application/json' \
-d '{
"merchantRefNum": "a9b2b8d2b9458c8beeb89dbce669",
"transactionType": "ORIGINAL_CREDIT",
"accountId": "1009688230",
"card": {
"cardNum": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data.number\" }}",
"cardExpiry": {
"month": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data\" | card_exp: \"MM\" | to_number }}",
"year": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data\" | card_exp: \"YYYY\" | to_number }}"
},
"cvv": "{{ token: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data.cvc\" }}",
"holderName": "Dilip",
"issuingCountry": "US"
},
"paymentType": "CARD",
"amount": 100,
"currencyCode": "USD",
"customerIp": "172.0.0.1",
"billingDetails": {
"nickName": "Home",
"street": "TEST",
"city": "CA",
"state": "CA",
"country": "US",
"zip": "12345"
},
"merchantDescriptor": {
"dynamicDescriptor": "OnlineStore",
"phone": "1234567899"
}
}'
Key Considerations
You are not restricted to the Payment Processors listed above. As long as your partner can accept cards through an API endpoint, you can invoke it using the Ephemeral Proxy.
If you find that the HTTPS response from your processor contains cardholder data, you can use a Pre-Configured Proxy to redact or tokenize the sensitive data points using a Response Transform.
It's important to note that for some acquirers, inbound connections are only accepted from whitelisted IP addresses provided by the client. To help with this, here you can find a compiled list of our IP addresses that you can send to your acquirer. In cases of more restrictive integrations, Basis Theory can provide dedicated IPs upon request. If you're interested in this option, please don't hesitate to contact us.
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 Ephemeral Proxy, you can confidently transmit cardholder data to Payment Processors via API requests without ever touching the card details yourself. This approach not only improves security and reduces compliance risks but also provides the flexibility to establish your own relationships with Payment Processors and the latest payment technologies.