Download the PHP package payintohq/payinto-php-sdk without Composer

Payinto PHP SDK

PHP 8.1+ SDK for the Payinto Business API and Checkout API v1.

Installation

The SDK uses https://api.payinto.co for both production and sandbox credentials. Select the environment with the credential you provide; no base URL setting is required.

Secret keys (sk_) belong only on your server. Public keys (pk_) are suitable for Checkout initialization flows. Amounts use the lowest currency unit: NGN amounts are kobo.

Laravel

Laravel applications receive the service provider and facade through Composer package auto-discovery. Publish the package configuration with:

Define both live and test credentials in your .env file, then select the active credential pair with PAYINTO_ENV:

Use PAYINTO_ENV=test when testing. The API host remains https://api.payinto.co; the selected credential and webhook-secret pair changes.

PAYINTO_WEBHOOK_TOLERANCE controls the accepted timestamp window in seconds. The default is five minutes. Set it to 0 to disable timestamp checking while retaining HMAC verification.

Inject Payinto\Client into a class or use the Payinto facade:

Responses and errors

Every successful call returns ApiResponse:

Non-2xx responses throw AuthenticationException, ValidationException, RateLimitException, or ApiException; network failures throw TransportException. Each exposes statusCode, responseData, responseHeaders, method, and uri.

Validation error bags returned by the API are preserved in ValidationException::$responseData['errors']:

If an API error envelope is returned with a successful HTTP status instead of a non-2xx status, the SDK returns it as an ApiResponse; inspect $response->status() and $response->raw() in that case.

Business API

All Business API calls use the configured secret key.

Flexible endpoint payloads are passed as associative arrays. Query parameters are passed as the final array argument where supported.

Checkout API

This PHP SDK provides server-side access to the Payinto Checkout API. For the browser-based popup checkout experience, use the official @payinto/checkout-sdk npm package instead. The popup SDK is responsible for opening and managing the customer-facing checkout flow, while this package is intended for backend initialization, reconciliation, payment status checks, and related server-side operations.

Initialize Checkout

The returned checkout token is consumed by the browser popup integration. Use the official @payinto/checkout-sdk package for retrieving the checkout session, submitting payment methods, and logging customer-facing checkout activity.

Checkout Transaction Status Query (TSQ)

Checkout TSQ returns data.reference, nullable data.merchant_reference, payment_status, currency, the amount breakdown, nullable paid_at, and nullable transaction_id. The envelope status is success; the payment state is successful.

For account transactions, use $payinto->transactions->status($reference) and inspect data.status. That response also includes nullable data.merchant_reference, but currently reads it only from transaction metadata. A transaction webhook can therefore contain a reference resolved from its linked source while TSQ returns null. Checkout TSQ reads the payment inflow field with a fallback to cached checkout data.

Webhook events

All events use the envelope fields event, id, created_at, api_version, and data. All four expose nullable data.merchant_reference. Transaction events resolve it from their linked payment inflow, transfer, or VAS record, then source metadata and transaction metadata, including legacy checkout metadata. reference remains the Payinto reference.

A checkout bank transfer can emit checkout success, virtual-account deposit, and transaction credit events for one payment. Fulfill only from checkout.payment.succeeded, with an idempotent payment key. Webhook retries and replays are possible. Checkout pending, failed, expired, and refunded events are not currently emitted. Future payment methods such as USSD must connect their verified confirmations to the unified event service.

The checkout event data has this shape (illustrative identifiers):

For cards, payment_method is card. All amounts use minor currency units. Match the customer's expected payment against amount; base_amount is the order amount and settled_amount is after fees. customer and metadata preserve checkout input or are null. The browser SDK's checkout.succeeded callback is a UI notification; keep fulfillment on your server using a verified webhook or authenticated checkout TSQ.

Webhook verification

Verify the webhook before processing its JSON payload. Always pass the exact raw request body because Payinto signs the original bytes before JSON decoding or re-encoding.

Laravel

Non-Laravel PHP

For a plain PHP application, read the raw request body and the X-Payinto-Signature HTTP header before decoding the JSON payload:

The package automatically handles the X-Payinto-Signature format: t={timestamp},v1={signature}. The verifier computes an HMAC-SHA256 signature over {timestamp}.{raw_request_body} and compares it using a timing-safe comparison. Webhook secrets must remain server-side and must never be exposed to browser code.

Set webhookTimestampTolerance to the number of accepted seconds. For example, 300 allows a five-minute clock difference, while 0 disables timestamp checking but keeps HMAC verification enabled.

Custom requests

Future endpoints can be accessed through the raw client while retaining the same response and exception behavior:

Testing

Use a mocked Guzzle client in application tests; never commit API keys. See tests/Unit/ClientTest.php for request and authentication examples.

Transfers to Payinto Tags

Resolve the tag, confirm the returned recipient, then initiate a transfer using the resolved bank details. The transfers module must be enabled for your API key. Amounts use minor units. Use the same optional debit_account_id throughout. Sandbox keys resolve only sandbox recipient records and simulate bank resolution.