API Integration

The Vault4x REST API provides direct access to tokenization and payment proxy services. Use this integration method when you need server-to-server communication or custom implementations.

PCI DSS Compliance Required

To use the tokenization API directly, your server must be PCI DSS compliant as it will handle raw payment card data. Consider using Form Integration instead to avoid this requirement.

Base URL

All API requests should be made to:

https://api.vault4x.com/v1

Authentication

Include your API key in the x-api-key header for all requests:

curl -H "x-api-key: vk4x_your_api_key_here" \
     https://api.vault4x.com/v1/token

Tokenization API

Create Token

Tokenize payment card information to receive a secure token.

Endpoint: POST /token

Headers:

x-api-key: vk4x_your_api_key_here
Content-Type: application/json

Request Body:

{
  "number": "4242424242424242",
  "holderName": "Jean Dupont",
  "expiryMonth": 10,
  "expiryYear": 2029,
  "cvv": 789
}

Success Response:

{
  "token": "tok.fpXi4kthiCfj9FU0dNJQkrdzo4uq",
  "last4": "4242",
  "brand": "visa",
  "expiryMonth": 10,
  "expiryYear": 2029
}

Example cURL:

curl -X POST https://api.vault4x.com/v1/token \
  -H "x-api-key: vk4x_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "4242424242424242",
    "holderName": "Jean Dupont",
    "expiryMonth": 10,
    "expiryYear": 2029,
    "cvv": 789
  }'

Node.js Example:

const response = await fetch("https://api.vault4x.com/v1/token", {
  method: "POST",
  headers: {
    "x-api-key": process.env.VAULT4X_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    number: "4242424242424242",
    holderName: "Jean Dupont",
    expiryMonth: 10,
    expiryYear: 2029,
    cvv: 789,
  }),
});

const result = await response.json();
console.log("Token:", result.token);

Proxy API

The proxy endpoint acts as a secure proxy between your application and any Payment Service Provider (PSP). It replaces sensitive data placeholders with actual card information before forwarding the request.

Process Payment

Endpoint: POST /proxy

Headers:

x-api-key: vk4x_your_api_key_here
Content-Type: application/json

Request Body:

{
  "method": "post",
  "token": "tok.sMwj7BExEHMD670nCb8I4JggrULn",
  "pspUrl": "https://api.your-psp.com/payments",
  "pspHeaders": {
    "Authorization": "Bearer your-psp-api-key",
    "Content-Type": "application/json"
  },
  "pspBody": "{\"card\":{\"number\":\"[CARD_NUMBER]\",\"exp_month\":\"[CARD_EXPIRY_MONTH]\",\"exp_year\":\"[CARD_EXPIRY_YEAR]\",\"cvc\":\"[CARD_CVV]\"},\"amount\":1000,\"currency\":\"usd\"}"
}

Placeholders:

The following placeholders in pspBody will be replaced with actual card data:

Placeholder	Description
[CARD_NUMBER]	Full card number
[CARD_EXPIRY_MONTH]	Expiry month (2 digits)
[CARD_EXPIRY_YEAR]	Expiry year (4 digits)
[CARD_CVV]	Card verification value

Success Response: The response will be the exact response from your PSP, proxied through Vault4x.

Example cURL:

curl -X POST https://api.vault4x.com/v1/proxy \
  -H "x-api-key: vk4x_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "post",
    "token": "tok.sMwj7BExEHMD670nCb8I4JggrULn",
    "pspUrl": "https://api.stripe.com/v1/payment_intents",
    "pspHeaders": {
      "Authorization": "Bearer sk_test_...",
      "Content-Type": "application/x-www-form-urlencoded"
    },
    "pspBody": "amount=1000&currency=usd&payment_method_data[type]=card&payment_method_data[card][number]=[CARD_NUMBER]&payment_method_data[card][exp_month]=[CARD_EXPIRY_MONTH]&payment_method_data[card][exp_year]=[CARD_EXPIRY_YEAR]&payment_method_data[card][cvc]=[CARD_CVV]"
  }'

Error Handling

Common Error Responses

Invalid API Key (401):

{
  "error": "invalid_api_key",
  "message": "The provided API key is invalid or has been revoked"
}

Validation Error (400):

{
  "error": "validation_error",
  "message": "Invalid card number",
  "field": "number"
}

Rate Limit (429):

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Please try again later",
  "retry_after": 60
}

Server Error (500):

{
  "error": "internal_server_error",
  "message": "An unexpected error occurred"
}

Rate Limits

• Tokenization: 1000 requests per minute
• Proxy: 500 requests per minute

Rate limit headers are included in responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1609459200

Test Cards

Use these test card numbers in development:

Card Number	Brand	Description
4242424242424242	Visa	Success
4000000000000002	Visa	Declined
5555555555554444	Mastercard	Success
2223003122003222	Mastercard	Success
378282246310005	American Express	Success

Testing

Use any future expiry date and any 3-4 digit CVV for test cards.