PHPackages                             qrcommunication/viva-isv-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. [Payment Processing](/categories/payments)
4. /
5. qrcommunication/viva-isv-sdk

ActiveLibrary[Payment Processing](/categories/payments)

qrcommunication/viva-isv-sdk
============================

PHP SDK for Viva Wallet ISV Partner API — connected accounts, ISV orders, composite auth, Cloud Terminal

v1.4.0(1mo ago)038↓100%MITPHPPHP ^8.2CI passing

Since Mar 18Pushed 1mo agoCompare

[ Source](https://github.com/QrCommunication/sdk-php-viva-isv)[ Packagist](https://packagist.org/packages/qrcommunication/viva-isv-sdk)[ RSS](/packages/qrcommunication-viva-isv-sdk/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (9)Dependencies (3)Versions (10)Used By (0)

SDK PHP Viva Wallet ISV
=======================

[](#sdk-php-viva-wallet-isv)

[![Version 1.3.5](https://camo.githubusercontent.com/a9ef15743ddac7e1a307b91152b9ff217d8a982ec7a7e2b4ee71f7892c6d9dd8/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f76657273696f6e2d312e332e352d626c75652e737667)](https://github.com/qrcommunication/sdk-php-viva-isv/releases)[![PHP 8.2+](https://camo.githubusercontent.com/c2588b5670f2c910b8cc849ace22a22efda8956b7c2f797d11d2096bbfc7b1f5/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e322532422d3737374242342e737667)](https://php.net)[![License: MIT](https://camo.githubusercontent.com/784362b26e4b3546254f1893e778ba64616e362bd6ac791991d2c9e880a3a64e/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d677265656e2e737667)](LICENSE)[![Packagist](https://camo.githubusercontent.com/954d5fb44453e2d2e154bef8ae5af8061329dc37ee4555aeb90a8eb0d6751d3c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5061636b61676973742d7172636f6d6d756e69636174696f6e253246766976612d2d6973762d2d73646b2d6f72616e67652e737667)](https://packagist.org/packages/qrcommunication/viva-isv-sdk)

SDK PHP complet pour l'API Viva Wallet ISV Partner. 10 ressources couvrant : comptes connectes, comptes ISV, ordres ISV avec commission, transactions (capture, recurrent, annulation), terminaux Cloud POS, transferts marketplace, ordres marketplace, Native Checkout ISV, webhooks ISV (CRUD) et parsing (21 evenements).

> **Ce SDK couvre les operations ISV (comptes connectes, composite auth, commission).** Pour les operations marchands standard, voir [`sdk-php-viva-merchant`](https://github.com/qrcommunication/sdk-php-viva-merchant).

---

Table des matieres
------------------

[](#table-des-matieres)

- [Installation](#installation)
- [Quick Start](#quick-start)
- [Reference des ressources](#reference-des-ressources)
    - [1. ConnectedAccounts — comptes connectes](#1-connectedaccounts--comptes-connectes)
    - [2. IsvAccounts — comptes ISV](#2-isvaccounts--comptes-isv)
    - [3. IsvOrders — ordres Smart Checkout ISV](#3-isvorders--ordres-smart-checkout-isv)
    - [4. IsvTransactions — transactions marchands connectes](#4-isvtransactions--transactions-marchands-connectes)
    - [5. EcrTerminals — terminaux POS Cloud](#5-ecrterminals--terminaux-pos-cloud)
    - [6. Transfers — transferts marketplace](#6-transfers--transferts-marketplace)
    - [7. MarketplaceOrders — ordres marketplace](#7-marketplaceorders--ordres-marketplace)
    - [8. NativeCheckoutIsv — paiement natif ISV](#8-nativecheckoutisv--paiement-natif-isv)
    - [9. IsvWebhooks — CRUD webhooks ISV](#9-isvwebhooks--crud-webhooks-isv)
    - [10. Webhooks — verification et parsing](#10-webhooks--verification-et-parsing)
- [Architecture](#architecture)
- [Authentification](#authentification)
- [Enums](#enums)
- [Gestion des erreurs](#gestion-des-erreurs)
- [Webhooks (21 evenements)](#webhooks-21-evenements)
- [Pieges evites par le SDK](#pieges-evites-par-le-sdk)
- [Test en sandbox](#test-en-sandbox)
- [Documentation API interactive](#documentation-api-interactive)
- [Integration AI](#integration-ai-claude-cursor-copilot-codex)
- [Licence](#licence)

---

Installation
------------

[](#installation)

```
composer require qrcommunication/viva-isv-sdk
```

**Prerequis** : PHP 8.2+ avec `ext-json` et `ext-curl`.

---

Quick Start
-----------

[](#quick-start)

```
use QrCommunication\VivaIsv\VivaIsvClient;

// 1. Instancier le client avec les 6 credentials
$isv = new VivaIsvClient(
    clientId:       'isv-client-id.apps.vivapayments.com',  // ISV OAuth2
    clientSecret:   'isv-client-secret',                    // ISV OAuth2
    merchantId:     'isv-merchant-uuid',                    // ISV Basic Auth
    apiKey:         'isv-api-key',                          // ISV Basic Auth
    resellerId:     'reseller-uuid',                        // Composite Auth
    resellerApiKey: 'reseller-api-key',                     // Composite Auth
    environment:    'demo',                                 // 'demo' ou 'production'
);

// 2. Creer un compte marchand connecte
$account = $isv->accounts->create(
    email: 'merchant@example.com',
    returnUrl: 'https://myapp.com/onboarding/complete',
);
// => ['accountId' => 'uuid', 'invitation' => ['redirectUrl' => 'https://...']]

// 3. Creer un ordre avec commission ISV
$order = $isv->orders->create(
    connectedMerchantId: $account['accountId'],
    amount: 1500,       // 15,00 EUR
    isvAmount: 100,     // 1,00 EUR de commission
);
// => ['order_code' => 1234567890, 'checkout_url' => 'https://...']

// 4. Rediriger le client vers le checkout
header('Location: ' . $order['checkout_url']);

// 5. Capturer une pre-autorisation
$isv->transactions->capture('preauth-txn-uuid', 'merchant-uuid', amount: 1500);

// 6. Vente sur terminal POS
$session = $isv->terminals->sale(
    terminalId: 16014231,
    amount: 1500,
    isvAmount: 100,
    terminalMerchantId: 'merchant-uuid',
);
$result = $isv->terminals->pollUntilComplete($session['session_id']);

// 7. Rembourser
$isv->transactions->cancel('txn-uuid', 'merchant-uuid', amount: 500);
```

### Ou trouver les credentials

[](#ou-trouver-les-credentials)

CredentialEmplacement dans le Dashboard VivaClient IDSettings > API Access > ISV OAuth Credentials > Client IDClient SecretSettings > API Access > ISV OAuth Credentials > Client SecretMerchant IDSettings > API Access > Merchant IDAPI KeySettings > API Access > API KeyReseller IDSettings > API Access > Reseller Credentials > Reseller IDReseller API KeySettings > API Access > Reseller Credentials > Reseller API Key### Test de connexion

[](#test-de-connexion)

```
if ($isv->testConnection()) {
    echo 'Connexion ISV OK';
}
```

---

Reference des ressources
------------------------

[](#reference-des-ressources)

### 1. ConnectedAccounts — comptes connectes

[](#1-connectedaccounts--comptes-connectes)

**Propriete** : `$isv->accounts`

Gestion des comptes marchands connectes a la plateforme ISV. Creation, consultation, KYB onboarding, verification, mise a jour et suppression.

MethodeSignatureRetour`create``create(string $email, string $returnUrl, ?string $partnerName, ?string $logoUrl)``array{accountId, invitation}``get``get(string $accountId)``array` (details du compte)`list``list()``array` (liste paginee)`isVerified``isVerified(string $accountId)``bool``onboardingUrl``onboardingUrl(string $accountId)``?string``update``update(string $accountId, array $attributes)``array``delete``delete(string $accountId)``array````
// Creer un compte connecte avec branding
$account = $isv->accounts->create(
    email: 'merchant@example.com',
    returnUrl: 'https://myapp.com/onboarding/complete',
    partnerName: 'Ma Plateforme',
    logoUrl: 'https://myapp.com/logo.png',
);

// Rediriger le marchand vers l'onboarding KYB
header('Location: ' . $account['invitation']['redirectUrl']);

// Verifier le statut KYB
if ($isv->accounts->isVerified($account['accountId'])) {
    echo 'Le marchand peut recevoir des paiements';
}

// Recuperer l'URL d'onboarding (null si deja verifie)
$url = $isv->accounts->onboardingUrl($account['accountId']);

// Lister tous les comptes connectes
$accounts = $isv->accounts->list();

// Mettre a jour
$isv->accounts->update($account['accountId'], ['email' => 'new@example.com']);

// Supprimer
$isv->accounts->delete($account['accountId']);
```

---

### 2. IsvAccounts — comptes ISV

[](#2-isvaccounts--comptes-isv)

**Propriete** : `$isv->isvAccounts`

Comptes ISV via le namespace `/isv/v1/` avec options de branding personnalise (couleur, logo).

MethodeSignatureRetour`create``create(string $email, string $returnUrl, ?string $partnerName, ?string $primaryColor, ?string $logoUrl)``array{accountId, invitation}``get``get(string $accountId)``array``list``list()``array````
$account = $isv->isvAccounts->create(
    email: 'merchant@example.com',
    returnUrl: 'https://myapp.com/onboarding/done',
    partnerName: 'Ma Plateforme',
    primaryColor: '#0052FF',
    logoUrl: 'https://myapp.com/logo.png',
);

$details = $isv->isvAccounts->get($account['accountId']);
$all = $isv->isvAccounts->list();
```

---

### 3. IsvOrders — ordres Smart Checkout ISV

[](#3-isvorders--ordres-smart-checkout-isv)

**Propriete** : `$isv->orders`

Creation d'ordres de paiement Smart Checkout pour les marchands connectes avec commission ISV.

MethodeSignatureRetour`create``create(string $connectedMerchantId, int $amount, int $isvAmount, ?string $customerDescription, ?string $merchantReference, bool $allowRecurring, bool $preauth)``array{order_code, checkout_url}``checkoutUrl``checkoutUrl(int $orderCode)``string````
$order = $isv->orders->create(
    connectedMerchantId: 'merchant-uuid',
    amount: 1500,                    // 15,00 EUR
    isvAmount: 100,                  // 1,00 EUR de commission
    customerDescription: 'Consultation bien-etre',
    merchantReference: 'INV-2026-001',
    allowRecurring: true,            // Tokeniser la carte
    preauth: false,
);

echo $order['order_code'];     // 1234567890
echo $order['checkout_url'];   // https://demo.vivapayments.com/web/checkout?ref=1234567890

// Reconstruire l'URL a partir d'un code
$url = $isv->orders->checkoutUrl(1234567890);
```

**Regles** :

- `isvAmount` doit etre <= `amount` (sinon `InvalidArgumentException`)
- Le marchand connecte utilise sa source de paiement par defaut (pas de `sourceCode`)

---

### 4. IsvTransactions — transactions marchands connectes

[](#4-isvtransactions--transactions-marchands-connectes)

**Propriete** : `$isv->transactions`

Operations sur les transactions des marchands connectes. Le SDK utilise automatiquement le Composite Basic Auth.

MethodeSignatureRetour`get``get(string $transactionId, string $connectedMerchantId)``array``listByDate``listByDate(string $connectedMerchantId, string $date)``array``capture``capture(string $transactionId, string $connectedMerchantId, int $amount, ?int $isvAmount)``array``recurring``recurring(string $initialTransactionId, string $connectedMerchantId, int $amount, ?int $isvAmount, ?string $sourceCode)``array``cancel``cancel(string $transactionId, string $connectedMerchantId, ?int $amount, ?string $sourceCode)``array````
// Consulter une transaction
$txn = $isv->transactions->get('txn-uuid', 'merchant-uuid');

// Lister les transactions d'une journee
$transactions = $isv->transactions->listByDate('merchant-uuid', '2026-03-18');

// Capturer une pre-autorisation
$isv->transactions->capture(
    transactionId: 'preauth-txn-uuid',
    connectedMerchantId: 'merchant-uuid',
    amount: 1500,
    isvAmount: 100,
);

// Paiement recurrent
$isv->transactions->recurring(
    initialTransactionId: 'initial-txn-uuid',
    connectedMerchantId: 'merchant-uuid',
    amount: 1500,
    isvAmount: 100,
);

// Remboursement total
$isv->transactions->cancel('txn-uuid', 'merchant-uuid');

// Remboursement partiel (5,00 EUR)
$isv->transactions->cancel('txn-uuid', 'merchant-uuid', amount: 500);
```

**Prerequis** : l'option "Allow recurring payments and pre-auth captures via API" doit etre activee dans Settings > API Access du compte ISV.

---

### 5. EcrTerminals — terminaux POS Cloud

[](#5-ecrterminals--terminaux-pos-cloud)

**Propriete** : `$isv->terminals`

Terminaux de paiement Cloud POS ISV. Recherche, vente, polling de sessions, abort.

MethodeSignatureRetour`search``search(?string $merchantId, ?int $statusId, ?string $sourceCode)``array``sale``sale(int $terminalId, int $amount, int $isvAmount, string $terminalMerchantId, string $cashRegisterId, ?string $merchantReference, int $currencyCode, ?string $sessionId)``array{session_id, success}``getSession``getSession(string $sessionId)``array``listSessions``listSessions(string $date)``array``abort``abort(string $sessionId, string $cashRegisterId)``array``pollUntilComplete``pollUntilComplete(string $sessionId, int $timeoutSeconds, int $intervalMs)``array````
// Rechercher les terminaux d'un marchand
$terminals = $isv->terminals->search(merchantId: 'merchant-uuid');

// Vente POS ISV
$session = $isv->terminals->sale(
    terminalId: 16014231,
    amount: 1500,
    isvAmount: 100,
    terminalMerchantId: 'merchant-uuid',
    cashRegisterId: 'PratiConnect-CR1',
    merchantReference: 'INV-2026-001',
);

echo $session['session_id']; // UUID de la session

// Polling jusqu'au resultat (defaut: 120s timeout, 3s intervalle)
$result = $isv->terminals->pollUntilComplete($session['session_id']);

// Interpreter le resultat avec l'enum
use QrCommunication\VivaIsv\Enums\EcrEventId;

$eventId = EcrEventId::tryFrom($result['eventId']);
if ($eventId?->isSuccessful()) {
    echo 'Transaction reussie : ' . $result['transactionId'];
} else {
    echo 'Echec : ' . $eventId?->label();
}

// Annuler une session active
$isv->terminals->abort('session-uuid', 'PratiConnect-CR1');

// Consulter une session
$session = $isv->terminals->getSession('session-uuid');

// Lister les sessions d'une journee
$sessions = $isv->terminals->listSessions('2026-03-18');
```

**Notes** :

- La pre-autorisation n'est PAS supportee via Cloud Terminal ISV (utiliser Smart Checkout avec `preauth: true`)
- L'abort utilise GET (pas DELETE) — particularite de l'API Viva
- Le `sessionId` est auto-genere si non fourni
- Le SDK construit `isvDetails` automatiquement

---

### 6. Transfers — transferts marketplace

[](#6-transfers--transferts-marketplace)

**Propriete** : `$isv->transfers`

Envoi et annulation de transferts de fonds vers les comptes connectes.

MethodeSignatureRetour`send``send(string $targetAccountId, int $amount, ?string $sourceWalletId, ?string $transactionId, ?string $description)``array{transferId}``reverse``reverse(string $transferId, ?int $amount)``array{transferId}````
// Envoyer des fonds a un vendeur
$transfer = $isv->transfers->send(
    targetAccountId: 'seller-account-uuid',
    amount: 1000,                           // 10,00 EUR
    transactionId: 'txn-uuid',               // Lier a une transaction
    description: 'Commission mars 2026',
);

echo $transfer['transferId'];

// Annuler totalement un transfert
$isv->transfers->reverse('transfer-uuid');

// Annuler partiellement (5,00 EUR)
$isv->transfers->reverse('transfer-uuid', amount: 500);
```

---

### 7. MarketplaceOrders — ordres marketplace

[](#7-marketplaceorders--ordres-marketplace)

**Propriete** : `$isv->marketplace`

Ordres marketplace avec transfert automatique vers le vendeur et gestion des reversals.

MethodeSignatureRetour`create``create(int $amount, string $sellerAccountId, int $sellerAmount, ?string $customerDescription, ?string $merchantReference, ?string $sourceCode, bool $preauth)``array{order_code, checkout_url, platform_fee}``cancel``cancel(string $transactionId, ?int $amount, bool $reverseTransfers, bool $refundPlatformFee)``array````
// Creer un ordre marketplace
$order = $isv->marketplace->create(
    amount: 1500,                    // 15,00 EUR total
    sellerAccountId: 'seller-uuid',
    sellerAmount: 1200,              // 12,00 EUR au vendeur
    customerDescription: 'Achat marketplace',
);

echo $order['order_code'];
echo $order['checkout_url'];
echo $order['platform_fee'];  // 300 (3,00 EUR de commission)

// Remboursement total avec reversal des transferts
$isv->marketplace->cancel('txn-uuid');

// Remboursement partiel sans rembourser la commission plateforme
$isv->marketplace->cancel(
    transactionId: 'txn-uuid',
    amount: 500,
    reverseTransfers: true,
    refundPlatformFee: false,
);
```

---

### 8. NativeCheckoutIsv — paiement natif ISV

[](#8-nativecheckoutisv--paiement-natif-isv)

**Propriete** : `$isv->nativeCheckout`

Paiement natif server-to-server pour les marchands connectes, sans redirection Smart Checkout.

MethodeSignatureRetour`createChargeToken``createChargeToken(string $connectedMerchantId, int $amount, string $paymentData, int $paymentMethodId)``array{chargeToken}``createTransaction``createTransaction(string $connectedMerchantId, string $chargeToken, int $amount, int $isvAmount, int $currencyCode, ?string $merchantTrns, ?string $customerTrns, bool $preauth)``array{transactionId, statusId}`**Flux** :

1. Le client collecte les donnees carte via le JS SDK Viva et obtient `paymentData` (chiffre)
2. Votre serveur cree un charge token via `createChargeToken()`
3. Votre serveur execute la transaction via `createTransaction()`

```
// Etape 1 : creer un charge token
$token = $isv->nativeCheckout->createChargeToken(
    connectedMerchantId: 'merchant-uuid',
    amount: 1500,
    paymentData: $encryptedCardData,  // Du JS SDK Viva
);

// Etape 2 : executer la transaction
$txn = $isv->nativeCheckout->createTransaction(
    connectedMerchantId: 'merchant-uuid',
    chargeToken: $token['chargeToken'],
    amount: 1500,
    isvAmount: 100,
    merchantTrns: 'INV-2026-001',
    customerTrns: 'Consultation bien-etre',
);

echo $txn['transactionId'];
echo $txn['statusId'];
```

---

### 9. IsvWebhooks — CRUD webhooks ISV

[](#9-isvwebhooks--crud-webhooks-isv)

**Propriete** : `$isv->isvWebhooks`

Creation, listing, mise a jour et suppression d'abonnements webhook ISV.

MethodeSignatureRetour`create``create(string $url, string $eventType, ?string $description)``array` (avec `webhookId`)`list``list()``array``update``update(string $webhookId, string $url, ?string $eventType)``array``delete``delete(string $webhookId)``array````
// Creer un webhook
$webhook = $isv->isvWebhooks->create(
    url: 'https://myapp.com/webhooks/viva',
    eventType: 'transaction.payment.created',
    description: 'Notifications de paiement',
);

// Lister
$webhooks = $isv->isvWebhooks->list();

// Modifier
$isv->isvWebhooks->update(
    webhookId: $webhook['webhookId'],
    url: 'https://myapp.com/webhooks/viva-v2',
    eventType: 'transaction.refund.created',
);

// Supprimer
$isv->isvWebhooks->delete($webhook['webhookId']);
```

---

### 10. Webhooks — verification et parsing

[](#10-webhooks--verification-et-parsing)

**Propriete** : `$isv->webhooks`

Verification de la requete GET initiale de Viva Wallet et parsing des payloads POST (21 types d'evenements).

MethodeSignatureRetour`verificationResponse``verificationResponse(string $verificationKey)``array{StatusCode, Key}``parse``parse(string $rawBody)``array{event_type, event_type_id, event_data}``isKnownEvent``Webhooks::isKnownEvent(int $eventTypeId)` (statique)`bool````
// GET — verification initiale
$verificationKey = config('services.viva.verification_key');
return response()->json(
    $isv->webhooks->verificationResponse($verificationKey)
);
// => {"StatusCode": 0, "Key": "votre-cle"}

// POST — parsing des evenements
$event = $isv->webhooks->parse(file_get_contents('php://input'));

echo $event['event_type'];     // 'transaction.payment.created'
echo $event['event_type_id'];  // 1796
$data = $event['event_data'];

switch ($event['event_type']) {
    case 'transaction.payment.created':
        // Traiter le paiement
        break;
    case 'transaction.refund.created':
        // Traiter le remboursement
        break;
    case 'account.connected':
        // Nouveau marchand connecte
        break;
}

// Verifier si un EventTypeId est connu (methode statique)
use QrCommunication\VivaIsv\Resources\Webhooks;

if (Webhooks::isKnownEvent(1796)) {
    echo 'Evenement reconnu';
}
```

---

Architecture
------------

[](#architecture)

```
VivaIsvClient
├── $accounts          → ConnectedAccounts   (7 methodes)
├── $isvAccounts       → IsvAccounts         (3 methodes)
├── $orders            → IsvOrders           (2 methodes)
├── $transactions      → IsvTransactions     (5 methodes)
├── $terminals         → EcrTerminals        (6 methodes)
├── $transfers         → Transfers           (2 methodes)
├── $marketplace       → MarketplaceOrders   (2 methodes)
├── $nativeCheckout    → NativeCheckoutIsv   (2 methodes)
├── $isvWebhooks       → IsvWebhooks         (4 methodes)
└── $webhooks          → Webhooks            (3 methodes)

36 methodes au total — 10 ressources

```

```
src/
├── VivaIsvClient.php              # Point d'entree, instancie les 10 ressources
├── IsvConfig.php                  # Configuration (6 credentials + environnement)
├── HttpClient.php                 # Client HTTP (Bearer, Basic, Composite Auth)
├── Enums/
│   ├── Environment.php            # demo | production
│   ├── EcrEventId.php             # 8 codes resultat POS
│   └── TransactionEventId.php     # 24 codes de declin
├── Exceptions/
│   ├── VivaException.php          # Exception de base
│   ├── ApiException.php           # Erreurs API (4xx, 5xx)
│   └── AuthenticationException.php # Erreurs OAuth2 (401)
└── Resources/
    ├── ConnectedAccounts.php      # 7 methodes
    ├── IsvAccounts.php            # 3 methodes
    ├── IsvOrders.php              # 2 methodes
    ├── IsvTransactions.php        # 5 methodes
    ├── EcrTerminals.php           # 6 methodes
    ├── Transfers.php              # 2 methodes
    ├── MarketplaceOrders.php      # 2 methodes
    ├── NativeCheckoutIsv.php      # 2 methodes
    ├── IsvWebhooks.php            # 4 methodes
    └── Webhooks.php               # 3 methodes

```

---

Authentification
----------------

[](#authentification)

Le SDK gere **3 modes d'authentification** automatiquement. L'utilisateur fournit les 6 credentials au constructeur et le SDK choisit le bon mode pour chaque appel.

ModeUsernamePasswordUtilise pour**ISV OAuth2 (Bearer)**`clientId``clientSecret`Comptes, ordres ISV, terminaux, transferts, marketplace, native checkout, webhooks ISV**ISV Basic Auth**`merchantId``apiKey`Operations Legacy sur le propre compte ISV**Composite Basic Auth**`{resellerId}:{connectedMerchantId}``resellerApiKey`Transactions des marchands connectes (capture, recurrent, annulation)### Composite Basic Auth (non documente par Viva Wallet)

[](#composite-basic-auth-non-documente-par-viva-wallet)

Le format `{ResellerID}:{ConnectedMerchantID}` comme username avec `{ResellerAPIKey}` comme password a ete decouvert empiriquement lors de la certification ISV. Ce format n'est pas documente dans la documentation officielle Viva Wallet.

Le SDK construit automatiquement ce header — vous n'avez qu'a passer le `connectedMerchantId` aux methodes de `$isv->transactions`.

### Token OAuth2

[](#token-oauth2)

Le token Bearer est obtenu automatiquement et rafraichi avant expiration (marge de 60 secondes). Pour forcer un refresh :

```
$isv->invalidateToken();
```

---

Enums
-----

[](#enums)

### EcrEventId — codes resultat Cloud Terminal

[](#ecreventid--codes-resultat-cloud-terminal)

```
use QrCommunication\VivaIsv\Enums\EcrEventId;

$event = EcrEventId::tryFrom($session['eventId']);
$event->isSuccessful();  // true si SUCCESS (0)
$event->isTerminal();    // true si etat final (pas IN_PROGRESS)
$event->shouldPoll();    // true si IN_PROGRESS (1100)
$event->label();         // 'Transaction successful', 'Declined', etc.
```

ValeurConstanteDescription0`SUCCESS`Transaction reussie1003`TERMINAL_TIMEOUT`Terminal hors delai1006`DECLINED`Transaction refusee1016`ABORTED`Transaction annulee1020`INSUFFICIENT_FUNDS`Fonds insuffisants1099`GENERIC_ERROR`Erreur generique1100`IN_PROGRESS`En cours (continuer le polling)6000`BAD_PARAMS`Parametres invalides### TransactionEventId — codes de declin detailles

[](#transactioneventid--codes-de-declin-detailles)

```
use QrCommunication\VivaIsv\Enums\TransactionEventId;

$decline = TransactionEventId::tryFrom($session['transactionEventId']);
echo $decline->label();       // 'Insufficient funds'
echo $decline->testAmount();  // 9951 (montant pour declencher ce declin en demo)
```

ValeurConstanteMontant test10001`REFER_TO_ISSUER`—10003`INVALID_MERCHANT`—10004`PICKUP_CARD`—10005`DO_NOT_HONOR`—10006`GENERAL_ERROR`990610012`INVALID_TRANSACTION`—10013`INVALID_AMOUNT`—10014`INVALID_CARD`991410030`FORMAT_ERROR`—10041`LOST_CARD`—10043`STOLEN_CARD`992010051`INSUFFICIENT_FUNDS`995110054`EXPIRED_CARD`995410055`INCORRECT_PIN`—10057`NOT_PERMITTED_CARDHOLDER`995710058`NOT_PERMITTED_TERMINAL`—10061`WITHDRAWAL_LIMIT`996110062`RESTRICTED_CARD`—10063`SECURITY_VIOLATION`—10065`ACTIVITY_LIMIT`—10068`LATE_RESPONSE`—10070`CALL_ISSUER`—10075`PIN_TRIES_EXCEEDED`—10200`UNMAPPED`—### Environment

[](#environment)

```
use QrCommunication\VivaIsv\Enums\Environment;

// Passer en string ou en enum
$isv = new VivaIsvClient(..., environment: 'demo');
$isv = new VivaIsvClient(..., environment: Environment::PRODUCTION);
```

---

Gestion des erreurs
-------------------

[](#gestion-des-erreurs)

Le SDK definit 3 exceptions dans le namespace `QrCommunication\VivaIsv\Exceptions` :

```
RuntimeException
└── VivaException         (base — httpStatus, responseBody, getErrorCode(), getErrorText())
    ├── ApiException      (erreurs API 4xx/5xx)
    └── AuthenticationException  (erreurs OAuth2 — httpStatus = 401)

```

```
use QrCommunication\VivaIsv\Exceptions\ApiException;
use QrCommunication\VivaIsv\Exceptions\AuthenticationException;

try {
    $order = $isv->orders->create('merchant-uuid', 1500, isvAmount: 100);
} catch (AuthenticationException $e) {
    // Credentials ISV invalides
    echo $e->getMessage(); // 'ISV OAuth2 authentication failed: ...'
} catch (ApiException $e) {
    // Erreur API (400, 404, 500, etc.)
    echo $e->getMessage();       // Message d'erreur
    echo $e->httpStatus;         // Code HTTP
    echo $e->getErrorCode();     // Code Viva (ErrorCode)
    echo $e->getErrorText();     // Texte Viva (ErrorText)
    print_r($e->responseBody);   // Body JSON complet
}
```

Les methodes `capture()` et `recurring()` lancent `ApiException` si `ErrorCode !== 0` dans la reponse Viva.

---

Webhooks (21 evenements)
------------------------

[](#webhooks-21-evenements)

Le SDK reconnait 21 types d'evenements webhook :

IDType1796`transaction.payment.created`1797`transaction.refund.created`1798`transaction.payment.cancelled`1799`transaction.reversal.created`1800`transaction.preauth.created`1801`transaction.preauth.completed`1802`transaction.preauth.cancelled`1810`pos.session.created`1811`pos.session.failed`1812`transaction.price.calculated`1813`transaction.failed`1819`account.connected`1820`account.verification.status.changed`1821`account.transaction.created`1822`command.bank.transfer.created`1823`command.bank.transfer.executed`1824`transfer.created`1825`obligation.created`1826`obligation.captured`1827`order.updated`1828`sale.transactions.file`### Gestion des webhooks ISV (CRUD)

[](#gestion-des-webhooks-isv-crud)

```
// Creer
$wh = $isv->isvWebhooks->create(
    url: 'https://myapp.com/webhooks/viva',
    eventType: 'transaction.payment.created',
);

// Lister
$all = $isv->isvWebhooks->list();

// Modifier
$isv->isvWebhooks->update($wh['webhookId'], url: 'https://myapp.com/v2/webhooks');

// Supprimer
$isv->isvWebhooks->delete($wh['webhookId']);
```

### Reception et parsing

[](#reception-et-parsing)

```
// Endpoint GET — verification initiale
public function verify(Request $request)
{
    return response()->json(
        $this->isv->webhooks->verificationResponse(
            config('services.viva.verification_key')
        )
    );
}

// Endpoint POST — reception des evenements
public function handle(Request $request)
{
    $event = $this->isv->webhooks->parse($request->getContent());

    match ($event['event_type']) {
        'transaction.payment.created' => $this->handlePayment($event['event_data']),
        'transaction.refund.created'  => $this->handleRefund($event['event_data']),
        'account.connected'           => $this->handleNewAccount($event['event_data']),
        default => null,
    };

    return response()->json(['status' => 'ok']);
}
```

---

Pieges evites par le SDK
------------------------

[](#pieges-evites-par-le-sdk)

Ces 9 pieges ont ete decouverts lors de la certification ISV. Le SDK les gere automatiquement — vous n'avez pas a vous en soucier.

\#PiegeCe que le SDK fait pour vous1**Composite Basic Auth** non documente (`ResellerID:MerchantID / ResellerAPIKey`)Le `HttpClient` construit automatiquement le header composite pour chaque appel sur un marchand connecte2**camelCase vs PascalCase** — New API en camelCase, Legacy API en PascalCaseChaque ressource envoie les parametres dans la bonne casse3**Pas de `sourceCode`** dans les ordres ISV (le marchand connecte utilise sa source par defaut)`IsvOrders::create()` n'envoie jamais de `sourceCode`4**`isvDetails`** obligatoire pour les ventes POS ISV`EcrTerminals::sale()` construit `isvDetails` automatiquement5**Abort POS** utilise GET (pas DELETE) avec `cashRegisterId` en query param`EcrTerminals::abort()` utilise GET6**Endpoints ISV** differents des endpoints marchands (`/ecr/isv/v1/` vs `/ecr/v1/`)Chaque ressource utilise le bon prefixe7**Token OAuth2** expire silencieusementLe `HttpClient` rafraichit le token automatiquement avec une marge de 60s8**Reponses vides** (200 sans body) sur certains endpoints POSLe `HttpClient` retourne `[]` au lieu de crash JSON9**`MerchantId`** en query string pour les ordres et native checkout ISVLes methodes `create()` ajoutent automatiquement `?MerchantId=`---

Test en sandbox
---------------

[](#test-en-sandbox)

Utiliser `environment: 'demo'` pour tester sans transactions reelles.

### Carte de test

[](#carte-de-test)

ChampValeurNumero`4111 1111 1111 1111`ExpirationToute date futureCVV`111`### Montants de test (declins)

[](#montants-de-test-declins)

Utiliser `TransactionEventId::testAmount()` pour obtenir les montants qui declenchent chaque type de declin en demo :

```
use QrCommunication\VivaIsv\Enums\TransactionEventId;

// Montant qui declenche "Insufficient funds" en demo
$amount = TransactionEventId::INSUFFICIENT_FUNDS->testAmount(); // 9951

$order = $isv->orders->create('merchant-uuid', $amount);
```

Montant (centimes)Declin9951Fonds insuffisants9954Carte expiree9920Carte volee9957Carte non autorisee9961Limite de retrait9906Erreur generale9914Carte invalide---

Documentation API interactive
-----------------------------

[](#documentation-api-interactive)

Documentation interactive ReDoc disponible :

- **En ligne** : [qrcommunication.github.io/sdk-php-viva-isv](https://qrcommunication.github.io/sdk-php-viva-isv/)
- **Locale** : ouvrir `docs/index.html` dans un navigateur
- **OpenAPI** : `docs/openapi.yaml` ou `openapi.yaml` a la racine

---

Intégration IA
--------------

[](#intégration-ia)

Ce SDK inclut un **skill détaillé** (`skill/SKILL.md`) automatiquement détecté par les assistants IA. Il fournit la référence complète des 10 resources, 36+ méthodes, 3 modes d'auth, enums, exceptions, 9 pièges de certification et patterns d'implémentation.

OutilFichierDétection**Claude Code**`CLAUDE.md` + `skill/SKILL.md`Automatique**Cursor**`.cursorrules`Automatique**GitHub Copilot**`.github/copilot-instructions.md`Automatique**OpenAI Codex**`AGENTS.md`Automatique```
// Un agent IA peut construire cet appel à partir de :
// "Crée un paiement ISV de 50€ avec 5€ de commission"
$order = $isv->orders->create(
    connectedMerchantId: $merchantId,
    amount: 5000,
    isvAmount: 500,
);
```

---

Licence
-------

[](#licence)

[MIT](LICENSE) — QrCommunication

###  Health Score

42

—

FairBetter than 90% of packages

Maintenance89

Actively maintained with recent releases

Popularity11

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity52

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 ~0 days

Total

9

Last Release

55d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/4af9a1dce07647c267375fb7a348b52040ef59b40cb50b907b61c9364d0a0494?d=identicon)[ronylicha](/maintainers/ronylicha)

---

Top Contributors

[![ronylicha](https://avatars.githubusercontent.com/u/4362602?v=4)](https://github.com/ronylicha "ronylicha (11 commits)")

---

Tags

sdkpaymentmarketplacevivaVivaWalletisv

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

![Health badge](/badges/qrcommunication-viva-isv-sdk/health.svg)

```
[![Health](https://phpackages.com/badges/qrcommunication-viva-isv-sdk/health.svg)](https://phpackages.com/packages/qrcommunication-viva-isv-sdk)
```

###  Alternatives

[sebdesign/laravel-viva-payments

A Laravel package for integrating the Viva Payments gateway

4845.9k](/packages/sebdesign-laravel-viva-payments)[robokassa/sdk-php

SDK для работы с Robokassa в PHP

119.2k](/packages/robokassa-sdk-php)

PHPackages © 2026

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