Examples

Here you can find some examples of how to use Vaultera PCI services.

Sending a Card to Stripe via Vaultera Detokenization (Drop-Ins)

To securely charge a credit card with Stripe using Vaultera, you will use Vaultera's detokenization process with Drop-In placeholders. The high-level steps are:

Tokenize (store) the credit card with Vaultera – obtain a card_token for the card.
Detokenize (send) the card to Stripe – use Vaultera's Send Card API with Drop-In placeholders to forward the card data to Stripe's API.
(Optional) Authorize (wipe CVV) – after a successful charge or PaymentMethod creation, instruct Vaultera to remove the CVV from storage (per PCI DSS requirements).

Below we detail each step, with examples in cURL and Node.js.

1. Store/Tokenize the Credit Card in Vaultera

First, store the customer's credit card in Vaultera’s PCI vault to get a secure token. You can do this either via Vaultera’s hosted Card Capture IFrame or by making a direct API call. For example, a direct API request to store a card might look like:

POST https://pci.vaultera.co/api/v1/cards?api_key=<VAULTERA_API_KEY>
Content-Type: application/json

{
  "card": {
    "card_number": "4111111111111111",
    "card_type": "visa",
    "cardholder_name": "JOHN DOE",
    "service_code": "123",
    "expiration_month": "12",
    "expiration_year": "2021"
  }
}

This returns a JSON response containing a unique card_token for the stored card. For example, the response includes a token like "card_token": "2f97cef45086488fa823ba3c014a3bc1" (along with masked card details) This card_token will represent the card in all future operations.

Note: Instead of direct API calls, you can also use Vaultera’s front-end IFrame to capture card details securely. In either case, you end up with a card_token that references the stored card.

2. Detokenize and Send Card Data to Stripe (Drop-Ins)

Once you have a card_token, you can instruct Vaultera to detokenize the card and forward the data to Stripe. Vaultera uses Drop-In placeholders to insert sensitive card information into outgoing requests. These placeholders act as markers in your request body that Vaultera will replace with the actual card data during the detokenization process. The supported Drop-Ins include: %CARD_NUMBER% (card PAN), %CARDHOLDER_NAME%, %SERVICE_CODE% (CVV), %EXPIRATION_MM% (2-digit month), %EXPIRATION_YYYY% (4-digit year), %EXPIRATION_YY% (2-digit year), and %CARD_TYPE%.

How it works: You call Vaultera’s Send Card endpoint, specifying the target Stripe API URL and HTTP method, and include a request body with card fields set to the Drop-In placeholders. Vaultera will retrieve the actual card details from its vault and substitute those %PLACEHOLDERS% with the real data, then forward the request to Stripe on your behalf. This way, your system never handles raw card numbers, yet Stripe receives the necessary card info.

Example using cURL

Below is a cURL example that uses Vaultera to create a Stripe PaymentMethod (type: card) using a stored card token:

curl -X POST "https://pci.vaultera.co/api/v1/cards/<CARD_TOKEN>/send?api_key=<VAULTERA_API_KEY>&method=post&url=https%3A%2F%2Fapi.stripe.com%2Fv1%2Fpayment_methods" \
     -H "Content-Type: application/json" \
     -H "Authorization: Basic <BASE64_ENCODED_STRIPE_SECRET:>" \
     -d '{
           "card": {
             "card_number": "%CARD_NUMBER%",
             "cardholder_name": "%CARDHOLDER_NAME%",
             "service_code": "%SERVICE_CODE%",
             "expiration_month": "%EXPIRATION_MM%",
             "expiration_year": "%EXPIRATION_YYYY%"
           }
         }'

Let's break down this request:

Endpoint: We call Vaultera’s POST /api/v1/cards/{card_token}/send endpoint, including our Vaultera api_key in the query params. We also specify method=post and the url of the Stripe API (URL-encoded). In this case, the target is Stripe’s https://api.stripe.com/v1/payment_methods endpoint (encoded as url=https%3A%2F%2Fapi.stripe.com%2Fv1%2Fpayment_methods).
Headers: We set Content-Type: application/json for Vaultera to accept our JSON body. Importantly, we include an Authorization header with Stripe credentials: Basic <encoded_secret_key>. This is the Stripe Secret Key (e.g. sk_live_... or sk_test_...) base64-encoded with an empty password (the usual Stripe Basic Auth format). Vaultera will forward this Authorization header to Stripe unchanged, allowing the request to authenticate with Stripe.
Body: The JSON body contains a "card" object with all the required Stripe card fields, but instead of actual numbers we use the Drop-In placeholders. For example, "card_number": "%CARD_NUMBER%" and "service_code": "%SERVICE_CODE%". When Vaultera receives this, it knows to replace those tokens with the real card number, CVV, etc., from the vault before sending to Stripe. The resulting forwarded request that Stripe sees will have the actual card data (e.g. card[number]=4242424242424242, card[cvc]=123, etc.).

Vaultera will execute this request to Stripe and return Stripe’s response back to you. In this example, Stripe would return the newly created PaymentMethod object if the call is successful.

3. Post-Transaction: Authorize (Remove CVV) and Cleanup

After you successfully send the card to Stripe (e.g. Stripe created a PaymentMethod or processed a charge), it is recommended to call Vaultera’s Authorize Card endpoint to remove the sensitive CVV from storage. By PCI DSS rules, the CVV (service code) should not be stored after authorization. You can do this with:

POST https://pci.vaultera.co/api/v1/cards/<CARD_TOKEN>/auth?api_key=<VAULTERA_API_KEY>

This will return 204 No Content and wipe the service_code for that card token. (The card itself can still be stored for future use, minus the CVV.) If the card is no longer needed at all, you can also delete it from Vaultera using the DELETE /cards/{card_token} endpoint

How to use Vaultera PCI with Channex

To tokenise cards from Channex you need to perform capture requests from secure.channex.io endpoint (if you want to test with Channex staging account it will be secure-staging.channex.io).

There are two Vaultera tokenisation profiles that should be used depending on which Channex endpoint you use. Request template POST https://pci.vaultera.co/api/v1/capture?api_key=<API_KEY>&profile=<PROFILE>&method=get&url<SECURE_CHANNEX_ENDPOINT>

API_KEY - your Vaultera PCI api_key
PROFILE - tokenisation profile name
SECURE_CHANNEX_ENDPOINT - url-encoded secure channex endpoint

All requests should contain an authentication header for Channex. Here are the endpoints you might be interested in. Receive bookings Endpoint: /api/v1/bookings Tokenisation profile: channex Example: POST https://pci.vaultera.co/api/v1/capture?api_key=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&profile=channex&method=get&url=https%3A%2F%2Fsecure.channex.io%2Fapi%2Fv1%2Fbookings Receive specific booking Endpoint: /api/v1/bookings/:id Tokenisation profile: channex_entity Example: POST https://pci.vaultera.co/api/v1/capture?api_key=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&profile=channex_entity&method=get&url=https%3A%2F%2F secure.channex.io %2Fapi%2Fv1%2Fbookings%2Fc3f75a90-41a8-40eb-9f59-55dad5fccf3a Receive booking_revisions Endpoint: /api/v1/booking_revisions Tokenisation profile: channex Example: POST https://pci.vaultera.co/api/v1/capture?api_key=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&profile=channex&method=get&url=https%3A%2F%2Fsecure .channex.io %2Fapi%2Fv1%2Fbooking_revisions Receive booking_revisions feed Endpoint: /api/v1/booking_revisions/feed Tokenisation profile: channex Example: POST https://pci.vaultera.co/api/v1/capture?api_key=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&profile=channex&method=get&url=https%3A%2F%2F secure.channex.io %2Fapi%2Fv1%2Fbooking_revisions%2Ffeed Receive specific booking_revision Endpoint: /api/v1/booking_revisions/:id Tokenisation profile: channex_entity Example: POST https://pci.vaultera.co/api/v1/capture?api_key=aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa&profile=channex_entity&method=get&url=https%3A%2F%2F secure.channex.io %2Fapi%2Fv1%2Fbooking_revisions%2F7b727014-1d86-4419-98b6-2ac915881f45

PreviousFAQ NextWalkthrough

Last updated 7 days ago