Viva Wallet Merchant SDK

create()

Créer un ordre de paiement.

Retourne : array{order_code: int, checkout_url: string}

$order = $viva->orders->create(
    amount:              1500,          // 15,00 EUR
    customerDescription: 'Consultation',
    merchantReference:   'session_123',
    allowRecurring:      true,
    preauth:             false,
    maxInstallments:     3,
);

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

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

get(int $orderCode): array

Récupérer le statut d'un ordre.

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

cancel(int $orderCode): array

Annuler un ordre non payé.

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

checkoutUrl(int $orderCode): string

Générer l'URL de checkout à partir d'un code de commande existant. Aucun appel API — calcul local.

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

get(string $transactionId): array

Détails complets via Legacy API (Basic Auth). Retourne des clés PascalCase incluant frais, commission, infos carte.

$txn = $viva->transactions->get('transaction-uuid');

echo $txn['Transactions'][0]['Amount'];   // en centimes
echo $txn['Transactions'][0]['StatusId']; // 'F', 'A', 'C', etc.
echo $txn['Transactions'][0]['Fee'];
echo $txn['Transactions'][0]['CreditCard']['Number']; // masqué

getV2(string $transactionId): array

Détails allégés via New API (Bearer OAuth). Clés camelCase. Recommandé pour vérifier les paiements Smart Checkout.

$txn = $viva->transactions->getV2('transaction-uuid');

echo $txn['email'];              // email acheteur
echo $txn['amount'];             // en EUR (pas en centimes)
echo $txn['statusId'];           // 'F' = finalisée
echo $txn['orderCode'];          // code de commande
echo $txn['cardNumber'];         // numéro masqué
echo $txn['currencyCode'];       // ex: 978 (EUR)
echo $txn['recurringSupport'];   // true si tokenisée

listByDate(string $date): array

Lister les transactions pour une date (format Y-m-d).

Retourne : array<int, array<string, mixed>>

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

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

cancel(string $transactionId, ?int $amount = null, ?string $sourceCode = null): array

Annuler ou rembourser une transaction. Même jour = annulation (void). Jour passé = remboursement (refund).

Retourne : array{TransactionId: string}

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

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

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

capture(string $transactionId, int $amount): array

Capturer une pré-autorisation. Lève ApiException si la capture échoue.

$result = $viva->transactions->capture(
    transactionId: 'preauth-uuid',
    amount:        1500, // 15,00 EUR
);

recurring(string $initialTransactionId, int $amount, ?string $sourceCode = null): array

Effectuer une charge récurrente sur une carte tokenisée. Prérequis : l'ordre initial doit avoir été créé avec allowRecurring: true.

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

list(): array

Lister toutes les sources de paiement du compte.

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

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

create(string $name, string $sourceCode, ?string $domain, ?string $pathSuccess, ?string $pathFail): array

Créer une nouvelle source de paiement.

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

list(): array

Lister les portefeuilles du compte (Legacy API /api/wallets, Basic Auth).

Retourne : list<array{Iban, WalletId, IsPrimary, Amount, Available, Overdraft, FriendlyName, CurrencyCode}>

$wallets = $viva->wallets->list();
foreach ($wallets as $w) {
    echo $w['Iban'] . ' — Available: ' . $w['Available'] . ' ' . $w['CurrencyCode'] . PHP_EOL;
}
// GR7205700000005273617183734 — Available: 17.89 978
// GR7205700000004781377813871 — Available: 0 978

⚠️ CurrencyCode est en ISO 4217 numérique en string ("978" = EUR, "840" = USD, "826" = GBP). Convertir côté application si besoin.

balance(): array

Solde agrégé de tous les portefeuilles (itère list() et somme).

Retourne : array{available: float, pending: float, reserved: float, currency: string}

$balance = $viva->wallets->balance();
echo $balance['available'];  // 17.89 (somme des Available)
echo $balance['pending'];    // 0.00
echo $balance['reserved'];   // 0.00
echo $balance['currency'];   // '978' (ISO numérique brut — convertir si besoin)

💡 Pour le total ledger (Available + Pending + Reserved + Overdraft), itérer list() et sommer le champ Amount.

transfer(int $amount, string $sourceWalletId, string $targetWalletId, ?string $description = null): array

Transfert entre deux portefeuilles du même compte. Prérequis : activer « Allow transfers between accounts » dans Settings > API Access.

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

listDetailed(): array

Liste enrichie avec IBAN, SWIFT, solde et indicateur de portefeuille principal.

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

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

create(string $friendlyName, string $currencyCode = 'EUR'): array

Créer un nouveau portefeuille.

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

update(int $walletId, string $friendlyName): array

Renommer un portefeuille existant.

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

searchTransactions(array $params): array

Rechercher les transactions d'un portefeuille sur une plage de dates.

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

getTransaction(string $transactionId): array

Détails d'une transaction de compte (wallet transaction).

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

link(string $iban, string $beneficiaryName, ?string $friendlyName = null): array

Lier un IBAN externe au compte Viva Wallet.

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

echo $result['bankAccountId']; // UUID du compte lié
echo $result['isVivaIban'];    // false (IBAN externe)

transferOptions(string $bankAccountId): array

Récupérer les options de transfert disponibles pour un compte lié.

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

feeCommand(string $bankAccountId, int $amount, string $walletId, bool $isInstant = false, string $instructionType = 'SHA'): array

Calculer les frais avant d'exécuter un virement. Le bankCommandId retourné doit être passé à send().

$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(string $bankAccountId, int $amount, string $walletId, ?string $bankCommandId = null, ?string $description = null): array

Exécuter un virement SEPA vers un compte lié.

$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(): array

Lister les comptes bancaires liés au compte.

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

get(string $bankAccountId): array

Détails d'un compte bancaire lié.

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

createChargeToken()

Générer un token de charge à partir des données Apple Pay ou Google Pay.

Retourne : array{chargeToken: string, redirectToACSForm: ?string}

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

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

createTransaction()

Finaliser la transaction à partir du token de charge.

Retourne : array{transactionId: string, statusId: string, amount: int, orderCode: int}

$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 commande

mt940(string $date): array

Récupérer le rapport MT940 pour une date donnée (format Y-m-d).

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

createSubscription(string $url, string $eventType): array

Créer une souscription webhook pour recevoir les notifications de fichiers.

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

updateSubscription(string $subscriptionId, ?string $url, ?string $eventType): array

Mettre à jour une souscription existante (null = conserver la valeur actuelle).

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

deleteSubscription(string $subscriptionId): void

Supprimer une souscription webhook.

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

listSubscriptions(): array

Lister toutes les souscriptions webhook actives.

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

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

requestFile(string $date): void

Déclencher la génération asynchrone d'un fichier pour une date donnée. Utilisez une souscription webhook pour être notifié de la disponibilité du fichier.

$viva->dataServices->requestFile('2026-03-18');
// Génération asynchrone — attendre le webhook 'sale.transactions.file'

verificationResponse(string $verificationKey): array

Répondre à la requête GET de vérification initiale de Viva Wallet.

Retourne : array{StatusCode: int, Key: string}

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

parse(string $rawBody): array

Parser le payload JSON d'un webhook POST. Lève \InvalidArgumentException si le JSON est invalide.

Retourne : array{event_type: string, event_type_id: int, event_data: array}

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

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

    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']);
}

isKnownEvent(int $eventTypeId): bool

Vérifier si un ID d'événement est reconnu par le SDK.

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

eventTypeIds(): array

Retourner la liste de tous les IDs d'événements connus.

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

info(): array

Informations générales du compte marchand.

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

wallets(): array

Portefeuilles associés au compte marchand.

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