PHPackages                             qrcommunication/viva-merchant-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-merchant-sdk

ActiveLibrary[Payment Processing](/categories/payments)

qrcommunication/viva-merchant-sdk
=================================

PHP SDK for Viva Wallet Merchant API — orders, transactions, sources, webhooks

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

Since Mar 18Pushed 1mo agoCompare

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

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

Viva Wallet Merchant SDK — PHP
==============================

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

[![Version 1.3.5](https://camo.githubusercontent.com/a9ef15743ddac7e1a307b91152b9ff217d8a982ec7a7e2b4ee71f7892c6d9dd8/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f76657273696f6e2d312e332e352d626c75652e737667)](https://github.com/qrcommunication/sdk-php-viva-merchant/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/9c86a4f0bbaeecacf0adb07fa64e5139cf125f8077345bad9f64201bf02c24a7/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5061636b61676973742d7172636f6d6d756e69636174696f6e253246766976612d2d6d65726368616e742d2d73646b2d6f72616e67652e737667)](https://packagist.org/packages/qrcommunication/viva-merchant-sdk)

SDK PHP complet pour l'intégration Viva Wallet. Couvre **9 ressources** : Orders, Transactions, Sources, Wallets, BankAccounts, NativeCheckout, DataServices, Account et Webhooks.

**PHP 8.2+** requis. Compatible Laravel, Symfony, ou tout projet PHP.

> **Ce SDK couvre les opérations marchands standard.** Pour les opérations ISV (comptes connectés, composite auth), voir [`sdk-php-viva-isv`](https://github.com/qrcommunication/sdk-php-viva-isv).

---

Table des matières
------------------

[](#table-des-matières)

- [Installation](#installation)
- [Démarrage rapide](#d%C3%A9marrage-rapide)
- [Référence des ressources](#r%C3%A9f%C3%A9rence-des-ressources)
    - [1. Orders](#1-orders--vivaorders)
    - [2. Transactions](#2-transactions--vivatransactions)
    - [3. Sources](#3-sources--vivasources)
    - [4. Wallets](#4-wallets--vivawallets)
    - [5. BankAccounts](#5-bankaccounts--vivabankaccounts)
    - [6. NativeCheckout](#6-nativecheckout--vivanativecheckout)
    - [7. DataServices](#7-dataservices--vivadataservices)
    - [8. Webhooks](#8-webhooks--vivawebhooks)
    - [9. Account](#9-account--vivaaccount)
- [Architecture](#architecture)
- [Enums](#enums)
- [Gestion d'erreurs](#gestion-derreurs)
- [Webhooks — Guide d'intégration](#webhooks--guide-dint%C3%A9gration)
- [Carte de test](#carte-de-test)
- [Documentation interactive](#documentation-interactive)
- [Intégration IA](#int%C3%A9gration-ia)
- [Licence](#licence)

---

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

[](#installation)

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

**Prérequis** : PHP 8.2+ avec `ext-json` et `ext-curl`.

---

Démarrage rapide
----------------

[](#démarrage-rapide)

```
use QrCommunication\VivaMerchant\VivaClient;

$viva = new VivaClient(
    merchantId: 'votre-merchant-uuid',
    apiKey: 'votre-api-key',
    clientId: 'xxx.apps.vivapayments.com',
    clientSecret: 'votre-client-secret',
    environment: 'demo', // ou 'production'
);

// Créer un ordre de paiement
$order = $viva->orders->create(amount: 1500, customerDescription: 'Consultation');
// Rediriger le client vers $order['checkout_url']

// Vérifier une transaction après paiement
$txn = $viva->transactions->getV2('transaction-uuid');

// Rembourser
$viva->transactions->cancel('transaction-uuid', amount: 500);

// Capturer une pré-autorisation
$viva->transactions->capture('preauth-uuid', amount: 1500);

// Charge récurrente
$viva->transactions->recurring('initial-txn-uuid', amount: 1500);

// Apple Pay / Google Pay
$token = $viva->nativeCheckout->createChargeToken(1500, $applePayData);
$txn = $viva->nativeCheckout->createTransaction($token['chargeToken'], 1500);

// Tester la connexion
$viva->testConnection(); // true ou false
```

---

Référence des ressources
------------------------

[](#référence-des-ressources)

### 1. Orders — `$viva->orders`

[](#1-orders--viva-orders)

Ordres de paiement Smart Checkout.

#### `create()` — Créer un ordre

[](#create--créer-un-ordre)

```
$order = $viva->orders->create(
    amount: 1500,                         // Centimes (15,00 EUR)
    customerDescription: 'Consultation',  // Affiché au client
    merchantReference: 'session_123',     // Référence interne
    allowRecurring: true,                 // Tokeniser la carte
    preauth: false,                       // Pré-autorisation ?
    maxInstallments: 3,                   // Paiement en 3x
);

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

ParamètreTypeDéfautDescription`amount``int`**requis**Montant en centimes`customerDescription``?string``null`Texte affiché au client`merchantReference``?string``null`Référence interne (exports)`sourceCode``?string``null`Source de paiement`allowRecurring``bool``false`Autoriser les charges récurrentes`preauth``bool``false`Pré-autorisation uniquement`maxInstallments``int``0`Nombre max de versements**Retour :** `array{order_code: int, checkout_url: string}`

#### `get()` — Statut d'un ordre

[](#get--statut-dun-ordre)

```
$order = $viva->orders->get(orderCode: 1234567890);
```

#### `cancel()` — Annuler un ordre non payé

[](#cancel--annuler-un-ordre-non-payé)

```
$viva->orders->cancel(orderCode: 1234567890);
```

#### `checkoutUrl()` — URL de checkout (sans appel API)

[](#checkouturl--url-de-checkout-sans-appel-api)

```
$url = $viva->orders->checkoutUrl(orderCode: 1234567890);
// 'https://demo.vivapayments.com/web/checkout?ref=1234567890'
```

---

### 2. Transactions — `$viva->transactions`

[](#2-transactions--viva-transactions)

Consultation, remboursement, capture et paiements récurrents.

#### `get()` — Détails complets (Legacy API, PascalCase)

[](#get--détails-complets-legacy-api-pascalcase)

```
$txn = $viva->transactions->get('transaction-uuid');
echo $txn['Transactions'][0]['Amount'];
echo $txn['Transactions'][0]['StatusId'];
```

#### `getV2()` — Détails légers (New API, camelCase)

[](#getv2--détails-légers-new-api-camelcase)

```
$txn = $viva->transactions->getV2('transaction-uuid');
echo $txn['email'];
echo $txn['amount'];      // En EUR (pas en centimes)
echo $txn['statusId'];    // 'F'
echo $txn['orderCode'];
```

Recommandé pour vérifier les paiements Smart Checkout.

#### `listByDate()` — Lister par date

[](#listbydate--lister-par-date)

```
$transactions = $viva->transactions->listByDate('2026-03-18');

foreach ($transactions as $txn) {
    echo $txn['TransactionId'] . ' — ' . $txn['Amount'] . "\n";
}
```

**Retour :** `array`

#### `cancel()` — Annuler / Rembourser

[](#cancel--annuler--rembourser)

```
// Remboursement total
$result = $viva->transactions->cancel('transaction-uuid');

// Remboursement partiel (5,00 EUR)
$result = $viva->transactions->cancel('transaction-uuid', amount: 500);

echo $result['TransactionId']; // UUID du remboursement
```

ParamètreTypeDéfautDescription`transactionId``string`**requis**UUID de la transaction`amount``?int``null`Centimes (`null` = total)`sourceCode``?string``null`Source de paiementMême jour = annulation (void). Jour passé = remboursement (refund).

#### `capture()` — Capturer une pré-autorisation

[](#capture--capturer-une-pré-autorisation)

```
$result = $viva->transactions->capture('preauth-uuid', amount: 1500);
```

Lève `ApiException` si la capture échoue.

#### `recurring()` — Charge récurrente

[](#recurring--charge-récurrente)

```
$result = $viva->transactions->recurring(
    initialTransactionId: 'initial-txn-uuid',
    amount: 1500,
    sourceCode: '1234', // optionnel
);
```

Prérequis : l'ordre initial doit avoir été créé avec `allowRecurring: true`.

---

### 3. Sources — `$viva->sources`

[](#3-sources--viva-sources)

Gestion des sources de paiement (domaines autorisés, URLs de redirection).

#### `list()` — Lister les sources

[](#list--lister-les-sources)

```
$sources = $viva->sources->list();

foreach ($sources as $source) {
    echo $source['Name'] . ' — ' . $source['SourceCode'] . "\n";
}
```

#### `create()` — Créer une source

[](#create--créer-une-source)

```
$source = $viva->sources->create(
    name: 'Mon site web',
    sourceCode: '1234',
    domain: 'www.example.com',
    pathSuccess: '/paiement/succes',
    pathFail: '/paiement/echec',
);
```

ParamètreTypeDéfautDescription`name``string`**requis**Nom d'affichage`sourceCode``string`**requis**Code à 4 chiffres`domain``?string``null`Domaine du site`pathSuccess``?string``null`Redirection succès`pathFail``?string``null`Redirection échec---

### 4. Wallets — `$viva->wallets`

[](#4-wallets--viva-wallets)

Portefeuilles (sous-comptes), soldes et transferts.

#### `list()` — Lister les portefeuilles

[](#list--lister-les-portefeuilles)

```
$wallets = $viva->wallets->list();
```

#### `balance()` — Solde agrégé

[](#balance--solde-agrégé)

```
$balance = $viva->wallets->balance();
echo $balance['available'];  // 150.50
echo $balance['pending'];    // 25.00
echo $balance['reserved'];   // 0.00
echo $balance['currency'];   // 'EUR'
```

**Retour :** `array{available: float, pending: float, reserved: float, currency: string}`

#### `transfer()` — Transfert entre wallets

[](#transfer--transfert-entre-wallets)

```
$viva->wallets->transfer(
    amount: 5000,                        // 50,00 EUR
    sourceWalletId: 'source-uuid',
    targetWalletId: 'target-uuid',
    description: 'Transfert mensuel',
);
```

Prérequis : « Allow transfers between accounts » dans Settings > API Access.

#### `listDetailed()` — Liste enrichie (IBAN, SWIFT)

[](#listdetailed--liste-enrichie-iban-swift)

```
$wallets = $viva->wallets->listDetailed();

foreach ($wallets as $wallet) {
    echo $wallet['iban'] . ' — ' . $wallet['amount'] . "\n";
    echo $wallet['isPrimary'] ? 'Principal' : 'Secondaire';
}
```

#### `create()` — Créer un portefeuille

[](#create--créer-un-portefeuille)

```
$viva->wallets->create(friendlyName: 'Compte secondaire', currencyCode: 'EUR');
```

#### `update()` — Renommer un portefeuille

[](#update--renommer-un-portefeuille)

```
$viva->wallets->update(walletId: 12345, friendlyName: 'Nouveau nom');
```

#### `searchTransactions()` — Rechercher les transactions de compte

[](#searchtransactions--rechercher-les-transactions-de-compte)

```
$transactions = $viva->wallets->searchTransactions([
    'date_from' => '2026-03-01',
    'date_to' => '2026-03-18',
    'walletId' => 12345,
]);
```

#### `getTransaction()` — Détails d'une transaction de compte

[](#gettransaction--détails-dune-transaction-de-compte)

```
$txn = $viva->wallets->getTransaction('transaction-uuid');
```

---

### 5. BankAccounts — `$viva->bankAccounts`

[](#5-bankaccounts--viva-bankaccounts)

Comptes bancaires IBAN et virements SEPA.

#### `link()` — Lier un IBAN

[](#link--lier-un-iban)

```
$result = $viva->bankAccounts->link(
    iban: 'FR7630006000011234567890189',
    beneficiaryName: 'Jean Dupont',
    friendlyName: 'Compte principal',
);

echo $result['bankAccountId']; // UUID
echo $result['isVivaIban'];    // false
```

#### `transferOptions()` — Options de transfert

[](#transferoptions--options-de-transfert)

```
$options = $viva->bankAccounts->transferOptions('bank-account-uuid');
```

#### `feeCommand()` — Calculer les frais avant virement

[](#feecommand--calculer-les-frais-avant-virement)

```
$fees = $viva->bankAccounts->feeCommand(
    bankAccountId: 'bank-account-uuid',
    amount: 10000,                    // 100,00 EUR
    walletId: 'source-wallet-uuid',
    isInstant: true,                  // SEPA instantané
    instructionType: 'SHA',           // Frais partagés
);

echo $fees['bankCommandId']; // À passer à send()
echo $fees['fee'];           // Frais en centimes
```

#### `send()` — Exécuter un virement SEPA

[](#send--exécuter-un-virement-sepa)

```
$result = $viva->bankAccounts->send(
    bankAccountId: 'bank-account-uuid',
    amount: 10000,
    walletId: 'source-wallet-uuid',
    bankCommandId: 'fee-command-uuid',  // Optionnel
    description: 'Virement mensuel',
);

echo $result['commandId']; // UUID du virement
echo $result['isInstant']; // true/false
echo $result['fee'];       // Frais en centimes
```

#### `list()` — Lister les comptes liés

[](#list--lister-les-comptes-liés)

```
$accounts = $viva->bankAccounts->list();
```

#### `get()` — Détails d'un compte lié

[](#get--détails-dun-compte-lié)

```
$account = $viva->bankAccounts->get('bank-account-uuid');
```

---

### 6. NativeCheckout — `$viva->nativeCheckout`

[](#6-nativecheckout--viva-nativecheckout)

Paiements Apple Pay et Google Pay.

#### `createChargeToken()` — Générer un token de charge

[](#createchargetoken--générer-un-token-de-charge)

```
$token = $viva->nativeCheckout->createChargeToken(
    amount: 1500,
    paymentData: $applePayPaymentDataString,
    paymentMethod: 'applepay', // ou 'googlepay'
    sourceCode: '1234',
);

echo $token['chargeToken'];       // Token à passer à createTransaction()
echo $token['redirectToACSForm']; // Formulaire 3DS (si applicable)
```

ParamètreTypeDéfautDescription`amount``int`**requis**Montant en centimes`paymentData``string`**requis**Données Apple Pay / Google Pay`paymentMethod``string``'applepay'``'applepay'` ou `'googlepay'``sourceCode``?string``null`Source de paiement`dynamicDescriptor``?string``null`Descripteur dynamique#### `createTransaction()` — Exécuter la transaction

[](#createtransaction--exécuter-la-transaction)

```
$txn = $viva->nativeCheckout->createTransaction(
    chargeToken: $token['chargeToken'],
    amount: 1500,
    currencyCode: 978,             // EUR (ISO 4217 numérique)
    merchantTrns: 'ref_123',
    customerTrns: 'Consultation',
);

echo $txn['transactionId']; // UUID
echo $txn['statusId'];      // 'F' = finalisée
echo $txn['amount'];        // 1500
echo $txn['orderCode'];     // Code de l'ordre
```

ParamètreTypeDéfautDescription`chargeToken``string`**requis**Token de `createChargeToken()``amount``int`**requis**Montant en centimes`currencyCode``int``978`ISO 4217 numérique`sourceCode``?string``null`Source de paiement`merchantTrns``?string``null`Référence interne`customerTrns``?string``null`Description client`preauth``bool``false`Pré-autorisation ?`tipAmount``int``0`Pourboire en centimes`installments``?int``null`Nombre de versements---

### 7. DataServices — `$viva->dataServices`

[](#7-dataservices--viva-dataservices)

Rapports MT940 et souscriptions webhook pour les fichiers de données.

#### `mt940()` — Rapport MT940

[](#mt940--rapport-mt940)

```
$report = $viva->dataServices->mt940('2026-03-18');
```

#### `createSubscription()` — Créer une souscription webhook

[](#createsubscription--créer-une-souscription-webhook)

```
$sub = $viva->dataServices->createSubscription(
    url: 'https://example.com/webhooks/viva-files',
    eventType: 'SaleTransactionsFileGenerated',
);
echo $sub['subscriptionId'];
```

#### `updateSubscription()` — Mettre à jour

[](#updatesubscription--mettre-à-jour)

```
$viva->dataServices->updateSubscription(
    subscriptionId: 'sub-uuid',
    url: 'https://example.com/webhooks/new-url',
    eventType: null, // null = conserver l'actuel
);
```

#### `deleteSubscription()` — Supprimer

[](#deletesubscription--supprimer)

```
$viva->dataServices->deleteSubscription('sub-uuid');
```

#### `listSubscriptions()` — Lister

[](#listsubscriptions--lister)

```
$subs = $viva->dataServices->listSubscriptions();

foreach ($subs as $sub) {
    echo $sub['subscriptionId'] . ' → ' . $sub['url'] . "\n";
}
```

#### `requestFile()` — Demander la génération d'un fichier

[](#requestfile--demander-la-génération-dun-fichier)

```
$viva->dataServices->requestFile('2026-03-18');
```

Déclenche la génération asynchrone. Utilisez une souscription webhook pour être notifié.

---

### 8. Webhooks — `$viva->webhooks`

[](#8-webhooks--viva-webhooks)

Vérification et parsing des webhooks Viva Wallet. Aucun appel API — tout est local.

#### `verificationResponse()` — Répondre au GET de vérification

[](#verificationresponse--répondre-au-get-de-vérification)

```
public function verify()
{
    return response()->json(
        $viva->webhooks->verificationResponse('votre-verification-key')
    );
    // => {"StatusCode": 0, "Key": "votre-verification-key"}
}
```

#### `parse()` — Parser un webhook POST

[](#parse--parser-un-webhook-post)

```
public function handle(Request $request)
{
    $event = $viva->webhooks->parse($request->getContent());

    echo $event['event_type'];     // 'transaction.payment.created'
    echo $event['event_type_id'];  // 1796
    echo $event['event_data'];     // Données de l'événement

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

**Retour :** `array{event_type: string, event_type_id: int, event_data: array}`

Lève `InvalidArgumentException` si le JSON est invalide.

#### `isKnownEvent()` — Vérifier un ID d'événement

[](#isknownevent--vérifier-un-id-dévénement)

```
$viva->webhooks->isKnownEvent(1796); // true
$viva->webhooks->isKnownEvent(9999); // false
```

#### `eventTypeIds()` — Lister les IDs connus

[](#eventtypeids--lister-les-ids-connus)

```
$ids = $viva->webhooks->eventTypeIds();
// [1796, 1797, 1798, ..., 1828]
```

#### 21 types d'événements supportés

[](#21-types-dévénements-supportés)

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`---

### 9. Account — `$viva->account`

[](#9-account--viva-account)

Informations du compte marchand.

#### `info()` — Informations du compte

[](#info--informations-du-compte)

```
$info = $viva->account->info();
echo $info['merchantId'];
echo $info['businessName'];
echo $info['email'];
```

#### `wallets()` — Portefeuilles du compte

[](#wallets--portefeuilles-du-compte)

```
$wallets = $viva->account->wallets();
```

---

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

[](#architecture)

```
src/
├── VivaClient.php          # Point d'entrée — instancie les 9 ressources
├── Config.php              # Configuration (URLs par environnement)
├── HttpClient.php          # Client HTTP Guzzle (OAuth2 auto, Basic Auth)
├── Enums/
│   ├── Environment.php     # demo | production
│   ├── Currency.php        # Codes ISO 4217 numériques
│   └── TransactionStatus.php  # F, A, C, E, M, X, R
├── Exceptions/
│   ├── VivaException.php          # Classe de base (RuntimeException)
│   ├── ApiException.php           # Erreur API (4xx, 5xx)
│   ├── AuthenticationException.php # Échec OAuth2 (401)
│   └── ValidationException.php    # Validation (422)
└── Resources/
    ├── Orders.php           # Smart Checkout
    ├── Transactions.php     # Get, list, cancel, capture, recurring
    ├── Sources.php          # Sources de paiement
    ├── Wallets.php          # Portefeuilles, soldes, transferts
    ├── BankAccounts.php     # IBAN, virements SEPA
    ├── NativeCheckout.php   # Apple Pay, Google Pay
    ├── DataServices.php     # MT940, souscriptions webhook
    ├── Webhooks.php         # Vérification et parsing
    └── Account.php          # Infos du compte

```

L'authentification est gérée automatiquement par `HttpClient` :

- **Legacy API** (Basic Auth) — utilisée par Orders, Transactions, Sources
- **New API** (Bearer OAuth2) — utilisée par Wallets, BankAccounts, NativeCheckout, DataServices, Account

Le token OAuth2 est mis en cache en mémoire et rafraîchi automatiquement avant expiration.

---

Enums
-----

[](#enums)

### `Environment`

[](#environment)

```
use QrCommunication\VivaMerchant\Enums\Environment;

$env = Environment::DEMO;
$env = Environment::PRODUCTION;
$env = Environment::from('demo');

$env->value;         // 'demo'
$env->apiUrl();      // 'https://demo-api.vivapayments.com'
$env->legacyUrl();   // 'https://demo.vivapayments.com'
$env->checkoutUrl(); // 'https://demo.vivapayments.com/web/checkout'
$env->accountsUrl(); // 'https://demo-accounts.vivapayments.com'
```

### `Currency`

[](#currency)

```
use QrCommunication\VivaMerchant\Enums\Currency;

Currency::EUR->value;     // 978
Currency::EUR->iso();     // 'EUR'
Currency::fromIso('GBP'); // Currency::GBP (826)
```

Devises supportées : EUR (978), GBP (826), USD (840), PLN (985), RON (946), BGN (975), CZK (203), HRK (191), HUF (348), DKK (208), SEK (752), NOK (578).

### `TransactionStatus`

[](#transactionstatus)

```
use QrCommunication\VivaMerchant\Enums\TransactionStatus;

$status = TransactionStatus::from('F');
$status->isSuccessful();  // true
$status->isPending();     // false
$status->isFailed();      // false
$status->label();         // 'Finalized'
```

ValeurConstante`isSuccessful()``isPending()``isFailed()``F``FINALIZED`oui`A``PENDING`oui`C``CLEARING`oui`E``ERROR`oui`M``MANUALLY_REVERSED`oui`X``REQUIRES_ACTION``R``REFUNDED`---

Gestion d'erreurs
-----------------

[](#gestion-derreurs)

Toutes les exceptions héritent de `VivaException` qui étend `RuntimeException`.

```
RuntimeException
└── VivaException
    ├── ApiException
    ├── AuthenticationException
    └── ValidationException

```

```
use QrCommunication\VivaMerchant\Exceptions\ApiException;
use QrCommunication\VivaMerchant\Exceptions\AuthenticationException;
use QrCommunication\VivaMerchant\Exceptions\ValidationException;
use QrCommunication\VivaMerchant\Exceptions\VivaException;

try {
    $order = $viva->orders->create(amount: 1500);
} catch (AuthenticationException $e) {
    // Identifiants invalides — httpStatus = 401
    echo $e->getMessage();
} catch (ValidationException $e) {
    // Erreur de validation — httpStatus = 422
    foreach ($e->errors as $field => $messages) {
        echo "$field: " . implode(', ', $messages);
    }
} catch (ApiException $e) {
    // Erreur API générale — 400, 404, 500, etc.
    echo $e->httpStatus;
    echo $e->getErrorCode();
    echo $e->getErrorText();
    print_r($e->responseBody);
} catch (VivaException $e) {
    // Toute autre erreur SDK
}
```

### Propriétés et méthodes de `VivaException`

[](#propriétés-et-méthodes-de-vivaexception)

MembreTypeDescription`$httpStatus``int`Code HTTP de la réponse`$responseBody``?array`Corps JSON décodé de la réponse`getErrorCode()``?int`Code d'erreur Viva (`ErrorCode`)`getErrorText()``?string`Message d'erreur Viva (`ErrorText`, `message`, ou `detail`)---

Webhooks — Guide d'intégration
------------------------------

[](#webhooks--guide-dintégration)

### 1. Configurer le webhook dans le Dashboard Viva

[](#1-configurer-le-webhook-dans-le-dashboard-viva)

1. Aller dans **Settings > API Access > Webhooks**
2. Ajouter l'URL de votre endpoint
3. Noter la **clé de vérification**

### 2. Gérer la vérification (GET)

[](#2-gérer-la-vérification-get)

```
// Route GET /webhooks/viva
public function verify()
{
    return response()->json(
        $viva->webhooks->verificationResponse('votre-clé')
    );
}
```

### 3. Recevoir les événements (POST)

[](#3-recevoir-les-événements-post)

```
// Route POST /webhooks/viva
public function handle(Request $request)
{
    $event = $viva->webhooks->parse($request->getContent());

    match ($event['event_type']) {
        'transaction.payment.created'   => $this->onPayment($event['event_data']),
        'transaction.refund.created'    => $this->onRefund($event['event_data']),
        'transaction.preauth.created'   => $this->onPreauth($event['event_data']),
        'transaction.preauth.completed' => $this->onCapture($event['event_data']),
        default => logger()->info('Webhook ignoré : ' . $event['event_type']),
    };

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

---

Carte de test
-------------

[](#carte-de-test)

Pour l'environnement `demo` :

ChampValeurNuméro de carte`4111 1111 1111 1111`ExpirationToute date futureCVV`111`3DSPas de 3DS en demo---

Documentation interactive
-------------------------

[](#documentation-interactive)

La documentation interactive (ReDoc) est disponible en ligne :

****

Elle détaille chaque classe, méthode, paramètre et type de retour du SDK.

---

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 9 resources, 34+ méthodes, enums, exceptions 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 de 25 EUR pour une consultation"
$order = $viva->orders->create(
    amount: 2500,
    customerDescription: 'Consultation',
);
```

---

Licence
-------

[](#licence)

MIT — [QrCommunication](https://qrcommunication.com)

###  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

Maturity53

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

11

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 (12 commits)")

---

Tags

sdkpaymentmerchantvivaVivaWallet

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Type Coverage Yes

### Embed Badge

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

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

###  Alternatives

[lokielse/omnipay-unionpay

UnionPay gateway for Omnipay payment processing library

11358.1k2](/packages/lokielse-omnipay-unionpay)[sebdesign/laravel-viva-payments

A Laravel package for integrating the Viva Payments gateway

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

Cryptonator.com Merchant API SDK for PHP

2713.7k](/packages/cryptonator-merchant-php-sdk)

PHPackages © 2026

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