Paysera - API documentation

Allowance is a permission to make payments without asking the user herself. It allows to make small payments from wallet very quickly and smoothly, after she has confirmed client-initiated allowance or created one by herself.

Warning Creating an allowance does not guarantee that payment will be successfuly made without user intervention. For example, there may be insufficient account balance in that wallet.

Important Only one allowance can be active for a wallet at a time. If client creates new one and it gets confirmed, the active one will get canceled.

Create allowance

This method creates allowance in Paysera system. After creating allowance, user should be redirected to confirmation page or allowance should be confirmed in other ways.

Info Creating a new allowance does not affect the active one - it is canceled only when (if) the new one is confirmed

Warning Allowances with status new are deleted automatically 1 month after creation time.

Request

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

Request body structure

Parameter

Type

Remarks

Description

description

string

optional

Description about allowance to user - what is it to be used for

currency

string

required

Currency in which all money amounts in this allowance are provided

max_price

integer

required if limits and max_price_decimal is not provided,
unavailable if max_price_decimal is provided

Total maximum amount in cents that can be charged from wallet for this allowance. Amount is cumulative - when sum of prices of transactions, confirmed using this allowance, reaches max_price, this allowance is no longer valid.

max_price_decimal

string

required if limits and max_price is not provided,
unavailable if max_price is provided

Total maximum decimal amount that can be charged from wallet for this allowance. Amount is cumulative - when sum of prices of transactions, confirmed using this allowance, reaches max_price_decimal, this allowance is no longer valid.

valid

object

optional
It's used with one of parameter inside: for or until
unavailable if valid_for or valid_until is provided

It is used with one of additional parameters inside:
for - validity time in seconds. Time starts from allowance confirmation
until - allowance validity time in UNIX timestamp - allowance will be valid until that moment

valid_for

integer

optional, defaults to 720 (30 days)
unavailable if valid_until or valid is provided

Deprecated. Use parameter valid with subparameter for instead.
Validity period in hours. Time starts from allowance confirmation

valid_until

integer

optional, unavailable if valid_for or valid is provided

Deprecated. Use parameter valid with subparameter until instead.
Allowance validity period in UNIX timestamp - allowance will be valid until that moment

limits

array of objects

required if max_price is not provided

Array of limits for this allowance

Warning valid, max_price and limits information has maximums that depend on client's Paysera service agreement

Limit data structure

Parameter

Type

Remarks

Description

max_price

integer

required if max_price_decimal is not provided,
unavailable if max_price_decimal is provided

Maximum amount in cents that can be charged from wallet in provided time

max_price_decimal

string

required if max_price is not provided,
unavailable if max_price is provided

Maximum decimal amount that that can be charged from wallet in provided time

time

integer

required, unless period specified

Time in seconds that this limit is valid for. Time has no start time - this is the limit that can be never exceeded in this time

period

integer

required, unless time specified

Deprecated. Use parameter time instead.
Period in hours that this limit is valid for. Time has no start time - this is the limit that can be never exceeded in this time

Info Each limit narrows the possible charging time and amount. If you create limit 1 Euro / 60 s there is no point adding 60 Euros / 3600 s, because first one is narrower than the second one.

Warning Maximum price of one payment can be no bigger than the limit's max_price in smallest time. If you create limit 1 Euro / 1 h, price of payment cannot be bigger than 1 Euro, otherwise it would exceed the limit (no matter what are the other limits in that allowance). This does not mean that you cannot have payments with bigger prices - you just have ask user to confirm the payment.

Response data structure

On success API returns allowance object that was created. See get allowance information for more info.

Errors

limit_violation (status code 400)

Example request for allowance without limits

POST /rest/v1/allowance 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="qHnDddnmudMi6FwQeWeINW2zEGNJR6xFrbpWOdgggSI=", ext="body_hash=Y2nyrCCNhAqRbJu0UK8b57S%2BDim5jcyCsRQoz9My4j0%3D"

{
    "description": "Allowance for weekly services (5 weeks)",
    "currency": "EUR",
    "max_price": 1500,
    "valid": {
        "for": 3110400
    }
}

Info This allows us to charge wallet maximum sum of 15.00 Euros in 36 days. For example, this can be used for charging 3 Euros each week for 5 weeks.

Warning Allowance is invalid if payments for 15.00 Euros are confirmed or 36 days passes. You cannot confirm more than 15.00 Euros using this allowance neither at once in single payment, nor at different payments using smaller amounts.

Example response

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

{
    "id": 2987,
    "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"
}

Example request for payment with limits

POST /rest/v1/payment 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="iWJAzV+d/Rc8kNuhPkbiuIxxwWfXZYmWtytm1Y7v1kc=", ext="body_hash=EsNVsLM2KVDsRfhmYmaiHfVShSMS2%2Bvqn96D%2BaUzAcM%3D"

{
    "description": "Allowance for weekly services (5 weeks)",
    "currency": "EUR",
    "max_price": 1500,
    "valid": {
        "for": 3110400
    },
    "limits": [
        {
            "max_price": 300,
            "time": 604800
        }
    ]
}

Info This example does the same as the one above, but here we are adding 3.00 Euros / 1 week limit, so user knows, that we cannot charge 15.00 Euros immidiately.

Example response

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

{
    "id": 2987,
    "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
        }
    ]
}

Get allowance information

This method returns allowance information that was created earlier. Allowance information can change in time, because it contains status field.

Requesting allowance by ID

GET https://wallet.paysera.com/rest/v1/allowance/:id

Parameters

id - id of allowance. Can be requested by other API methods or get from allowance creation response

Requesting active allowance by a wallet

GET https://wallet.paysera.com/rest/v1/allowance/active/:wallet

Parameters

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

Info It is normal for wallet not to have an active allowance, so expect error with code not_found in that case

Response data structure

Parameter

Type

Remarks

Description

id

integer

always

ID of the allowance

transaction_key

string

always

See transaction for more information

created_at

integer

always

Date of allowance creation in UNIX timestamp

status

string

always

Status of allowance. One of: new, active, inactive, deleted

currency

string

always

Same as provided when creating the allowance

wallet

integer

Only if this allowance was already related with some wallet,
always if status is active

Wallet ID in Paysera system, to which allowance is related

confirmed_at

integer

Only if status is active or inactive

Date of allowance confirmation in UNIX timestamp

valid

object

optional
It's used with one of parameter inside: for or until

It is used with one of additional parameters inside:
for - Same as provided when creating the allowance
until - Date in UNIX timestamp until when the allowance is active

valid_until

integer

Only if status is active or it was provided when creating the allowance

Deprecated. It's used parameter valid with subparameter until instead.
Date in UNIX timestamp until when the allowance is active

valid_for

integer