PHP cURL quickstart

When to use this

Use plain cURL when you need a dependency-free way to call the published sandbox or production endpoint — for example inside a legacy application, a one-off script, or a container image where you want to avoid pulling in an HTTP client library. If you are already on Laravel, prefer the Laravel HTTP client guide instead; it wraps the same underlying cURL calls with a friendlier API.

Authentication

Every technical parameter set we publish includes a bearer API key scoped to a single environment (sandbox or production). Send it as a standard Authorization: Bearer <key> header on every request — there is no separate signing step for simple GET/POST calls, though webhook payloads are signed separately (see the note on webhooks below).

PHP example

$ch = curl_init('https://sandbox.example.com/v1/ping');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 10,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer '.$apiKey,
        'Accept: application/json',
    ],
]);

$response = curl_exec($ch);
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$curlError = curl_error($ch);
curl_close($ch);

if ($curlError !== '') {
    throw new RuntimeException('Connection error: '.$curlError);
}

if ($statusCode >= 400) {
    throw new RuntimeException("Processor returned HTTP {$statusCode}: {$response}");
}

$data = json_decode($response, true, flags: JSON_THROW_ON_ERROR);

Environment variables

Never hard-code the API key or base URL. A typical setup keeps both in .env (outside version control) and reads them through getenv() or your framework's config layer:

PROCESSOR_BASE_URL=https://sandbox.example.com
PROCESSOR_API_KEY=sk_sandbox_xxxxxxxxxxxxxxxx

$baseUrl = getenv('PROCESSOR_BASE_URL');
$apiKey = getenv('PROCESSOR_API_KEY');

Error handling

Distinguish between three failure classes: transport errors (DNS/TLS/timeout — curl_error() is non-empty), HTTP errors (a response was received but the status code indicates a problem — 4xx is usually a request issue, 5xx is usually a processor-side issue worth retrying with backoff), and payload errors (the body did not parse as expected JSON). Handling each distinctly makes downstream logs and alerts far easier to triage than a single generic "request failed" catch-all.

Security notes

• Store secrets outside source control (.env, a secrets manager, or your CI/CD provider's encrypted variables) and rotate keys immediately after go-live from a temporary sandbox key to a dedicated production one.
• Always verify TLS (CURLOPT_SSL_VERIFYPEER should stay at its default of true — do not disable it, even temporarily, to work around a certificate issue).
• Set a sane timeout (CURLOPT_TIMEOUT) so a slow or hung upstream cannot cascade into your own request queue backing up.
• If your webhook consumer receives asynchronous notifications from the processor, verify the signature header before trusting the payload — treat unsigned or mis-signed webhooks as untrusted input.