PHPackages                             michaeld555/santander-sdk - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. michaeld555/santander-sdk

ActiveLibrary[API Development](/categories/api)

michaeld555/santander-sdk
=========================

Santander SDK for PHP/Laravel

v1.0.3(2mo ago)08MITPHPPHP ^8.1

Since Feb 18Pushed 2mo agoCompare

[ Source](https://github.com/michaeld555/santander-sdk)[ Packagist](https://packagist.org/packages/michaeld555/santander-sdk)[ RSS](/packages/michaeld555-santander-sdk/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (1)Dependencies (10)Versions (5)Used By (0)

Santander PHP/Laravel SDK
=========================

[](#santander-phplaravel-sdk)

SDK para integracao com APIs do Santander em projetos Laravel e PHP puro.

Versao
------

[](#versao)

`1.0.0`

Sumario
-------

[](#sumario)

- [Escopo](#escopo)
- [Cobertura de Endpoints](#cobertura-de-endpoints)
- [Instalacao](#instalacao)
- [Configuracao](#configuracao)
- [Arquitetura da SDK](#arquitetura-da-sdk)
- [Quickstart Laravel](#quickstart-laravel)
- [Quickstart PHP puro](#quickstart-php-puro)
- [Referencia por Modulo](#referencia-por-modulo)
- [Erros e Tratamento](#erros-e-tratamento)
- [Logs e Observabilidade](#logs-e-observabilidade)
- [Testes](#testes)
- [Notas da versao 1.0.0](#notas-da-versao-110)
- [Documentacao oficial Santander](#documentacao-oficial-santander)
- [Licenca](#licenca)

Escopo
------

[](#escopo)

Esta SDK cobre os fluxos principais das colecoes em `endpoints/`:

- Pagamentos parceiros (`management_payments_partners`)
- Informacoes de contas (`bank_account_information`)
- Comprovantes (`consult_payment_receipts`)
- Pix Automatico (`/api/v1`)
- Autenticacao OAuth2 (`/auth/oauth/v2/token`)

Cobertura de Endpoints
----------------------

[](#cobertura-de-endpoints)

DominioBase endpointAcesso via SDKMetodosAuth`/auth/oauth/v2/token`interno (`SantanderAuth`)renovacao automatica de tokenWorkspaces`/management_payments_partners/v1/workspaces``Santander::workspaces()``createWorkspace`, `listWorkspaces`, `getWorkspace`, `updateWorkspace`, `deleteWorkspace`Pix Payments`/management_payments_partners/v1/workspaces/:workspaceid/pix_payments``Santander::pix()``transferPix`, `createPayment`, `confirmPayment`, `getPayment`, `listPayments`Bank Slip Payments`/management_payments_partners/v1/workspaces/:workspaceid/bank_slip_payments``Santander::bankSlips()``createPayment`, `confirmPayment`, `getPayment`, `listPayments`, `listAvailableBankSlips`Barcode Payments`/management_payments_partners/v1/workspaces/:workspaceid/barcode_payments``Santander::barcodes()``createPayment`, `confirmPayment`, `getPayment`, `listPayments`Vehicle Taxes`/management_payments_partners/v1/workspaces/:workspaceid/vehicle_taxes_payments``Santander::vehicleTaxes()``listAvailableVehicleTaxes`, `createPayment`, `confirmPayment`, `getPayment`, `listPayments`Taxes by Fields`/management_payments_partners/v1/workspaces/:workspaceid/taxes_by_fields_payments``Santander::taxesByFields()``createPayment`, `confirmPayment`, `getPayment`, `listPayments`Contas`/bank_account_information/v1/banks/:bank_tax_id``Santander::accounts()``listAccounts`, `getBalance`, `getStatement`Comprovantes`/consult_payment_receipts/v1/payment_receipts``Santander::receipts()``paymentList`, `paymentListIterByPages`, `createReceipt`, `getReceipt`, `receiptCreationHistory`Pix Automatico - Location`/api/v1/locrec``Santander::pixAutomatic()``createLocation`, `listLocations`, `getLocation`, `unbindLocation`Pix Automatico - Recorrencia`/api/v1/rec``Santander::pixAutomatic()``createRecurrence`, `listRecurrences`, `getRecurrence`, `updateRecurrence`, `cancelRecurrence`Pix Automatico - Solicitacao de confirmacao`/api/v1/solicrec``Santander::pixAutomatic()``createConfirmationRequest`, `getConfirmationRequest`, `reviewConfirmationRequest`Pix Automatico - Cobranca recorrente`/api/v1/cobr``Santander::pixAutomatic()``createRecurringCharge`, `reviewRecurringCharge`, `getRecurringCharge`, `listRecurringCharges`, `requestRecurringChargeRetry`Pix Automatico - Webhooks`/api/v1/webhookrec` e `/api/v1/webhookcobr``Santander::pixAutomatic()``configure*Webhook`, `get*Webhook`, `delete*Webhook`Instalacao
----------

[](#instalacao)

```
composer require michaeld555/santander-sdk
```

Publicar configuracao (Laravel):

```
php artisan vendor:publish --tag=santander-config
```

Configuracao
------------

[](#configuracao)

### Variaveis de ambiente

[](#variaveis-de-ambiente)

```
SANTANDER_CLIENT_ID=seu_client_id
SANTANDER_CLIENT_SECRET=seu_client_secret
SANTANDER_CERT=/caminho/para/cert.pem
SANTANDER_BASE_URL=https://trust-open.api.santander.com.br
SANTANDER_WORKSPACE_ID=
SANTANDER_BANK_TAX_ID=90400888000142
SANTANDER_LOG_LEVEL=ERROR
SANTANDER_TIMEOUT=60
```

### Tabela de configuracao

[](#tabela-de-configuracao)

VariavelObrigatoriaDefaultDescricao`SANTANDER_CLIENT_ID`Sim-Client ID da aplicacao no Santander`SANTANDER_CLIENT_SECRET`Sim-Client secret da aplicacao no Santander`SANTANDER_CERT`Sim na maioria dos cenarios-Certificado client TLS. Pode ser string (caminho) ou array compativel com Guzzle`SANTANDER_BASE_URL`Sim-URL base da API (`trust-open` ou `trust-sandbox`)`SANTANDER_WORKSPACE_ID`NaovazioSe vazio, SDK tenta descobrir o primeiro workspace `PAYMENTS` ativo`SANTANDER_BANK_TAX_ID`Nao`90400888000142`CNPJ base usado pelos endpoints de contas`SANTANDER_LOG_LEVEL`Nao`ERROR``ERROR` ou `ALL``SANTANDER_TIMEOUT`Nao`60`Timeout HTTP em segundos### URLs usuais

[](#urls-usuais)

- Sandbox: `https://trust-sandbox.api.santander.com.br`
- Producao: `https://trust-open.api.santander.com.br`

### Observacoes importantes

[](#observacoes-importantes)

- O placeholder de workspace aceita `:workspaceid` e `:workspace_id` internamente.
- Se `SANTANDER_WORKSPACE_ID` nao for informado e nao existir workspace `PAYMENTS` ativo, a SDK lanca `SantanderClientError`.
- Para endpoints de contas, o `bank_tax_id` pode ser definido na config ou sobrescrito por metodo.

Arquitetura da SDK
------------------

[](#arquitetura-da-sdk)

### Camadas

[](#camadas)

- `SantanderAuth`: gerencia token OAuth2 e renovacao
- `SantanderApiClient`: executa requests HTTP, substitui placeholders e centraliza logs/erros
- Modulos de dominio (`Pix`, `PaymentReceipts`, `BankAccounts`, etc): expoem metodos por endpoint
- `SantanderSdk`: facade de alto nivel para acessar todos os modulos

### Fluxo de request

[](#fluxo-de-request)

1. O modulo chama `SantanderApiClient` com endpoint + payload
2. O client injeta `Authorization` e `X-Application-Key`
3. O client resolve placeholders de URL
4. O Santander responde
5. A SDK retorna array normalizado ou lanca excecao especifica

Quickstart Laravel
------------------

[](#quickstart-laravel)

```
use Santander\SDK\Facades\Santander;
use Santander\SDK\Exceptions\SantanderError;

try {
    $transfer = Santander::pix()->transferPix(
        pixKey: 'destinatario@email.com',
        value: '50.00',
        description: 'Pagamento pedido #123'
    );

    if (! $transfer['success']) {
        throw new \RuntimeException($transfer['error']);
    }

    $paymentId = $transfer['data']['id'] ?? null;
    $status = $paymentId ? Santander::pix()->getPayment($paymentId) : null;

    // use $status conforme sua regra de negocio
} catch (SantanderError $e) {
    // erro de integracao Santander
} catch (\Throwable $e) {
    // erro generico da aplicacao
}
```

Quickstart PHP puro
-------------------

[](#quickstart-php-puro)

```
use Illuminate\Http\Client\Factory;
use Santander\SDK\Auth\SantanderAuth;
use Santander\SDK\Client\SantanderApiClient;
use Santander\SDK\Client\SantanderClientConfiguration;
use Santander\SDK\PaymentReceipts;
use Santander\SDK\Pix;
use Santander\SDK\SantanderSdk;

$http = new Factory();
$config = new SantanderClientConfiguration(
    clientId: 'seu_client_id',
    clientSecret: 'seu_client_secret',
    cert: '/caminho/para/cert.pem',
    baseUrl: 'https://trust-sandbox.api.santander.com.br',
    workspaceId: '',
    logRequestResponseLevel: 'ERROR',
    logger: null,
    timeout: 60,
    bankTaxId: '90400888000142'
);

$auth = SantanderAuth::fromConfig($http, $config);
$client = new SantanderApiClient($config, $auth, $http);

$sdk = new SantanderSdk(
    $client,
    new Pix($client),
    new PaymentReceipts($client)
);

$workspaces = $sdk->workspaces()->listWorkspaces();
```

Referencia por Modulo
---------------------

[](#referencia-por-modulo)

### 1) Pix (`Santander::pix()`)

[](#1-pix-santanderpix)

#### Fluxo simplificado: `transferPix`

[](#fluxo-simplificado-transferpix)

- Entrada:
    - `pixKey`: chave PIX string (CPF/CNPJ/EMAIL/EVP/CELULAR) ou array `beneficiary`
    - `value`: valor numerico
    - `description`: descricao
    - `tags` e `id` opcionais
- Comportamento:
    - cria pagamento
    - aguarda `READY_TO_PAY` quando necessario
    - confirma com status `AUTHORIZED`
    - retorna estrutura padrao:

```
[
  'success' => true|false,
  'request_id' => '...',
  'data' => [...],
  'error' => ''
]
```

#### Fluxo detalhado (baixo nivel)

[](#fluxo-detalhado-baixo-nivel)

```
$created = Santander::pix()->createPayment([
    'dictCode' => 'destinatario@email.com',
    'dictCodeType' => 'EMAIL',
    'paymentValue' => '10.00',
    'remittanceInformation' => 'Teste',
]);

$confirmed = Santander::pix()->confirmPayment($created['id'], [
    'status' => 'AUTHORIZED',
    'paymentValue' => '10.00',
]);

$one = Santander::pix()->getPayment($created['id']);
$list = Santander::pix()->listPayments(['_limit' => 100, '_offset' => 0]);
```

### 2) Comprovantes (`Santander::receipts()`)

[](#2-comprovantes-santanderreceipts)

```
$payments = Santander::receipts()->paymentList([
    'start_date' => '2025-01-01',
    'end_date' => '2025-01-31',
    '_limit' => '100',
]);

$paymentId = $payments[0]['payment']['paymentId'];
$create = Santander::receipts()->createReceipt($paymentId);
$receipt = Santander::receipts()->getReceipt($paymentId, $create['receipt_request_id']);
$history = Santander::receipts()->receiptCreationHistory($paymentId);
```

Paginacao lazy por generator:

```
foreach (Santander::receipts()->paymentListIterByPages([
    'start_date' => '2025-01-01',
    'end_date' => '2025-01-31',
    '_limit' => '50',
]) as $page) {
    // cada pagina contem paymentsReceipts e links
}
```

### 3) Workspaces (`Santander::workspaces()`)

[](#3-workspaces-santanderworkspaces)

```
$created = Santander::workspaces()->createWorkspace([
    'type' => 'PAYMENTS',
    'name' => 'Workspace API',
]);

$list = Santander::workspaces()->listWorkspaces();
$one = Santander::workspaces()->getWorkspace('123456');

$updated = Santander::workspaces()->updateWorkspace('123456', [
    'name' => 'Workspace API v2',
]);

$deleted = Santander::workspaces()->deleteWorkspace('123456');
```

### 4) Contas (`Santander::accounts()`)

[](#4-contas-santanderaccounts)

```
$accounts = Santander::accounts()->listAccounts(['_limit' => 50]);
$balance = Santander::accounts()->getBalance('0000.000011112222');
$statement = Santander::accounts()->getStatement('0000.000011112222', [
    'initialDate' => '2025-01-01',
    'finalDate' => '2025-01-31',
    '_limit' => 50,
    '_offset' => 0,
]);
```

Sobrescrevendo `bank_tax_id` por chamada:

```
$accounts = Santander::accounts()->listAccounts(['_limit' => 50], '12345678000195');
```

### 5) Bank Slips (`Santander::bankSlips()`)

[](#5-bank-slips-santanderbankslips)

```
$created = Santander::bankSlips()->createPayment($payload);
$confirmed = Santander::bankSlips()->confirmPayment($created['id'], ['status' => 'AUTHORIZED']);
$one = Santander::bankSlips()->getPayment($created['id']);
$list = Santander::bankSlips()->listPayments(['_limit' => 50]);
$dda = Santander::bankSlips()->listAvailableBankSlips([
    'payerDocumentNumber' => '12345678000195',
]);
```

### 6) Barcode (`Santander::barcodes()`)

[](#6-barcode-santanderbarcodes)

```
$created = Santander::barcodes()->createPayment($payload);
$confirmed = Santander::barcodes()->confirmPayment($created['id'], ['status' => 'AUTHORIZED']);
$one = Santander::barcodes()->getPayment($created['id']);
$list = Santander::barcodes()->listPayments(['_limit' => 50]);
```

### 7) Vehicle Taxes (`Santander::vehicleTaxes()`)

[](#7-vehicle-taxes-santandervehicletaxes)

```
$debts = Santander::vehicleTaxes()->listAvailableVehicleTaxes([
    'renavam' => '12345678901',
]);

$created = Santander::vehicleTaxes()->createPayment($payload);
$confirmed = Santander::vehicleTaxes()->confirmPayment($created['id'], ['status' => 'AUTHORIZED']);
$one = Santander::vehicleTaxes()->getPayment($created['id']);
$list = Santander::vehicleTaxes()->listPayments(['_limit' => 50]);
```

### 8) Taxes by Fields (`Santander::taxesByFields()`)

[](#8-taxes-by-fields-santandertaxesbyfields)

```
$created = Santander::taxesByFields()->createPayment($payload);
$confirmed = Santander::taxesByFields()->confirmPayment($created['id'], ['status' => 'AUTHORIZED']);
$one = Santander::taxesByFields()->getPayment($created['id']);
$list = Santander::taxesByFields()->listPayments(['_limit' => 50]);
```

### 9) Pix Automatico (`Santander::pixAutomatic()`)

[](#9-pix-automatico-santanderpixautomatic)

#### Location

[](#location)

```
$created = Santander::pixAutomatic()->createLocation($payloadLocation);
$list = Santander::pixAutomatic()->listLocations([
    'inicio' => '2025-03-27T00:00:00Z',
    'fim' => '2025-03-28T23:59:59Z',
]);
$one = Santander::pixAutomatic()->getLocation('1001');
$unlink = Santander::pixAutomatic()->unbindLocation('2001', 'idRec');
```

#### Recorrencia

[](#recorrencia)

```
$created = Santander::pixAutomatic()->createRecurrence($payloadRecurrence);
$list = Santander::pixAutomatic()->listRecurrences([
    'inicio' => '2025-03-26T00:00:00Z',
    'fim' => '2025-03-26T23:59:59Z',
]);
$one = Santander::pixAutomatic()->getRecurrence('RR904008882025021000000000001');
$updated = Santander::pixAutomatic()->updateRecurrence('RR904008882025021000000000001', $payloadUpdate);
$cancel = Santander::pixAutomatic()->cancelRecurrence('RR904008882025021000000000001', $payloadCancel);
```

#### Solicitacao de confirmacao

[](#solicitacao-de-confirmacao)

```
$created = Santander::pixAutomatic()->createConfirmationRequest($payloadSolic);
$one = Santander::pixAutomatic()->getConfirmationRequest('SC904008882025031000000000201');
$review = Santander::pixAutomatic()->reviewConfirmationRequest('SC904008882025031000000000201', $payloadReview);
```

#### Cobranca recorrente

[](#cobranca-recorrente)

```
$created = Santander::pixAutomatic()->createRecurringCharge('txid123', $payloadCharge);
$review = Santander::pixAutomatic()->reviewRecurringCharge('txid123', $payloadReview);
$one = Santander::pixAutomatic()->getRecurringCharge('txid123');
$list = Santander::pixAutomatic()->listRecurringCharges([
    'inicio' => '2025-04-25T00:00:00Z',
    'fim' => '2025-04-26T23:59:59Z',
]);
$retry = Santander::pixAutomatic()->requestRecurringChargeRetry('txid123', '2025-04-30');
```

#### Webhooks

[](#webhooks)

```
$cfgRec = Santander::pixAutomatic()->configureRecurrenceWebhook([
    'webhookUrl' => 'https://sua-api.com/webhook/rec',
]);
$getRec = Santander::pixAutomatic()->getRecurrenceWebhook();
$delRec = Santander::pixAutomatic()->deleteRecurrenceWebhook();

$cfgCobr = Santander::pixAutomatic()->configureRecurringChargeWebhook([
    'webhookUrl' => 'https://sua-api.com/webhook/cobr',
]);
$getCobr = Santander::pixAutomatic()->getRecurringChargeWebhook();
$delCobr = Santander::pixAutomatic()->deleteRecurringChargeWebhook();
```

Erros e Tratamento
------------------

[](#erros-e-tratamento)

### Excecoes da SDK

[](#excecoes-da-sdk)

- `SantanderRequestError`
    - erro HTTP, timeout de conexao ou resposta nao bem sucedida
    - contem `getStatusCode()` e `getContent()`
- `SantanderClientError`
    - erro de configuracao local (workspace ausente, parametros invalidos, etc)
- `SantanderRejectedError`
    - pagamento rejeitado pelo banco durante create/confirm
- `SantanderStatusTimeoutError`
    - timeout ao aguardar mudanca de status no fluxo de polling

### Exemplo de captura

[](#exemplo-de-captura)

```
use Santander\SDK\Exceptions\SantanderRequestError;

try {
    $res = Santander::pix()->createPayment($payload);
} catch (SantanderRequestError $e) {
    logger()->error('Santander request error', [
        'status_code' => $e->getStatusCode(),
        'content' => $e->getContent(),
        'message' => $e->getMessage(),
    ]);
}
```

### Observacao sobre `transferPix`

[](#observacao-sobre-transferpix)

`transferPix` e um helper de alto nivel. Para fluxos de controle total (idempotencia propria, reprocesso customizado, auditoria por etapa), prefira `createPayment` + `confirmPayment` + `getPayment`.

Logs e Observabilidade
----------------------

[](#logs-e-observabilidade)

Configurar `SANTANDER_LOG_LEVEL`:

- `ERROR`: registra apenas falhas
- `ALL`: registra falhas e sucessos

Quando habilitado, o log inclui:

- metodo HTTP
- URL
- request body
- query params
- status code
- response body parseado (quando possivel)
- tipo/mensagem de erro

Testes
------

[](#testes)

Rodar suite atual:

```
vendor/bin/phpunit
```

Notas da versao 1.0.0
---------------------

[](#notas-da-versao-100)

- Adicionados modulos: `WorkspaceManagement`, `BankAccounts`, `BankSlipPayments`, `BarcodePayments`, `VehicleTaxesPayments`, `TaxesByFieldsPayments`, `PixAutomatic`
- `Pix` expandido com `createPayment`, `confirmPayment`, `listPayments`, `getPayment`
- `SantanderApiClient` agora resolve placeholders `:workspaceid` e `:workspace_id`
- Configuracao nova: `bank_tax_id`
- README expandido com referencia completa

Documentacao oficial Santander
------------------------------

[](#documentacao-oficial-santander)

- User guide:
- Transferencias e pagamentos:
- Comprovantes:

Licenca
-------

[](#licenca)

MIT

###  Health Score

37

—

LowBetter than 83% of packages

Maintenance83

Actively maintained with recent releases

Popularity4

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity46

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~2 days

Total

4

Last Release

80d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/468ac93c5d3d72f0574d393b2582b56059fcc1cf48f564e63717a685f19d8b50?d=identicon)[michaeld555](/maintainers/michaeld555)

---

Top Contributors

[![michaeld555](https://avatars.githubusercontent.com/u/97418627?v=4)](https://github.com/michaeld555 "michaeld555 (2 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/michaeld555-santander-sdk/health.svg)

```
[![Health](https://phpackages.com/badges/michaeld555-santander-sdk/health.svg)](https://phpackages.com/packages/michaeld555-santander-sdk)
```

###  Alternatives

[simplestats-io/laravel-client

Client for SimpleStats!

4515.5k](/packages/simplestats-io-laravel-client)[jasara/php-amzn-selling-partner-api

A fluent interface for Amazon's Selling Partner API in PHP

1344.8k1](/packages/jasara-php-amzn-selling-partner-api)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

245.2k](/packages/aedart-athenaeum)[surface/laravel-webfinger

A Laravel package to create an ActivityPub webfinger.

113.8k](/packages/surface-laravel-webfinger)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)