Skip to main content

​
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

FieldTypeRequiredDescription
tokenstringYesThe token to use
cvc_session_idstringNoCVC session for CVV
proxy_urlstringYesTarget PSP endpoint
request_dataobjectYesRequest body with placeholders
http_headersobjectNoHeaders to include
http_methodstringNoHTTP 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:
PlaceholderDescription
${cardNumber}Full card number
${expirationMonth}2-digit month (01-12)
${expirationYear}Year (2 or 4 digit)
${cvv}Security code
${cvc}Alias for cvv
For Bank Accounts:
PlaceholderDescription
${accountNumber}Account number
${routingNumber}Routing number

​
Examples

​
Stripe

curl -X POST https://pci-vault-hrhwdgc4akhse3bs.eastus-01.azurewebsites.net/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 https://pci-vault-hrhwdgc4akhse3bs.eastus-01.azurewebsites.net/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 https://pci-vault-hrhwdgc4akhse3bs.eastus-01.azurewebsites.net/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

FieldDescription
successWhether proxy succeeded
proxy_response.status_codeHTTP status from PSP
proxy_response.headersResponse headers from PSP
proxy_response.bodyResponse 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"
      }
    }
  }
}
Note: 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