PHP SDK

The official RDCPASS SDK for PHP, published on Packagist as rdcpass/rdcpass-php. It signs every request, encrypts and decrypts payloads with AES-256-GCM, presents your mTLS client certificate, adds idempotency keys, retries transient failures and verifies webhooks — the complete security stack described in Authentication, handled for you.

PackagistPHP 8.1+Source code ↗Changelog ↗

Installation

Add rdcpass/rdcpass-php to your project:

composer require rdcpass/rdcpass-php

Requirements

PHP 8.1+ or later.
Outbound HTTPS (TLS 1.2 or later) to gateway.staging.rdcpass.cd for the staging environment and api.rdcpass.cd for production. In production, calls must come from an IP address on your application’s allowlist.
An RDCPASS application with API credentials, created in the console — see Sandbox.

Configuration

Create one client and reuse it across your application: it is safe for concurrent use and keeps connections open between calls. The environment selects the base URL; keys and certificates issued for one environment are rejected by the other.

Environment	RDCPASS_ENVIRONMENT	Base URL
Staging environment	`sandbox`	`https://gateway.staging.rdcpass.cd`
Production	`production`	`https://api.rdcpass.cd`

Configure a client for the staging environment explicitly:

rdcpass.php
<?php
require __DIR__ . '/vendor/autoload.php';

use RdcPass\RdcPass;

// Staging environment: https://gateway.staging.rdcpass.cd
$rdcpass = new RdcPass([
    'environment' => 'sandbox',
    'key_id' => 'key_test_3c7e1a9f42',
    'key_secret' => getenv('RDCPASS_KEY_SECRET'),
    'encryption_key' => getenv('RDCPASS_ENCRYPTION_KEY'),
]);

Credentials

Credential	Environment variable	Description
Key ID	`RDCPASS_KEY_ID`	Public identifier of your HMAC key, sent with every request (`key_test_…` in staging, `key_live_…` in production).
Key secret	`RDCPASS_KEY_SECRET`	HMAC-SHA256 signing secret. Never sent over the network.
Payload Encryption Key	`RDCPASS_ENCRYPTION_KEY`	AES-256-GCM key used to encrypt requests and decrypt responses, and to verify webhook signatures.
Environment	`RDCPASS_ENVIRONMENT`	`sandbox` or `production`. Defaults to `sandbox`.
mTLS client certificate and key	—	Issued by RDCPASS for your application; required in production. Must belong to the same application as the key ID. Loaded from files in the client configuration.

Production and environment variables

When no credentials are passed, the client reads the four environment variables above. In production, add your mTLS client certificate and private key:

rdcpass.php
<?php
use RdcPass\RdcPass;

// Options left out are read from RDCPASS_KEY_ID, RDCPASS_KEY_SECRET,
// RDCPASS_ENCRYPTION_KEY and RDCPASS_ENVIRONMENT.
// Production (https://api.rdcpass.cd) also requires your mTLS client certificate.
$rdcpass = new RdcPass([
    'client_cert' => '/etc/rdcpass/client.crt',
    'client_key' => '/etc/rdcpass/client.key',
]);

Keep secrets out of source code

Load the key secret, the Payload Encryption Key and the certificate’s private key from environment variables or a secrets manager. Never commit them, and never ship them in a mobile or browser application — the SDK is for server-side use.

Your first request

Validate a customer by RDCPASS ID with KYC Validation. The SDK encrypts and signs the request, decrypts the response and returns a typed kyc_validation object:

validate-identity.php
<?php
require __DIR__ . '/vendor/autoload.php';

use RdcPass\RdcPass;

$rdcpass = new RdcPass();

$validation = $rdcpass->kyc->validations->create([
    'reference' => 'cust-0001',
    'identifier' => ['type' => 'rdcpass_id', 'value' => 'COD-2103-0214-4937'],
    'match' => ['full_name' => 'Kabeya Mwamba Tshisekedi', 'date_of_birth' => '1988-04-12'],
    'purpose' => 'customer_onboarding',
    'scopes' => ['kyc.documents.primary', 'kyc.phone_numbers'],
]);

echo $validation->result, PHP_EOL;                // verified
echo $validation->kyc->basic->full_name, PHP_EOL; // Kabeya Mwamba Tshisekedi
print_r($validation->scopes_withheld);            // []

Decrypted response
{
  "id": "kyc_8d2f6a1c93",
  "object": "kyc_validation",
  "livemode": true,
  "reference": "cust-0001",
  "status": "completed",
  "result": "verified",
  "certified_account": true,
  "identifier": {
    "type": "rdcpass_id",
    "value": "COD-2103-0214-4937"
  },
  "match": {
    "full_name": "match",
    "date_of_birth": "match",
    "age": "not_provided",
    "score": 0.98
  },
  "account": {
    "rdcpass_id": "COD-2103-0214-4937",
    "status": "active",
    "certified": true,
    "created_at": "2025-03-14T09:22:41Z",
    "level_of_assurance": "LOA3"
  },
  "kyc": {
    "basic": {
      "full_name": "Kabeya Mwamba Tshisekedi",
      "first_name": "Kabeya",
      "last_name": "Tshisekedi",
      "date_of_birth": "1988-04-12",
      "age": 38,
      "gender": "male",
      "nationality": "COD"
    },
    "documents": {
      "primary": {
        "type": "passport",
        "number": "OB1234567",
        "issued_at": "2022-06-01",
        "expires_at": "2027-05-31",
        "issuing_authority": "Direction Générale de Migration",
        "status": "valid",
        "image": {
          "content_type": "image/jpeg",
          "url": "https://files.rdcpass.cd/d/9f2c41e8b7a3?sig=Qm9fX2t5Y19zaWc&exp=1790418002",
          "expires_at": "2026-09-26T10:20:02Z"
        }
      }
    },
    "phone_numbers": [
      {
        "number": "+243812345678",
        "operator": "Vodacom",
        "is_primary": true,
        "verified": true
      },
      {
        "number": "+243991234567",
        "operator": "Airtel",
        "is_primary": false,
        "verified": true
      }
    ]
  },
  "scopes_applied": [
    "kyc.basic",
    "kyc.documents.primary",
    "kyc.phone_numbers"
  ],
  "scopes_withheld": [],
  "purpose": "customer_onboarding",
  "created_at": "2026-09-26T10:15:02Z"
}

Every field is documented in KYC Validation.

Calling every service

Every service is exposed as a resource on the client, named after its endpoint. Parameters and responses use the same names and shapes as the API reference.

KYC Validation

Look up an identity by RDCPASS ID, passport, CENI voter card, driving licence or national ID. The result is verified, not_found or not_certified. Reference →

$validation = $rdcpass->kyc->validations->create([
    'identifier' => ['type' => 'passport', 'value' => 'OB1234567'],
    'purpose' => 'customer_onboarding',
    'scopes' => [], // basic KYC only
]);
echo $validation->result; // verified | not_found | not_certified

Face Recognition

Compare a photo — sent as base64 data or a url — with the enrolled face of an identity. reason is required; the result is match or no_match. Reference →

$recognition = $rdcpass->face->recognitions->create([
    'image' => ['data' => base64_encode(file_get_contents('selfie.jpg'))],
    'identifier' => ['type' => 'rdcpass_id', 'value' => 'COD-2103-0214-4937'],
    'reason' => 'Current account opening at Gombe branch, Kinshasa',
    'purpose' => 'customer_onboarding',
]);
echo $recognition->result; // match | no_match

Age Verification

Check whether a person is over a threshold without receiving their date of birth; read over_threshold. Reference →

$verification = $rdcpass->age->verifications->create([
    'identifier' => ['type' => 'rdcpass_id', 'value' => 'COD-2103-0214-4937'],
    'threshold' => 18,
    'purpose' => 'age_gating',
]);
var_dump($verification->over_threshold); // bool(true)

KYB Verification

Verify a business by rccm, id_nat or nif, and receive its officers and beneficial owners if your application is granted those scopes. Reference →

$business = $rdcpass->kyb->verifications->create([
    'identifier' => ['type' => 'rccm', 'value' => 'CD/KIN/RCCM/23-B-01234'],
    'match' => ['business_name' => 'Congo Digital Solutions SARL'],
    'purpose' => 'customer_onboarding',
    'scopes' => ['kyb.officers', 'kyb.beneficial_owners'],
]);
echo $business->result;

AML/CTF Screening

Screen a subject against the requested checks; enable monitoring to be notified of new hits. Read risk_level. Reference →

$screening = $rdcpass->aml->screenings->create([
    'subject' => ['identifier' => ['type' => 'rdcpass_id', 'value' => 'COD-1907-5521-0386']],
    'checks' => ['sanctions', 'pep', 'adverse_media', 'watchlists', 'high_risk_jurisdictions'],
    'monitoring' => true,
    'purpose' => 'regulatory_compliance',
]);
echo $screening->risk_level; // low | medium | high

Credit Scoring

Requires the customer’s consent in the RDCPASS app (consent.method: rdcpass_app). Returns a score and a band. Reference →

$credit = $rdcpass->credit->scores->create([
    'identifier' => ['type' => 'rdcpass_id', 'value' => 'COD-2103-0214-4937'],
    'consent' => ['method' => 'rdcpass_app', 'consent_id' => 'cns_5e8a2d71c4'],
    'purpose' => 'credit_assessment',
]);
echo $credit->score, ' ', $credit->band;

Fraud Reporting

Report a confirmed or suspected fraud, such as identity_usurpation, against a subject, with a description. Reference →

$report = $rdcpass->fraud->reports->create([
    'type' => 'identity_usurpation',
    'subject' => ['identifier' => ['type' => 'rdcpass_id', 'value' => 'COD-2103-0214-4937']],
    'description' => 'Account opened with a stolen passport at an agent in Lubumbashi.',
]);
echo $report->id, ' ', $report->status;

Login with RDCPASS

The login helper builds the /v1/oidc/authorize URL with state and a PKCE code_challenge (S256), exchanges the authorization code at /v1/oidc/token with the matching code_verifier, and calls /v1/oidc/userinfo. See Login with RDCPASS.

login.php
<?php
// 1. Build the authorize URL. The SDK generates state and the PKCE
//    code_verifier / code_challenge (S256) for you.
$auth = $rdcpass->login->createAuthorizationUrl([
    'client_id' => 'app_8f2a1c0e9b',
    'redirect_uri' => 'https://yourapp.example.com/callback',
    'scopes' => ['openid', 'profile', 'rdcpass:kyc.phone_numbers'],
]);
$_SESSION['rdcpass_state'] = $auth->state;
$_SESSION['rdcpass_verifier'] = $auth->codeVerifier;
header('Location: ' . $auth->url);

// 2. On your callback, check state and exchange the code.
if (!hash_equals($_SESSION['rdcpass_state'], $_GET['state'] ?? '')) {
    throw new RuntimeException('state mismatch');
}
$tokens = $rdcpass->login->exchangeCode([
    'client_id' => 'app_8f2a1c0e9b',
    'code' => $_GET['code'],
    'code_verifier' => $_SESSION['rdcpass_verifier'],
    'redirect_uri' => 'https://yourapp.example.com/callback',
]);
$user = $rdcpass->login->userInfo($tokens->access_token);

Batches & async

Every service accepts batches at /batches: up to 50 items synchronously, or up to 10,000 asynchronously. With the async option the SDK sends Prefer: respond-async and returns a 202 job or batch object immediately.

Wait — the wait helper polls /v1/batches/{id} (or /v1/jobs/{id} for a single async call) with backoff until the status is final, or until your timeout elapses.
Iterate — the results helper pages through /v1/batches/{id}/results and follows next_cursor for you.
Or subscribe — instead of polling, handle the batch.completed and batch.completed_with_errors webhooks.

refresh-kyc.php
<?php
// Submit up to 10,000 items asynchronously (Prefer: respond-async).
$batch = $rdcpass->kyc->validations->batches->create([
    'purpose' => 'customer_onboarding',
    'items' => [
        ['reference' => 'cust-0001', 'identifier' => ['type' => 'rdcpass_id', 'value' => 'COD-2103-0214-4937']],
        ['reference' => 'cust-0002', 'identifier' => ['type' => 'ceni', 'value' => '1234567890123']],
    ],
], ['respond_async' => true]);

// Poll GET /v1/batches/{id} until the batch reaches a final status.
$done = $rdcpass->batches->wait($batch->id, ['poll_interval' => 5, 'timeout' => 1800]);
echo $done->status, ' ', $done->succeeded_items, ' ', $done->failed_items, PHP_EOL;

// Iterate every result; autoPaging() follows next_cursor page by page.
foreach ($rdcpass->batches->results($batch->id, ['limit' => 500])->autoPaging() as $item) {
    echo $item->reference, ' ', $item->status, PHP_EOL;
}

Batch quota is separate from single-call quota, and batch items are billed at the discounted batch rate — see Rate limits and Billing.

Webhooks

The webhook helper checks X-RDCPASS-Webhook-Signature — HMAC-SHA256 of {timestamp}.{rawBody} with your Payload Encryption Key — using a constant-time comparison, rejects deliveries whose X-RDCPASS-Webhook-Timestamp is more than 5 minutes from your clock (configurable), and parses the envelope { id, object: "event", type, livemode, created_at, data: { object, previous_attributes } } into a typed event.

webhook.php
<?php
use RdcPass\Exception\SignatureVerificationException;

// Use the raw body: the signature covers "{timestamp}.{rawBody}".
$payload = file_get_contents('php://input');

try {
    $event = $rdcpass->webhooks->constructEvent($payload, getallheaders());
} catch (SignatureVerificationException $e) {
    http_response_code(400);
    exit('Invalid signature');
}

switch ($event->type) {
    case 'kyc_validation.completed':
        error_log($event->data->object->status);
        break;
    case 'batch.completed':
    case 'batch.completed_with_errors':
        error_log($event->data->object->id . ' ' . $event->data->object->failed_items);
        break;
}
http_response_code(200);

Pass the raw request body, exactly as received — a body parsed and re-serialized by your framework will not match the signature. Respond with a 2xx within 5 seconds and deduplicate on the event id, which is also sent as X-RDCPASS-Webhook-Id. See Webhooks.

Errors

Every API error — { error, message } in the response body — is raised as RdcPass\Exception\RdcPassException, which carries $e->errorCode, $e->status, $e->getMessage(), $e->requestId. Network failures and timeouts that exhaust their retries raise a separate connection error. Quote the request ID when you contact RDCPASS support.

Code	HTTP	What to do
`invalid_identifier`	400	The identifier is malformed for its type. Fix the input; do not retry.
`insufficient_balance`	402	Your prepaid balance is too low. Top up in the console.
`scope_not_granted`	403	A requested scope is not granted to your application. Remove it or request it in the console.
`purpose_not_approved`	403	The purpose is not approved for your application.
`rate_limited`	429	Too many requests per second. Retried automatically after `Retry-After`.
`batch_quota_exceeded`	429	Your batch quota is used up. Separate from single-call quota.

use RdcPass\Exception\RdcPassException;

try {
    $rdcpass->kyc->validations->create([
        'identifier' => ['type' => 'rdcpass_id', 'value' => 'COD-2103-0214-4937'],
        'purpose' => 'customer_onboarding',
        'scopes' => ['kyc.biometrics.iris'],
    ]);
} catch (RdcPassException $e) {
    error_log("{$e->status} {$e->errorCode} {$e->getMessage()} {$e->requestId}");
    if ($e->errorCode === 'scope_not_granted') {
        // 403: request the scope for your application in the console
    }
}

The full list is in Errors.

Retries & idempotency

Automatic idempotency keys. Every POST is sent with a generated Idempotency-Key, reused on each retry of that request, so a retried call is never processed or billed twice.
What is retried. 429 responses, 5xx responses, connection failures and timeouts. Other 4xx errors are raised immediately.
Backoff. Exponential backoff with jitter, starting at 0.5 seconds and capped at 8 seconds; Retry-After is honoured when present. Up to 3 retries by default.
Configurable. Change the number of retries per client or per request, and pass your own idempotency key to keep retries safe across process restarts.

$rdcpass = new RdcPass(['max_retries' => 5]); // default 3; set 0 to disable

// Every POST gets an Idempotency-Key automatically. Pass your own to make
// retries safe across process restarts:
$rdcpass->fraud->reports->create([
    'type' => 'identity_usurpation',
    'subject' => ['identifier' => ['type' => 'rdcpass_id', 'value' => 'COD-2103-0214-4937']],
    'description' => 'Account opened with a stolen passport.',
], [
    'idempotency_key' => 'fraud-case-INC-2026-88213',
    'max_retries' => 1,
]);

Timeouts & logging

Each attempt times out after 30 seconds by default; set a different timeout per client or per request. Logs are written through your language’s standard logging interface. They include method, path, status, duration, retry attempts and request ID — never decrypted payloads, secrets or personal data.

use Monolog\Handler\StreamHandler;
use Monolog\Level;
use Monolog\Logger;

$rdcpass = new RdcPass([
    'timeout' => 20, // seconds per attempt (default 30)
    'logger' => new Logger('rdcpass', [new StreamHandler('php://stderr', Level::Debug)]), // any PSR-3 logger
]);

// Override per request.
$rdcpass->aml->screenings->create([
    'subject' => ['identifier' => ['type' => 'rdcpass_id', 'value' => 'COD-1907-5521-0386']],
    'purpose' => 'regulatory_compliance',
], ['timeout' => 60]);

Upgrading & versioning

rdcpass/rdcpass-php follows semantic versioning: only major versions contain breaking changes.
Each major version receives security and bug fixes for 24 months after the next major version is released.
Every release, with upgrade notes for each major version, is listed in the Changelog.
New API fields and events arrive in minor releases, so keep the SDK up to date to use them.

Integrating without an SDK? See Authentication to sign, encrypt and send requests yourself.