JSON Proxy Requests
Forward JSON requests to payment processors.Basic Request
POST /proxy/transaction
Content-Type: application/json
{
"token": "tok_a1b2c3d4e5f6",
"cvc_session_id": "550e8400-e29b-41d4-a716-446655440000",
"proxy_url": "https://api.psp.com/v1/charges",
"request_data": {
"amount": 1000,
"currency": "usd",
"card": {
"number": "${cardNumber}",
"exp_month": "${expirationMonth}",
"exp_year": "${expirationYear}",
"cvc": "${cvv}"
}
},
"http_headers": {
"Authorization": "Bearer sk_live_xxx"
}
}
Request Fields
| Field | Type | Required | Description |
|---|---|---|---|
token | string | Yes | The token to use |
cvc_session_id | string | No | CVC session for CVV |
proxy_url | string | Yes | Target PSP endpoint |
request_data | object | Yes | Request body with placeholders |
http_headers | object | No | Headers to include |
http_method | string | No | HTTP method (default: POST) |
Placeholders
Placeholders are replaced with actual card data:{
"card_number": "${cardNumber}", // → "4111111111111111"
"exp_month": "${expirationMonth}", // → "12"
"exp_year": "${expirationYear}", // → "2025"
"cvv": "${cvv}" // → "123"
}
Available Placeholders
For Cards:| Placeholder | Description |
|---|---|
${cardNumber} | Full card number |
${expirationMonth} | 2-digit month (01-12) |
${expirationYear} | Year (2 or 4 digit) |
${cvv} | Security code |
${cvc} | Alias for cvv |
| Placeholder | Description |
|---|---|
${accountNumber} | Account number |
${routingNumber} | Routing number |
Examples
Stripe
curl -X POST $YOUR_VAULT_URL/proxy/transaction \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
-d '{
"token": "tok_a1b2c3d4e5f6",
"cvc_session_id": "session_xyz",
"proxy_url": "https://api.stripe.com/v1/payment_methods",
"request_data": {
"type": "card",
"card": {
"number": "${cardNumber}",
"exp_month": "${expirationMonth}",
"exp_year": "${expirationYear}",
"cvc": "${cvv}"
}
},
"http_headers": {
"Authorization": "Bearer sk_live_xxx",
"Content-Type": "application/x-www-form-urlencoded"
}
}'
Adyen
curl -X POST $YOUR_VAULT_URL/proxy/transaction \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
-d '{
"token": "tok_a1b2c3d4e5f6",
"cvc_session_id": "session_xyz",
"proxy_url": "https://checkout-test.adyen.com/v69/payments",
"request_data": {
"amount": {
"currency": "USD",
"value": 1000
},
"reference": "order_123",
"paymentMethod": {
"type": "scheme",
"number": "${cardNumber}",
"expiryMonth": "${expirationMonth}",
"expiryYear": "${expirationYear}",
"cvc": "${cvv}"
},
"merchantAccount": "YourMerchantAccount"
},
"http_headers": {
"X-API-Key": "your_adyen_api_key"
}
}'
Braintree
curl -X POST $YOUR_VAULT_URL/proxy/transaction \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
-d '{
"token": "tok_a1b2c3d4e5f6",
"cvc_session_id": "session_xyz",
"proxy_url": "https://api.braintreegateway.com/merchants/xxx/transactions",
"request_data": {
"transaction": {
"type": "sale",
"amount": "10.00",
"credit_card": {
"number": "${cardNumber}",
"expiration_month": "${expirationMonth}",
"expiration_year": "${expirationYear}",
"cvv": "${cvv}"
}
}
},
"http_headers": {
"Authorization": "Basic xxx",
"X-ApiVersion": "6"
}
}'
Response
The proxy returns the PSP’s response:{
"success": true,
"proxy_response": {
"status_code": 200,
"headers": {
"content-type": "application/json",
"x-request-id": "req_abc123"
},
"body": {
"id": "pm_1234567890",
"object": "payment_method",
"created": 1640000000,
"type": "card",
"card": {
"brand": "visa",
"last4": "1111"
}
}
}
}
Response Fields
| Field | Description |
|---|---|
success | Whether proxy succeeded |
proxy_response.status_code | HTTP status from PSP |
proxy_response.headers | Response headers from PSP |
proxy_response.body | Response body from PSP |
Error Handling
PSP Returns Error
{
"success": true,
"proxy_response": {
"status_code": 402,
"body": {
"error": {
"code": "card_declined",
"message": "Your card was declined"
}
}
}
}
success: true means the proxy worked. Check status_code for PSP errors.
Proxy Error
{
"success": false,
"message": "Failed to proxy request",
"error": {
"code": "CONNECTION_FAILED",
"details": "Could not connect to target URL"
}
}
Best Practices
1. Always Include CVC Session
Most PSPs require CVV for card-not-present transactions:{
"token": "tok_xxx",
"cvc_session_id": "session_xxx" // Don't forget this!
}
2. Set Appropriate Headers
Match the PSP’s expected format:{
"http_headers": {
"Content-Type": "application/json", // or as required by PSP
"Authorization": "Bearer xxx"
}
}
3. Handle PSP Errors
const response = await fetch('/proxy/transaction', { ... });
const data = await response.json();
if (!data.success) {
// Proxy failed
console.error('Proxy error:', data.message);
} else if (data.proxy_response.status_code >= 400) {
// PSP returned an error
console.error('PSP error:', data.proxy_response.body);
} else {
// Success!
console.log('Payment successful:', data.proxy_response.body);
}
Next Steps
- XML Requests - SOAP/XML proxying
- Form-Encoded Requests - Form data proxying
- CVC Sessions - CVV handling