tamino-gateway / sdk

v1.0.0 2026-11-03 20:26 UTC

Requires

• php: >=8.1
• ext-curl: *
• ext-json: *

Requires (Dev)

• phpunit/phpunit: ^10.5

MIT

• Tamino

• payments
• sdk
• pagamentos
• boleto
• pix
• tamino

Published on Packagist.org on 2026-11-03 20:30 UTC

README

SDK oficial em PHP da API Tamino (/v1). Requer PHP 8.1+ com as extensões curl e json, sem outras dependências.

Instalação

composer require tamino-gateway/sdk

Uso

<?php

use Tamino\Exceptions\GatewayException;
use Tamino\Gateway;

// sk_test_... (sandbox) ou sk_live_... (produção)
$gateway = new Gateway($_ENV['GATEWAY_API_KEY']);
// Outra instalação: new Gateway($apiKey, 'https://api.suaempresa.com');

try {
    // Cobrança Pix
    $charge = $gateway->pix->create([
        'amountInCents' => 5000,
        'payerDocument' => '12345678909',
        'externalId' => 'pedido-123', // reenviar devolve a mesma cobrança
    ]);
    echo $charge['copyPaste'];

    // Consulta
    $gateway->pix->get($charge['id']);
    $gateway->pix->getByExternalId('pedido-123');

    // Saque via Pix
    $payout = $gateway->payouts->create([
        'amountInCents' => 10000,
        'pixKey' => '[e-mail]',
        'pixKeyType' => 'email',
        'externalId' => 'saque-123',
    ]);

    // Saldo e extrato
    $balance = $gateway->balance->get();
    $statement = $gateway->balance->statement(['limit' => 20]);

    // Procurar um identificador nas suas operações
    $found = $gateway->lookup->search('E46026562202611030021hnbemj7ngao');

    // Boleto
    $boleto = $gateway->boletos->create([
        'amountInCents' => 5000,
        'payerDocument' => '12345678909',
        'payerName' => 'Maria da Silva',
    ]);
} catch (GatewayException $e) {
    error_log("{$e->errorCode}: {$e->getMessage()} (correlationId={$e->correlationId})");
}

Idempotência

Toda chamada POST/PATCH sai com um Idempotency-Key gerado na hora. Para repetir uma chamada com segurança depois de um erro de rede, passe a sua própria chave ou use externalId:

$gateway->pix->create($params, idempotencyKey: 'my-own-key-123');

Webhooks

Verifique a assinatura com o corpo cru da requisição:

<?php

use Tamino\Webhooks;

$rawBody = file_get_contents('php://input');

$ok = (new Webhooks())->verifySignature(
    $rawBody,
    $_SERVER['HTTP_X_GATEWAY_TIMESTAMP'],
    $_SERVER['HTTP_X_GATEWAY_SIGNATURE'],
    getenv('GATEWAY_WEBHOOK_SECRET'),
);
if (!$ok) {
    http_response_code(401);
    exit;
}

$event = json_decode($rawBody, true);
// ... processa $event['type'] / $event['data']
http_response_code(200);

Paginação

$cursor = null;
do {
    $page = $gateway->payouts->list(array_filter(['cursor' => $cursor, 'limit' => 50]));
    foreach ($page['data'] as $payout) {
        echo $payout['id'], ' ', $payout['status'], PHP_EOL;
    }
    $cursor = $page['nextCursor'];
} while ($cursor !== null);

Recursos

customers, recipients, payments, pix, boletos, paymentLinks, checkoutSessions, receivables, settlements, payouts, balance, lookup, webhooks.

Desenvolvimento

composer install
composer test

Licença

MIT