Paysera - API documentation

Paysera offers a secure API that lets you perform cash-in to your customers with their generated cash-in code.

Integration

1. Scan customer generated cash in code.

Scan your customer generated cash in code and extract customer walletId from it. walletId is padded with 0 to the left side to the total of 12 characters. For example, wallet ID is 1 from EVP000000000001.

2. Perform a background payment.

In order to complete cash-in you need to perform background payment using an allowance.

Info Paysera will provide an allowance, you do not need to create one.

Background payment with a library

Create a file that will make background payment.

Create file pay-with-allowance.php in the paysera-wallet folder. the process is similar to Create a payment, just difference is that client (developed system) doesn't need to wait for user confirmation as created allowance will be added to transaction. The sample code which makes background payment with allowance:

<?php

if (!class_exists('Paysera_WalletApi_Autoloader')) {
    require_once 'lib-wallet-php-client-master/src/Paysera/WalletApi/Autoloader.php';
}

Paysera_WalletApi_Autoloader::register();

// $clientId - mac
$clientId = 'wkVd93h2uS';
// $secret - mac_key
$secret = 'IrdTc8uQodU7PRpLzzLTW6wqZAO6tAMU';

$api = new Paysera_WalletApi($clientId, $secret, Paysera_WalletApi_Util_Router::createForSandbox());

try {
    $price = Paysera_WalletApi_Entity_Money::create()
        ->setAmountInCents(100)
        ->setCurrency('EUR')
    ;

    $item = Paysera_WalletApi_Entity_Item::create()
        ->setTitle('Item')
        ->setDescription('Item in sale')
        ->setImageUri('https://developers.paysera.com/bundles/evpfrontpage/img/logo.png')
        ->setPrice($price)
        ->setQuantity(2)
    ;

    $fullPrice = Paysera_WalletApi_Entity_Money::create()
        ->setAmountInCents(200)
        ->setCurrency('EUR')
    ;

    $payment = Paysera_WalletApi_Entity_Payment::create()
        ->addItem($item)
        ->setPrice($fullPrice)
        ->setDescription('In Sale')
    ;

    // if commission is needed
    $commissionPrice = Paysera_WalletApi_Entity_Money::create()
        ->setAmountInCents(100)
        ->setCurrency('EUR')
    ;
    $commission = Paysera_WalletApi_Entity_Commission::create()
        ->setOutCommission($commissionPrice)
    ;
    $payment = $payment
        ->setCommission($commission)
    ;

    $allowanceTransaction = $api->walletClient()->getTransaction('[ALLOWANCE_TRANSACTION_KEY]');

    $transaction = Paysera_WalletApi_Entity_Transaction::create()
        ->addPayment($payment)
        ->setAllowance($allowanceTransaction->getAllowance())
    ;

    $transactionCreated = $api->walletClient()->createTransaction($transaction);

    $api->walletClient()->acceptTransactionUsingAllowance(
        $transactionCreated->getKey(),
        $allowanceTransaction->getWallet()
    );

    // ToDo: some actions with transaction

    $api->walletClient()->confirmTransaction($transactionCreated->getKey());
} catch (Exception $e) {
    echo '<pre>', $e, '<pre>';
}

Background payment with the specification

1. Create transaction.

Transaction groups one or more objects into one confirmable group. To confirm any created object, there must be a transaction.

Info Default transaction is created together with payment and allowance to be confirmed without creating it manually.

Moreover, transactions take part in all-or-nothing scenarios: either all of grouped payments are done successfully, or all fail. For example, if wallet has sufficient account balance only for one of grouped payments, user will be unable to confirm this transaction.
Transactions are also good when making shop carts with payments to different beneficiaries - user will have to confirm something just once.

Warning Transactions group payments only when confirming. If payment is canceled, other payments in the same transaction remain unchanged.

This method creates transaction that groups payment(s) and/or allowance into item that can be confirmed. More info about transaction creation: Transaction resource.

POST https://wallet.paysera.com/rest/v1/transaction

Example request for creating payment and assigning optional allowance

POST /rest/v1/transaction HTTP/1.1
Host: wallet.paysera.com
Content-Type: application/json;charset=utf-8
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="R5Kw+qeaej/TRdVEkxbKzJHeHfA7HbsEcI4StcJo3lU=", ext="body_hash=gK8kVbYW1XEeZUf4BR1yZ45YLu%2BEYnq1WOGYtRhxyQA%3D"

{
    "payments": [
        {
            "description": "Payment for order No. 1234",
            "price": 1299,
            "currency": "EUR",
            "parameters": {
                "orderid": 1234
            }
        }
    ],
    "allowance": {
        "id": 784,
        "optional": true
    },
    "redirect_uri": "http://www.example.com/somePage"
}

Example response

HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8

{
    "transaction_key": "pDAlAZ3z",
    "created_at": 1355314332,
    "status": "new",
    "project_id": 2248,
    "valid_for_payment_card_debit": false,
    "payments": [
        {
            "id": 2988,
            "transaction_key": "pDAlAZ3z",
            "created_at": 1355314332,
            "status": "new",
            "price": 1299,
            "currency": "EUR",
            "price_decimal": "12.99",
            "description": "Payment for order No. 1234",
            "parameters": {
                "orderid": 1234
            }
        }
    ],
    "allowance": {
        "optional": true,
        "data": {
            "id": 784,
            "transaction_key": "pDAlAZ3z",
            "created_at": 1355314332,
            "status": "new",
            "description": "Allowance for weekly services (5 weeks)",
            "currency": "EUR",
            "max_price": 1500,
            "max_price_decimal": "15.00",
            "limits": [
                {
                    "max_price": 300,
                    "max_price_decimal": "3.00",
                    "time": 604800
                }
            ]
        }
    },
    "reserve": {
        "until": 1355400732
    },
    "use_allowance": false,
    "suggest_allowance": false,
    "auto_confirm": false,
    "redirect_uri": "http://www.example.com/somePage"
}

2. Authorise transaction.

After creating transaction, it has to be authorised by a user and confirmed by the client (developed system) to take effect. Authorising (reserving funds) can be accomplished using active allowance, without user intervention. This allowance must be accepted beforehand in some other way and confirmed by the client (developed system).

More info about authorising transaction: Authorising transactions (reserving funds).

Transaction cannot have an included allowance. Allowance must be accepted beforehand in some other way and confirmed by the client (developed system). More info about allowance: Allowance resource.

PUT https://wallet.paysera.com/rest/v1/transaction/:transaction_key/reserve/:wallet

Example request

PUT /rest/v1/transaction/pDAlAZ3z/reserve/14471 HTTP/1.1
Host: wallet.paysera.com
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="hKC//dWjcCRuPwlXVlDyo6tdzlRbRy/CCNLRfbvzvDw="

Info In this example we are reserving price of transaction which transaction_key is pDAlAZ3z in the wallet which ID is 14471.

Example response

HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8

{
    "transaction_key": "pDAlAZ3z",
    "created_at": 1355314332,
    "status": "reserved",
    "type": "automatic",
    "wallet": 14471,
    "valid_for_payment_card_debit": false,
    "project_id": 2248,
    "payments": [
        {
            "id": 2988,
            "transaction_key": "pDAlAZ3z",
            "created_at": 1355314332,
            "status": "reserved",
            "price": 1299,
            "currency": "EUR",
            "price_decimal": "12.99",
            "wallet": 14471,
            "freeze": {
                "until": 1357992732
            },
            "description": "Payment for order No. 1234",
            "parameters": {
                "orderid": 1234
            },
            "transfer_id": 578842
        }
    ],
    "reserve": {
        "until": 1357992732
    },
    "use_allowance": false,
    "suggest_allowance": false,
    "auto_confirm": false
}

3. Confirm transaction.

When transaction status is reserved, you can confirm or revoke the transaction.

PUT https://wallet.paysera.com/rest/v1/transaction/:transaction_key/confirm

Confirmed transaction is returned on success. See get transaction information response data structure for more information.

Example request

PUT /rest/v1/transaction/pDAlAZ3z/confirm HTTP/1.1
Host: wallet.paysera.com
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="ZQYIS0L4Uq40te+qxNXJzWHNO6Ff7qhnEDuwduFlqRI="

Example response

HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8

{
    "transaction_key": "pDAlAZ3z",
    "created_at": 1355314332,
    "status": "confirmed",
    "type": "page",
    "wallet": 14471,
    "valid_for_payment_card_debit": false,
    "confirmed_at": 1355314392,
    "project_id": 2248,
    "payments": [
        {
            "id": 2988,
            "transaction_key": "pDAlAZ3z",
            "created_at": 1355314332,
            "status": "confirmed",
            "price": 1299,
            "currency": "EUR",
            "price_decimal": "12.99",
            "wallet": 14471,
            "confirmed_at": 1355314392,
            "freeze": {
                "until": 1357992732
            },
            "description": "Payment for order No. 1234",
            "parameters": {
                "orderid": 1234
            }
        }
    ],
    "allowance": {
        "optional": true,
        "data": {
            "id": 784,
            "transaction_key": "pDAlAZ3z",
            "created_at": 1355314332,
            "status": "active",
            "currency": "EUR",
            "wallet": 14471,
            "confirmed_at": 1355314392,
            "valid": {
                "until": 1357992732
            },
            "description": "Allowance for weekly services (5 weeks)",
            "max_price": 1500,
            "max_price_decimal": "15.00",
            "limits": [
                {
                    "max_price": 300,
                    "max_price_decimal": "3.00",
                    "time": 604800
                }
            ]
        }
    }
}

Cash-in with code

Integration

1. Scan customer generated cash in code.

2. Perform a background payment.

Background payment with a library

Create a file that will make background payment.

Background payment with the specification

1. Create transaction.

Example request for creating payment and assigning optional allowance

Example response

2. Authorise transaction.

Example request

Example response

3. Confirm transaction.

Example request

Example response