English

Callbacks

After some events that was not initiated by the client there can be a callback with the data about the event.

Callback is a request from our servers to client's server. This way data about event is passed to callback_uri, defined in project configuration in Paysera system or provided when creating a transaction.

Possible events are these:

transaction accepted, but registration of beneficiary is pending - raised when transaction is accepted by the user and money for transaction is reserved, but one or more beneficiaries are still not registered on the system

transaction reserved - raised when transaction is accepted by the user and money for transaction is reserved. All beneficiaries are registered and transaction can proceed

transaction confirmed - raised when transaction is reserved (see above) and auto-confirmed (only when auto_confirm option is set on transaction). In this case callback about reservation is not sent

transaction rejected - raised when transaction is rejected by the user

transaction failed - raised when transaction fails due to some other reason

Info Callbacks are made only for transactions, not payments - each payment always has it's transaction
Info If client does not have accessible URI from remote server, client can get all information directly from API. In this case client should check transaction status when user makes some action in your application or check for it periodically. Be aware that API requests can be limited to client, so status cannot be checked too often. It's best to always use callbacks if available
Warning If client reserves transaction by using allowance, callback will not be sent - callbacks are only fired when an event was not initiated by the client: changed by the user, after timeout etc. Similarly client will get callback about transaction confirmation only if it was confirmed automatically, not by using API.

Callback structure

Our servers make POST request to callback_uri in your server. Parameters are encoded in application/x-www-form-urlencoded format which is automatically parsed in the most of programming languages.

Callback parameters

Parameter
Type
Remarks
Description
event
string
always
Information about the event. Information is encoded in application/json format, like all responses from API
sign
string
always
Sign of data parameter using PPK scheme and encoded in base64 format. See verifying sign for more information

Event parameter structure

Parameter
Type
Remarks
Description
type
string
always
Type of the event. One of: rejected, failed, reserved, confirmed, waiting_funds, waiting_registration, waiting_password
object
string
always
Type of the object in the event. In the current API version this parameter is always transaction
data
object
always
Transaction object that was confirmed of canceled. Structure is the same as when getting transaction information
Warning Client should always check if object parameter is as expected - code will be compatible with future versions of API

Verifying sign

Sign is calculated using this formula: 
sign = base64_encode(RSA(event, d, n))

RSA is public key algorithm, using sha256 encoding.

Most of cryptographic libraries give a way to check if some data was encrypted with RSA algorithm by giving a public key. Reverse action is practically not possible - private key is needed for that. Checking algorithm:
ok = verify, that base64_decode(sign) is the result when event is signed with publicKey

For example, in PHP language sign can be checked with this code: 
// get $webToPayPublicKey
$ok = openssl_verify($_POST['event'], base64_decode($_POST['sign']), $webToPayPublicKey, 'sha256');
if ($ok) {
    $event = json_decode($_POST['event']);
    // ...
}
Public key used in sign verifying is provided by Paysera system and is publicly accessible by this URI: 
https://wallet.paysera.com/publickey
Info You are recommended to use provided libraries that takes care of verifying sign if one is available in your programming language

Response status codes

Server must return status code 200 (or any other 2xx) if the callback has been successfully processed and any other status code if not - in that case callback will be repeated after some time. Server should not provide redirect status codes (3xx).

Keep in mind, that transaction is canceled or confirmed no matter what callback status code is - there might even not be any callback.

Examples

Transaction rejected callback example

POST /your_provided_callback_uri HTTP/1.1
Host: example.com

event=%7B%22type%22%3A%22rejected%22%2C%22object%22%3A%22transaction%22%2C%22data%22%3A%7B%22transaction_key%22%3A%22pDAlAZ3z%22%2C%22created_at%22%3A1355314332%2C%22status%22%3A%22rejected%22%2C%22type%22%3A%22page%22%2C%22wallet%22%3A14471%2C%22project_id%22%3A2248%2C%22payments%22%3A%5B%7B%22id%22%3A2988%2C%22transaction_key%22%3A%22pDAlAZ3z%22%2C%22created_at%22%3A1355314332%2C%22status%22%3A%22canceled%22%2C%22price%22%3A1299%2C%22currency%22%3A%22EUR%22%2C%22price_decimal%22%3A%2212.99%22%2C%22wallet%22%3A14471%2C%22description%22%3A%22Payment+for+order+No.+1234%22%2C%22parameters%22%3A%7B%22orderid%22%3A1234%7D%2C%22transfer_id%22%3A578842%7D%5D%7D%7D&sign=f75rkX5qrvS3i9%2frQraUKPZOIW4MOXuFyy0yVMYc2SHoRFABko23oDBeCagGI9V9RUmeE6s5PMHLZ%2fYQJtePAkEA%2f0DCozbYbz%2bxlGwhg7kHvH0LqCB6sITxfzMaFQbT8EGmloj4wIkgvEImgBTyJ3xIZulcDwFpT9qApIKmcCm3Q%3d%3d
event contents (urldecoded and formatted): 
{
    "type": "rejected",
    "object": "transaction",
    "data": {
        "transaction_key": "pDAlAZ3z",
        "created_at": 1355314332,
        "status": "rejected",
        "type": "page",
        "wallet": 14471,
        "project_id": 2248,
        "payments": [
            {
                "id": 2988,
                "transaction_key": "pDAlAZ3z",
                "created_at": 1355314332,
                "status": "canceled",
                "price": 1299,
                "currency": "EUR",
                "wallet": 14471,
                "price_decimal": "12.99",
                "description": "Payment for order No. 1234",
                "parameters": {
                    "orderid": 1234
                },
                "transfer_id": 578842
            }
        ]
    }
}

Transaction reserved callback example

POST /your_provided_callback_uri HTTP/1.1
Host: example.com

event=%7B%22type%22%3A%22reserved%22%2C%22object%22%3A%22transaction%22%2C%22data%22%3A%7B%22transaction_key%22%3A%22pDAlAZ3z%22%2C%22created_at%22%3A1355314332%2C%22status%22%3A%22reserved%22%2C%22type%22%3A%22page%22%2C%22wallet%22%3A14471%2C%22project_id%22%3A2248%2C%22payments%22%3A%5B%7B%22id%22%3A2988%2C%22transaction_key%22%3A%22pDAlAZ3z%22%2C%22created_at%22%3A1355314332%2C%22status%22%3A%22reserved%22%2C%22price%22%3A1299%2C%22currency%22%3A%22EUR%22%2C%22price_decimal%22%3A%2212.99%22%2C%22wallet%22%3A14471%2C%22freeze%22%3A%7B%22until%22%3A1357992732%7D%2C%22description%22%3A%22Payment+for+order+No.+1234%22%2C%22parameters%22%3A%7B%22orderid%22%3A1234%7D%2C%22transfer_id%22%3A578842%7D%5D%7D%7D&sign=f75rkX5qrvS3i9%2frQraUKPZOIW4MOXuFyy0yVMYc2SHoRFABko23oDBeCagGI9V9RUmeE6s5PMHLZ%2fYQJtePAkEA%2f0DCozbYbz%2bxlGwhg7kHvH0LqCB6sITxfzMaFQbT8EGmloj4wIkgvEImgBTyJ3xIZulcDwFpT9qApIKmcCm3Q%3d%3d
event contents (urldecoded and formatted): 
{
    "type": "reserved",
    "object": "transaction",
    "data": {
        "transaction_key": "pDAlAZ3z",
        "created_at": 1355314332,
        "status": "reserved",
        "type": "page",
        "wallet": 14471,
        "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
            }
        ]
    }
}