PHP SDK

Use the raims/raims-php package to integrate a server application written in PHP with the public API. The SDK organizes resources into services, with typed responses, cursor pagination, and webhook signature verification.

Keep the API key in the integration backend. Do not distribute credentials in code delivered to a browser or in your customers' applications.

Install the package

The SDK requires PHP 8.2 or later on a 64-bit platform, Composer 2, and the curl, json, and hash extensions. From your application directory:

composer require raims/raims-php

The package is available on Packagist. Without a version argument, Composer installs the latest stable version compatible with the project and records the constraint in composer.json. Keep your application's composer.lock to repeat installation of the same version. Check extensions and platform requirements with composer check-platform-reqs after installing. The SDK does not require third-party production libraries.

Configure the client

Obtain a key through API keys and store it in a protected environment variable or your application's secret store. The validated credential determines the company, environment, and permissions in the API. Sandbox and Production use https://api.raims.com.

<?php

require __DIR__ . '/vendor/autoload.php';

use Raims\RaimsClient;

$apiKey = getenv('RAIMS_API_KEY');
if ($apiKey === false || $apiKey === '') {
    throw new RuntimeException('Configure RAIMS_API_KEY.');
}

$raims = new RaimsClient($apiKey);
$customers = $raims->customers->all(['page_size' => 20]);

foreach ($customers as $customer) {
    echo $customer->id, PHP_EOL;
}

Reuse the instance to benefit from HTTP connections. The following snippets assume that the application has configured $raims.

Create a customer and a charge

$customerTaxId is a valid CPF or CNPJ belonging to the customer authorized by your application. $customerIdempotencyKey and $chargeIdempotencyKey are distinct keys, created and persisted before sending the requests. $chargeDueDate is the due date selected and persisted for the order, in Unix seconds UTC.

$customer = $raims->customers->create([
    'tax_id' => $customerTaxId,
], [
    'idempotency_key' => $customerIdempotencyKey,
]);

$charge = $raims->charges->create([
    'customer_id' => $customer->id,
    'amount_cents' => 15000,
    'due_date' => $chargeDueDate,
    'title' => 'Order 1234',
], [
    'idempotency_key' => $chargeIdempotencyKey,
]);

$httpStatus = $charge->getLastResponse()->statusCode;
$requestId = $charge->getLastResponse()->getRequestId();

If the CPF or CNPJ already exists within the same company and environment, the customer is updated and keeps its identifier. 15000 represents BRL 150.00. See the fields and conditions in Create charge. When repeating the same intent after losing a response, keep the key and every parameter, including the due date. An order's external reference does not replace idempotency.

Pagination and pending results

all() fetches one page. Enumerating that page does not send further requests. Use nextPage() and previousPage() to navigate; the SDK preserves filters and returns null when no page exists in the selected direction.

autoPagingIterator() loads subsequent pages during enumeration and can send multiple requests. Leaving the foreach stops further fetches. Copy the returned cursors and keep the filters; do not send after and before together. See Listing and pagination.

An HTTP 202 response preserves its meaning as a pending result. It does not confirm payment or a completed financial result and does not start automatic polling. Retrieve the resource or monitor the appropriate event before confirming the effect in your application.

Idempotency and errors

Pass idempotency_key in request options only for endpoints that accept Idempotency-Key. The SDK does not generate keys or automatically retry POST, PATCH, or DELETE. Read retries are optional; the default is zero.

Handle HTTP failures through ApiErrorException, using getHttpStatus() and getErrorCode(). getRequestId() helps identify the attempt. The text in error.message is a human diagnostic and must not be compared as a control code. Do not log complete responses, credentials, personal documents, or temporary links. See Idempotency and the SDK error guide.

In updates, omitting a field preserves its value. Sending null clears only fields whose contract permits that action. Use (object) [] for an empty object in an input; an empty PHP array represents a list. Check each endpoint's conditions.

Use Sandbox

Use a Sandbox key for simulations in $raims->simulations->charges and $raims->simulations->refunds. A Production key does not become a Sandbox key when these services are used. See the rules and conditions in the Simulations reference.

Requests that ask for email or webhook deliveries can reach external destinations even in Sandbox. Use only destinations authorized for your integration.

Receive webhooks

Read the original body and the headers received by your server:

use Raims\Exception\SignatureVerificationException;
use Raims\Webhook;

$payload = file_get_contents('php://input');
if ($payload === false) {
    throw new RuntimeException('Unable to read the request body.');
}

$headers = [
    'webhook-id' => $_SERVER['HTTP_WEBHOOK_ID'] ?? '',
    'webhook-timestamp' => $_SERVER['HTTP_WEBHOOK_TIMESTAMP'] ?? '',
    'webhook-signature' => $_SERVER['HTTP_WEBHOOK_SIGNATURE'] ?? '',
];

try {
    $event = Webhook::constructEvent($payload, $headers, $webhookSecret);
} catch (SignatureVerificationException $error) {
    http_response_code(400);
    exit;
}

$webhookSecret is the secret_key returned when creating or rotating a webhook, not the API Bearer key. Preserve the original body bytes and do not reserialize the JSON before authentication. A failure raises SignatureVerificationException; do not process the body in that case.

A valid signature does not eliminate duplicates. Check type and environment, deduplicate by the event id, and store the work durably before responding with success. The webhook-id header identifies the delivery and does not replace the event identifier. See Receive events.

Update the SDK

To get the latest stable version, run the command again without a version argument:

composer require raims/raims-php

Composer chooses a constraint based on the available versions and updates composer.json and composer.lock. Check the releases and test the flows used by your integration. The SDK version is independent of the API HTTP version /v1.

Full guides and the service reference are available in the SDK repository.