PHP · Nowgate docs

composer require nowgate/nowgate-php

The SDK needs PHP 8.1 or later with ext-curl and ext-json, and no other package. Its results are arrays, described for PHPStan as array shapes, so your static analysis checks every field you read.

Configure#

$nowgate = new Client(['api_key' => env('NOWGATE_API_KEY'), 'base_url' => $baseUrl, 'transport' => $counted]);

Option	Default	What
`api_key`	(needed)	Your API key. Its environment picks the API.
`base_url`	from the key	Another API, such as a local engine.
`timeout`	`60`	Seconds each attempt may take.
`max_retries`	`2`	How many times a failed attempt is retried.
`transport`	curl	Your own HTTP client: see below.
`app_info`	none	Your application, added to the `User-Agent`: `my-shop/1.2`.

Every method takes a last options array: ['idempotency_key' => ..., 'timeout' => ..., 'max_retries' => ...].

Calls#

$payment = $nowgate->payments->create(
    ['network' => 'tron', 'asset' => 'USDT', 'amount' => '25.00', 'order_id' => '1042'],
    ['idempotency_key' => $orderKey],
);

To read the status, the headers and the request's ID too, make the same call through $nowgate->withResponse():

$again = $nowgate->withResponse()->payments->create(
    ['network' => 'tron', 'asset' => 'USDT', 'amount' => '25.00', 'order_id' => '1042'],
    ['idempotency_key' => $orderKey],
);

Method	Operation
`$nowgate->status->retrieve()`	Service and network status
`$nowgate->assets->list()`	Supported networks and assets
`$nowgate->rates->list()`	List rates
`$nowgate->rates->estimate()`	Estimate a fiat price
`$nowgate->rates->minAmount()`	Get an asset's minimum
`$nowgate->payments->create()`	Create a payment
`$nowgate->payments->retrieve()`	Retrieve a payment
`$nowgate->payments->list()` and `$nowgate->payments->listAll()`	List payments
`$nowgate->paymentLinks->create()`	Create a payment link
`$nowgate->paymentLinks->retrieve()`	Retrieve a payment link
`$nowgate->paymentLinks->update()`	Update a payment link
`$nowgate->paymentLinks->list()` and `$nowgate->paymentLinks->listAll()`	List payment links
`$nowgate->logos->create()`	Upload a logo
`$nowgate->balances->list()`	List balances
`$nowgate->payoutDestinations->create()`	Add a payout destination
`$nowgate->payoutDestinations->retrieve()`	Retrieve a payout destination
`$nowgate->payoutDestinations->disable()`	Disable a payout destination
`$nowgate->payoutDestinations->list()` and `$nowgate->payoutDestinations->listAll()`	List payout destinations
`$nowgate->payouts->create()`	Create a payout
`$nowgate->payouts->retrieve()`	Retrieve a payout
`$nowgate->payouts->cancel()`	Cancel a payout
`$nowgate->payouts->list()` and `$nowgate->payouts->listAll()`	List payouts
`$nowgate->payoutBatches->create()`	Create a batch of payouts
`$nowgate->payoutBatches->retrieve()`	Retrieve a payout batch
`$nowgate->payoutBatches->list()` and `$nowgate->payoutBatches->listAll()`	List payout batches
`$nowgate->refunds->create()`	Refund a payment
`$nowgate->refunds->retrieve()`	Retrieve a refund
`$nowgate->refunds->cancel()`	Cancel a refund
`$nowgate->refunds->list()` and `$nowgate->refunds->listAll()`	List refunds
`$nowgate->forwarding->retrieve()`	Retrieve your forwarding rules
`$nowgate->forwarding->update()`	Set your forwarding rules
`$nowgate->plans->create()`	Create a plan
`$nowgate->plans->retrieve()`	Get a plan
`$nowgate->plans->update()`	Update a plan
`$nowgate->plans->list()` and `$nowgate->plans->listAll()`	List plans
`$nowgate->subscriptions->create()`	Create a subscription
`$nowgate->subscriptions->retrieve()`	Get a subscription
`$nowgate->subscriptions->update()`	Update a subscription
`$nowgate->subscriptions->cancel()`	Cancel a subscription at once
`$nowgate->subscriptions->rotateLink()`	Replace the subscriber's link
`$nowgate->subscriptions->list()` and `$nowgate->subscriptions->listAll()`	List subscriptions
`$nowgate->invoices->retrieve()`	Get an invoice
`$nowgate->invoices->list()` and `$nowgate->invoices->listAll()`	List invoices
`$nowgate->sandbox->simulatePayment()`	Simulate a payer (sandbox)
`$nowgate->sandbox->simulatePayout()`	Fail a payout (sandbox)
`$nowgate->sandbox->activatePayoutDestination()`	Activate a destination now (sandbox)
`$nowgate->sandbox->simulateSubscription()`	Move a subscription's time (sandbox)
`$nowgate->sandbox->simulateInvoice()`	Pay an invoice (sandbox)

Errors#

try {
    $nowgate->payments->create(['network' => 'tron', 'asset' => 'USDT', 'amount' => '25.0000001']);
} catch (InvalidRequestException $e) {
    // $e->errorCode is 'amount_too_precise'; each field's problem has its JSON pointer
    $pointer = $e->errors[0]['pointer'] ?? null;
    check($e->errorCode === 'amount_too_precise', $e->errorCode);
}

The exceptions are Nowgate\Exception\NowgateException, ApiException and its classes by status (AuthenticationException, PermissionException, NotFoundException, ConflictException, InvalidRequestException, RateLimitException, ServerException), ConnectionException when there's no answer, and SignatureVerificationException. The API's code is $e->errorCode, since an exception's own code is a number. A float where an amount goes is an InvalidArgumentException, before anything is sent. See Errors.

Pages#

$all = [];
foreach ($nowgate->payments->listAll() as $payment) {
    $all[] = $payment['id'];
}

listAll is a generator: it fetches nothing until you iterate, and stops when you do.

Amounts#

Amount fields take a decimal string or an int. Amounts::toUnits, Amounts::fromUnits and Amounts::compare convert and compare amounts exactly, as digit strings, without bcmath. See Amounts.

Webhooks#

$payload = (string) file_get_contents('php://input'); // the raw body, exactly as received
$header = $_SERVER['HTTP_NOWGATE_SIGNATURE'] ?? null;
try {
    $event = Webhook::constructEvent($payload, is_string($header) ? $header : null, $secret);
} catch (SignatureVerificationException $e) {
    http_response_code(400);
    return;
}

In Laravel, the raw body is $request->getContent(). See Webhooks.

Your own HTTP client#

A transport implements Nowgate\Transport\Transport: send(Request $request): Response. When there's no answer, it throws a Nowgate\Transport\TransportException, which the client retries.

final class Counted implements Transport
{
    public int $requests = 0;
    private CurlTransport $curl;

    public function __construct()
    {
        $this->curl = new CurlTransport();
    }

    public function send(Request $request): Response
    {
        $this->requests++;
        return $this->curl->send($request); // or any HTTP client: throw a TransportException when there's no answer
    }
}