English

Authorising Transactions

After creating transaction, it has to be authorised by a user and confirmed by the client to take effect. Authorising (reserving funds) can be accomplished these ways:

  1. Using active allowance, without user intervention. This allowance must be accepted beforehand in some other way and confirmed by the client;
  2. Redirecting user to transaction confirmation page in Paysera system;
  3. Sending FLASH SMS to the user;
  4. Sending user's PIN code.

Errors

Following errors can be returned for any of authorisation requests.

- if current client made too many requests (or invalid requests) in some period of time

- There is not enough funds in the account

- Transaction limits are exceeded for current user in the account

- Temporally restriction limits are exceeded for current user in the account. User should contact support.

- User has no rights to make transfers from the account

- Payment is made to the same account

- Transaction has some restrictions for the payer and they were violated

- Payer for this transaction must be verified

- Beneficiary account is inactive and thus cannot accept payments

- Payer account is inactive and thus cannot make payments

- Your account is restricted, you are not allowed to make any transactions until restriction is removed

Getting available ways to reserve funds for transaction

This method returns available ways for specified wallet so you can choose the best one for your needs.

Requesting available types by wallet ID

GET https://wallet.paysera.com/rest/v1/transaction/:transaction_key/type/:wallet

Parameters

transaction_key - transaction_key assigned to transaction. Can be get from creation response of transaction or some other object

wallet - id of the wallet. Can be integer or me (if access token is used)

Response data structure

Response is array of strings. Each string represent one of available types to accept transaction. Possible values: automatic, flash, page, pin, reservation_code, mobile_app.

Example request

GET /rest/v1/transaction/pDAlAZ3z/type/14471 HTTP/1.1
Host: wallet.paysera.com
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="NVx9pHklDyMMGpdvq7d7eOysIrj/I4keloYVfGGqe8s="

Example response

HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
[
    "flash",
    "page"
]

Reserving money by using active allowance

This way uses active allowance to accept transaction made of payments. Transaction cannot have an included allowance.
Important You have to confirm the transaction even if reserving money for transaction by API. Without confirming the transaction, money will be reserved but payment will not be made
Warning If you reserve transaction by using allowance, you will never get a callback - callbacks are only fired when an event was not initiated by your application: changed by the user, after timeout etc.

Requesting automatic reservation by wallet ID

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

Parameters

transaction_key - transaction_key assigned to transaction. Can be get from creation response of transaction or some other object

wallet - id of the wallet. Can be integer or me (if access token is used). You can get ID with callback or using OAuth

Request body structure

Request body is optional in this request.
Parameter
Type
Remarks
Description
revoke_transactions
array of string
optional
Keys of transactions to revoke when making transaction reservation. Either reservation is made and all given transactions are revoked, or no action is performed

Response data structure

Transaction with status reserved is returned on success. See get transaction information response data structure for more information.

Errors

no_active_allowance (status code 400), allowance_exceeded (status code 400)

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 request with request content

PUT /rest/v1/transaction/pDAlAZ3z/reserve/14471 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="dL1bDhqNmERP8hHATToLX2SCjZd58FUof1bghcknW+E=", ext="body_hash=t6yKQ2LGX%2FgYKzrOuLcUTcASxp4O8%2F99BRddVGWIR00%3D"
{
    "revoke_transactions": [
        "qYYahw221",
        "u6aWQka972"
    ]
}
Info In this example we are reserving price of transaction which transaction_key is pDAlAZ3z in the wallet which ID is 14471. We also revoke transactions with keys qYYahw221 and u6aWQka972.

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
}

Redirecting user to transaction page

When using this way, user is redirected to Paysera system. If she is not logged in, credentials are asked. After logging in, user sees information about transaction and can accept or reject.

Ways to redirect user

There are several ways to redirect user to confirmation page:

show confirmation page in an iframe - this way lets embed confirmation process into your own page. This way cannot be used if user has to log in into Paysera system. Therefore it is recommended to use provided Javascript library for embedding confirmation process into your page - it takes care of selecting the best possible solution

show confirmation page in pop-up window - you can open pop-up window with confirmation page. This way can be used even if user has to log in into Paysera system. It is still recommended to use provided Javascript library for opening the window

redirect user to the confirmation page - this way user leaves your site and comes back only after confirming or canceling the request. You can use this way as an alternative to those users who has no Javascript support. You should provide redirect_uri when creating the transaction if using this confirmation way. If not provided, user will see notice and will not be redirected anywhere after confirming or rejecting the transaction.

Confirmation page URI

In English

https://www.paysera.com/frontend/en/wallet/confirm/:transaction_key

In Lithuanian

https://www.paysera.com/frontend/wallet/confirm/:transaction_key

In Russian

https://www.paysera.com/frontend/ru/wallet/confirm/:transaction_key

Sending FLASH SMS

This way uses FLASH SMS sent to user's phone. This way requires that user would have been confirmed her phone number. This method is available only to specific projects, it is disabled by default.

Sending FLASH SMS by wallet ID

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

Parameters

transaction_key - transaction_key assigned to transaction. Can be get from creation response of transaction or some other object

wallet - id of the wallet. Can be integer or me (if access token is used)

Response data structure

Changed transaction is returned. See get transaction information response data structure for more information.

Errors

phone_not_confirmed (status code 400) unsupported_grant_type (status code 400, if current client cannot accept transactions using FLASH SMS), phone_not_confirmed (status code 400)

Transaction parameters

If use_allowance is true to current transaction, active allowance will be checked before sending FLASH SMS confirmation to the user. If current transaction does not exceed the allowance, it will be automatically accepted. Response will be the same as if requested reservation using active allowance.

Example request

PUT /rest/v1/transaction/pDAlAZ3z/flash/14471 HTTP/1.1
Host: wallet.paysera.com
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="/CrRUc54dvx36cD5awZk1EvAeZQ3f4frEJ/1k4GL8Pk="
Info In this example we are sending FLASH SMS with transaction which transaction_key is pDAlAZ3z to the user of 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": "waiting",
    "type": "flash",
    "wallet": 14471,
    "valid_for_payment_card_debit": false,
    "correlation_key": "RG5A",
    "project_id": 2248,
    "payments": [
        {
            "id": 2988,
            "transaction_key": "pDAlAZ3z",
            "created_at": 1355314332,
            "status": "confirmed",
            "price": 1299,
            "currency": "EUR",
            "price_decimal": "12.99",
            "wallet": 14471,
            "freeze": {
                "until": 1357992732
            },
            "description": "Payment for order No. 1234",
            "parameters": {
                "orderid": 1234
            }
        }
    ],
    "use_allowance": false,
    "suggest_allowance": false,
    "auto_confirm": false
}
Warning Be sure to check status before getting the correlation_key - if there is an active allowance for this wallet, transaction will be automatically accepted, so status will be reserved, type will be automatic and correlation_key will be missing

Reserving money by sending user's PIN code

This way uses user's PIN code to accept transaction. This method is not recommended and should not be used if other ways are available. This method is enabled only for specific projects, it's not available by default.

Requesting reservation by wallet ID and PIN

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

Parameters

transaction_key - transaction_key assigned to transaction. Can be get from creation response of transaction or some other object

wallet - id of the wallet. Can be integer or me (if access token is used)

Request body structure

Parameter
Type
Remarks
Description
pin
string
required
User's PIN code
Info URL and HTTP method here is the same as when accepting transaction by using active allowance. The only difference is that request body is provided.

Response data structure

Transaction with status reserved is returned on success. See get transaction information response data structure for more information.
Important You have to confirm the transaction even if reserving money for transaction by API. Without confirming the transaction, money will be reserved but payment will not be made
Warning If you reserve transaction in this way, you will never get a callback - callbacks are only fired when an event was not initiated by your application: changed by the user, after timeout etc.

Errors

invalid_code (status code 400, if PIN code is incorrect), user_error_limit_exceeded (status code 400, if this user is blocked due to too many PIN errors), unsupported_grant_type (status code 400, if current client cannot accept transactions using PIN code)

Example request

PUT /rest/v1/transaction/pDAlAZ3z/reserve/14471 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="Mr03RniLli+nJuuo+Fnn0Ovgprx5aKvxfeiTUAiuy5w=", ext="body_hash=83tPM5QX61IkqTth23KfazXa5C4B%2F6lQy5mKv8uSV6o%3D"
{
    "pin": "0000"
}
Info In this example we are reserving price of transaction which transaction_key is pDAlAZ3z in the wallet which ID is 14471 providing user's PIN code 0000.

Example response

HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
{
    "transaction_key": "pDAlAZ3z",
    "created_at": 1355314332,
    "status": "reserved",
    "type": "pin",
    "wallet": 14471,
    "valid_for_payment_card_debit": false,
    "project_id": 2248,
    "payments": [
        {
            "id": 2988,
            "transaction_key": "pDAlAZ3z",
            "created_at": 1355314332,
            "status": "reserved",
            "price": "12.99",
            "currency": "EUR",
            "wallet": 14471,
            "freeze": {
                "until": 1357992732
            },
            "description": "Payment for order No. 1234",
            "parameters": {
                "orderid": 1234
            },
            "transfer_id": 578842
        }
    ],
    "reserve": {
        "until": 1355400732
    },
    "use_allowance": false,
    "suggest_allowance": false,
    "auto_confirm": false
}

Reserving money by sending reservation code

This way uses generated one-time valid reservation code to accept transaction. This code is usually provided by the user as QR code or barcode with some additional formatting.

Requesting reservation by wallet ID and reservation code

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

Parameters

transaction_key - transaction_key assigned to transaction. Can be get from creation response of transaction or some other object

Request body structure

Parameter
Type
Remarks
Description
reservation_code
string
required
Reservation code
payment_prices
object
optional
Prices of the payments for which price_rules element was passed. Keys of this object are payment IDs, values are selected price in cents for each payment. Selected price is in the currency of that particular payment.
Info Wallet ID is not required in this method as it is encoded in the reservation code itself

Response data structure

Transaction with status reserved is usually returned on success. See get transaction information response data structure for more information. Other possible statuses might be waiting_registration and waiting_password.
Important You have to confirm the transaction even if reserving money for transaction by API. Without confirming the transaction, money will be reserved but payment will not be made
Warning If you reserve transaction in this way, you will never get a callback - callbacks are only fired when an event was not initiated by your application: changed by the user, after timeout etc.

Errors

invalid_code - if reservation code is incorrect; user should re-initiate generator in her phone

code_expired - if reservation code has expired; user should just generate new code, re-initiation is not needed

code_restriction_violation - if reservation code has some restriction, which does not allow to accept this transaction; usually this happens because maximum transaction amount is encoded into reservation code

unsupported_grant_type - if current client cannot accept transactions using reservation code

invalid_state - if there is some invalid state in system, i.e. invalid amount or currency, code not supported, etc. More specific description will be provided ir error message.

Example request

PUT /rest/v1/transaction/pDAlAZ3z/reserve 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="po+pbHX1/6fS3Nu+9FBQRiKVcIoOimmyOAodpQrzrlg=", ext="body_hash=mZdnmoXri89S9PtTqZYHygI3JvJ%2BGpWmLmu%2BjpVF%2FfM%3D"
{
    "reservation_code": "0154742514278165942184409277"
}
Warning Even if reservation code consists only from digits, it must be sent as a string

Example request with payment prices

PUT /rest/v1/transaction/pDAlAZ3z/reserve 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="FukFlm84OA/Ube9qMUO2AyohB5LS5KgdvV2BE3xTWHc=", ext="body_hash=53zuCVOmL7KOWSkBoVVvP03v0U5PegVliVoj7JaVMvs%3D"
{
    "reservation_code": "0154742514278165942184409277",
    "payment_prices": {
        "2992": 80
    }
}

Example response

HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
{
    "transaction_key": "pDAlAZ3z",
    "created_at": 1355314332,
    "status": "reserved",
    "type": "reservation_code",
    "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
        },
        {
            "id": 2992,
            "transaction_key": "pDAlAZ3z",
            "created_at": 1355314332,
            "status": "reserved",
            "price": 80,
            "currency": "EUR",
            "price_decimal": "0.80",
            "price_rules": {
                "min": 0
            },
            "wallet": 14471,
            "freeze": {
                "until": 1357992732
            },
            "description": "Tips for payment",
            "transfer_id": 578842,
            "purpose": "tips"
        }
    ],
    "reserve": {
        "until": 1357992732
    },
    "use_allowance": false,
    "suggest_allowance": false,
    "auto_confirm": false
}

Reservation code as QR code

Reservation code is usually provided as QR code. QR code contents are composed of two parts:

  • PAYSERA$ - prefix in ASCII symbols;
  • reservation code in ASCII symbols.

Example QR code is provided on the right (with inactive reservation code, but formatted correctly). reservation_code, which would be needed to sent in this case, is 0154742514278159924687548051.

Reservation code as barcode

Reservation code can also be provided as Code128 barcode. Barcode contents are composed of two parts:

  • 9999 - prefix in ASCII symbols;
  • reservation code in ASCII symbols.

Example barcode is provided on the right (with inactive reservation code, but formatted correctly). reservation_code, which would be needed to sent in this case, is 0154742514278159925679172111.