stadem/viva-payments

Viva Payment package for PHP 8

v1.0.6 2024-09-10 19:45 UTC

Requires

• php: ^8.2.0

Requires (Dev)

• pestphp/pest: ^2.34
• phpstan/phpstan: ^1.11
• phpunit/phpunit: ^10.5
• symfony/var-dumper: ^6.4

MIT

• Stavros Dem

README

This package provides a streamlined interface for the Viva Wallet Payment API, enabling seamless integration with Smart Checkout, Webhooks, and support for both API v1 and API v2 calls.

Features

• Smart Checkout Integration: Easily integrate Viva Wallet's Smart Checkout into your application.
• Webhooks: Handle Viva Wallet webhooks with minimal setup.
• API v1 & v2 Support: Compatible with both versions of the Viva Wallet API.
• Lightweight & Minimal Dependencies: Designed to be easy to install and use without unnecessary bloat.

Installation

Install the package through Composer.

This package requires PHP 8.2 + and no other dependencies.

composer require stadem/viva-payments

Configuration

Rename viva-config.php.example to viva-config.php and add your credentials.

Add the following data on your viva-config.php.

And for you local environment

    'vivaDEMO' => [
        'VIVA_URL' => 'https://demo.vivapayments.com',
        'VIVA_ACCOUNT_URL' => 'https://demo-accounts.vivapayments.com',
        'VIVA_API_URL' => 'https://demo-api.vivapayments.com',
        'VIVA_API_KEY' => '',
        'VIVA_MERCHANT_ID' => '',
        'VIVA_SOURCE_CODE' => '',
        'VIVA_CLIENT_ID' => '',
        'VIVA_CLIENT_SECRET' => '',
        'VIVA_SMARTCHECKOUT_COLOR'=>'0d1bbd',
        'VIVA_DEBUG'=>0,
    ],

And for you production

'vivaPROD' => [
    'VIVA_URL' => 'https://www.vivapayments.com',
    'VIVA_ACCOUNT_URL' => 'https://accounts.vivapayments.com',
    'VIVA_API_URL' => 'https://api.vivapayments.com',
    'VIVA_API_KEY' => '',
    'VIVA_MERCHANT_ID' => '',
    'VIVA_SOURCE_CODE' => '',
    'VIVA_CLIENT_ID' => '',
    'VIVA_CLIENT_SECRET' => '',
    'VIVA_DEBUG'=>0,
],

The total file config.php

return [
    'curlDebug' => 0,
    'defaultProvider' => 'vivaDEMO',
    'vivaDEMO' => [
        'VIVA_URL' => 'https://demo.vivapayments.com',
        'VIVA_ACCOUNT_URL' => 'https://demo-accounts.vivapayments.com',
        'VIVA_API_URL' => 'https://demo-api.vivapayments.com',
        'VIVA_API_KEY' => 'a4bw%t%^',
        'VIVA_MERCHANT_ID' => '123456', 
        'VIVA_SOURCE_CODE' => '2222',
        'VIVA_CLIENT_ID' => '123456.vivapayments.com',
        'VIVA_CLIENT_SECRET' => '123456',
        'VIVA_BANK_TRANSFER_URL_API' => 'https://demo.vivapayments.com/api/wallets/{{platformAccountId}}/commands/banktransfer/{{vendorAccountId}}',
        'VIVA_WALLET_TO_WALLET_URL_API'=>'https://demo.vivapayments.com/api/wallets/{{platformAccountId}}/balancetransfer/{{vendorAccountId}}',
        'VIVA_SMARTCHECKOUT_COLOR'=>'0d1bbd',
        'VIVA_DEBUG'=>0,
    ],

    'vivaPROD' => [
        'VIVA_URL' => 'https://www.vivapayments.com',
        'VIVA_ACCOUNT_URL' => 'https://accounts.vivapayments.com',
        'VIVA_API_URL' => 'https://api.vivapayments.com',
        'VIVA_API_KEY' => '',
        'VIVA_MERCHANT_ID' => '',
        'VIVA_SOURCE_CODE' => '',
        'VIVA_CLIENT_ID' => '',
        'VIVA_CLIENT_SECRET' => '',
        'VIVA_DEBUG'=>0
    ]
];

Read more about API authentication on the Developer Portal: https://developer.vivawallet.com/getting-started/find-your-account-credentials/client-smart-checkout-credentials/

Usage

Full example

require_once __DIR__ . '/../vendor/autoload.php';
use Stadem\VivaPayments\Enums;
use Stadem\VivaPayments\Services\AccessToken;
use Stadem\VivaPayments\Request\Customer;
use Stadem\VivaPayments\Request\CreatePaymentOrder;

$requestLang = $_REQUEST['requestLang'] ?? 'Greek';

 $config = new Config();
 $accessToken = new AccessToken($config);


$customer = new Customer(
    $email = '[e-mail]',
    $fullName = 'Customer name',
    $phone = '[phone]',
    $countryCode = 'GR',
    $requestLang = Enums\RequestLang::fromName($requestLang),
);


$CreatePaymentOrder  = [
    'amount'                => 120, 
    'customerTrns'          => 'Test POST - No End Payment', items/services being purchased.
    'paymentTimeout'        => 1800, 
    'preauth'               => false, 
    'allowRecurring'        => false, 
    'maxInstallments'       => 0, 
    'forceMaxInstallments'  => false, 
    'paymentNotification'   => true, 
    'tipAmount'             => 0, 
    'disableExactAmount'    => false, 
    'disableCash'           => true, 
    'disableWallet'         => false, 
    'cardTokens'            => null, Tokens tutorial.
    'merchantTrns'          => 'This is a short description that helps you uniquely identify the transaction', 
    'tags'                  => ['tag1', 'tag2'] 
];


$paymentMethods = [0, 8, 21, 29, 34, 35];


$paymentMethodFees  =  [
    'paymentMethodId' => '35',
    'fee' => 550
];


try {
   	$order = new CreatePaymentOrder($CreatePaymentOrder, $accessToken,$config);
    $order->setCustomer($customer);
    $order->setPaymentMethods($paymentMethods);
    $order->setPaymentMethodsFees($paymentMethodFees);

    $getOrderJson = $order->send();
    echo '<a href="' . $order->redirectUrl(PaymentMethods: Enums\PaymentMethods::fromName('VivaWallet')) . '" target="blank">';
    echo $order->getOrderCode();
    echo '</a>';
} catch (Exception  $e) {
    echo 'An error occured: <b>' . $e->getMessage() . '</b>';
}

Get the Access Token

Here’s a quick example of how to get started:

To interact with the Viva Wallet API, you'll first need to obtain an access token. Here’s a quick example of how to get started:

'vivaPROD' => [ Create a file and add the following code, you can switch from the vivaDEMO to vivaProd evn.

require_once __DIR__ . '/../vendor/autoload.php';
use Stadem\VivaPayments\Enums;
use Stadem\VivaPayments\Services\AccessToken;
use Stadem\VivaPayments\Request\Customer;
use Stadem\VivaPayments\Request\CreatePaymentOrder;
use Stadem\VivaPayments\Config\Config;

$config = new Config();
$accessToken = new AccessToken(); // Set the value on config file -> defaultProvider
or
$config = new Config();
$accessToken = new AccessToken(environment: 'vivaDEMO'); // By direct set, mostly for testing purposes 

Additionaly you can access to token and status code by using

$Token = $accessToken->getAccessToken();
$statusCode = $accessToken->getStatusCode();
dump($Token.'-'.$statusCode);

Create new customer

$customer = new Customer(
    $email = '[e-mail]',
    $fullName = 'Customer name',
    $phone = '[phone]',
    $countryCode = 'GR',
    $requestLang = Enums\RequestLang::fromName('Greek'),
);

You can set the requestLang with multiple ways by type or value. For further details refer to src\VivaPayments\Enums\RequestLang

 RequestLang::Greek
 RequestLang::from('el-GR') // by value
 RequestLang::fromName('Greek') // by name

Create Payment order

$CreatePaymentOrder  = [
    'amount'                => 120, 
    'customerTrns'          => 'Test POST - No End Payment',
    'paymentTimeout'        => 1800, 
    'preauth'               => false, 
    'allowRecurring'        => false, 
    'maxInstallments'       => 0, 
    'forceMaxInstallments'  => false, 
    'paymentNotification'   => true, 
    'tipAmount'             => 0, 
    'disableExactAmount'    => false, 
    'disableCash'           => true, 
    'disableWallet'         => false, 
    'cardTokens'            => null, Tokens tutorial.
    'merchantTrns'          => 'This is a short description that helps you uniquely identify the transaction', 
    'tags'                  => ['tag1', 'tag2'] 
];

	$order = new CreatePaymentOrder($CreatePaymentOrder, $accessToken,$config);

amount
The amount associated with this payment order *100. Must be a positive, non-zero number
customerTrns
This optional parameter adds a friendly description to the payment order that you want to display to the customer on the payment form. It should be a short description of the
paymentTimeout
By using this parameter, you can define a different life span for the Payment Order in sec
preauth
This will hold the selected amount as unavailable (without the customer being charged) for a period of time
allowRecurring
If this parameter is set to true, recurring payments are enabled so that the initial transaction ID can be used for subsequent payments. https://developer.viva.com/tutorials/payments/create-a-recurring-payment/
maxInstallments
The maximum number of installments that the customer can choose for this transaction
forceMaxInstallments
If this parameter is set to true, the customer will be forced to pay with installments and with the specific number indicated in maxInstallments parameter
paymentNotification
If you wish to create a payment order, and then send out an email to the customer to request payment
tipAmount
The tip value (if Applicable for the customer's purchase) which is already included in the amount of the payment order and marked as tip
disableExactAmount
If this parameter is set to true, then any amount specified in the payment order is ignored (although still mandatory), and the customer is asked to indicate the amount they will pay
disableCash \ If this parameter is set to true, the customer will not have the option to pay in cash at a Viva Spot
disableWallet
If this parameter is set to true, the customer will not have the option to pay using their Viva personal account (wallet)
cardTokens
You can provide the card tokens you have saved on your backend for this customer. The card tokens will then be presented to the customer on Smart Checkout to pay with. For details, view our Handle Card
merchantTrns
This can be either an ID or a short description that helps you uniquely identify the transaction in the viva banking App
tags
You can add several tags to a transaction that will help in grouping and filtering in the viva banking App

Create the payment order

The amount requested in cents is required. All the other parameters are optional. Check out the request body schema.

try {
    $order = new CreatePaymentOrder($CreatePaymentOrder, $accessToken,$config);
    $order->setCustomer($customer);
    $order->setPaymentMethods($paymentMethods);
    $order->setPaymentMethodsFees($paymentMethodFees);
    $order->send();
    $redirectUrl = $order->redirectUrl();
} catch (Exception  $e) {
    echo 'An error occured: <b>' . $e->getMessage() . '</b>';
}

Run tests via PEST & PHP STAN

You can run tests via PEST with the following command

 ./vendor/bin/pest tests/Payments

 ./vendor/bin/phpstan analyse src

Upcoming Features

Marketplace API Support: Future updates will include support for marketplace-related API calls.

Documentation

For comprehensive documentation, please visit the Viva Wallet Developer Portal.

Contributing

Contributions are welcome! Please submit a pull request or open an issue to discuss potential changes.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Disclaimer

Note: This is an unofficial package, and its usage is at your own discretion.