English

Making Payments

This specification chapter describes how to use Wallet API to initiate and control payment transactions.

When making payments, default client credentials are enough, no integration with OAuth framework is required.

Resources, available in API and related to payments:

Wallet - Wallet is always related to some user and some account. Each user can have one or more wallets, each of them can have different limits, options etc. Wallet can be related to some card or other identifier, so it's possible for user to have few wallets, related to same account.

Payment - Payment from some wallet to some other wallet. In case of collecting payments, beneficiary is the wallet, related to the project. In case of sending or coordinating payments, beneficiary is a wallet owned by some Paysera user. If beneficiary ID is known in advance, it can be provided, if not - beneficiary's email address or phone number is available as beneficiary information. If there is user registered with such contact information, notification will be sent with registration instructions. Payment can be made up from several Items or can contain only price information - this is only for displaying purposes.

Allowance - Allowance lets client charge a wallet without user interaction as long as payments do not exceed the limits provided when creating an allowance. There may be only one active allowance for client and wallet combination at any time. If user accepts allowance with some limits, it is not necessary to accept with all other payments until allowance limits are reached or it's time limit has expired.

Transaction - Every payment and allowance is assigned to exactly one transaction. Transactions can have one or several payments and optionally an allowance (or just an allowance). The whole transaction is whether accepted or rejected by the user - this helps to group related payments into one object.

Transaction status flow

Every transaction follows these steps until it's completed:
  1. Transaction is created by client. Information is saved in Paysera system, no money is transferred or reserved.
  2. Transaction is accepted by user, relating it to specific wallet. This step can be done in different ways: redirecting user to confirmation page, asking user's PIN and providing it with API call etc. Transaction can be accepted beforehand by using allowance. This way this step can be done by the client without user intervention - by calling API method.
    After this step, funds are reserved in the payer's account, but payments are still not visible to beneficiary.
  3. Transaction is confirmed or revoked by the client. This step is needed for several reasons:
    • By confirming transaction, client shows, that it's system is still running and it can provide services for the user;
    • Transaction can be revoked if service can be no longer provided (for example, payment time has expired, items are not available anymore etc.)
    • Sum of payments can be changed before reaching beneficiary - in confirmation API method, reserved amounts can be reduced.
    Transaction must be confirmed until specific time (reserveUntil, controlled by the client), if this time is reached, reserved funds for payments are returned to the payer.
    After this step, payments are visible for beneficiary. If freezeUntil is provided for payment, funds are still seen as reserved for payer and also appears as reserved for beneficiary. In other case, payment is done completely.
    If necessary, confirmation step can be made automatically if auto_confirm parameter is set to true when creating transaction. This can be used if client can be offline when reservation is made, usually if no service is provided (transfer between users, charity etc.) This is generally not recommended.
  4. Optionally, each payment in transaction can be finalized or cancelled. This is only available for payments with freezeUntil provided. They can be canceled up to this time. When finalizing payment, it is also possible to reduce payment's amount. When the time is reached, payment is automatically finalized.

Transaction statuses and their flow is provided in the diagram bellow.

Info Blue arrows indicate state changes initiated by using API
Info done and canceled statuses are available only for payments. Up to these states, all payments in the same transaction has the same status as the transaction itself

More detailed diagram between waiting and related statuses is provided bellow.

Sections in this chapter