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
Only if it was provided when creating the allowance
Deprecated. It's used parameter valid with subparameter for instead.
Same as provided when creating the allowance
description
string
Only if it was provided when creating the allowance
Same as provided when creating the allowance
max_price
integer
Only if it was provided when creating the allowance
Same as provided when creating the allowance
max_price_decimal
string
Only if it was provided when creating the allowance
Same as provided when creating the allowance
limits
array of objects
Only if it was provided when creating the allowance
Same as provided when creating the allowance

Example request by allowance ID

GET /rest/v1/allowance/10145 HTTP/1.1
Host: wallet.paysera.com
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="7mZKPJyMUEJMilO0+u9IV+5MO6vQGuO33Tc2/1UpYY0="
Info In this example we are requesting information about allowance which ID is 10145

Example request by wallet ID

GET /rest/v1/allowance/active/14471 HTTP/1.1
Host: wallet.paysera.com
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="XFatXQZv7Pz68Gp6FzTF54nR5XyWuPHa+9ojiDarw4s="
Info In this example we are requesting information about active allowance related to wallet which ID is 14471

Example response

HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
{
    "id": 10145,
    "transaction_key": "pDAlAZ3z",
    "created_at": 1355314332,
    "status": "active",
    "currency": "EUR",
    "wallet": 14471,
    "confirmed_at": 1355314392,
    "valid": {
        "until": 1357992732
    },
    "description": "Allowance for some services",
    "max_price": 1500,
    "max_price_decimal": "15.00",
    "limits": [
        {
            "max_price": 100,
            "max_price_decimal": "1.00",
            "time": 86400
        },
        {
            "max_price": 300,
            "max_price_decimal": "3.00",
            "time": 604800
        }
    ]
}
Info See more response examples in create allowance method

Get maximum price for active allowance

This method returns maximum price that can be reserved using active allowance for specified wallet (see Reserving money by using active allowance). Allowance max price, allowance limits, user's balance, user's account limits and other factors are included when calculating maximum limit for an allowance.

Requesting active allowance limit by a wallet

GET https://wallet.paysera.com/rest/v1/allowance/limit/:wallet?currency=:currency

Parameters

wallet
id of the wallet. Can be integer or me (if access token is used)
currency
currency code for limit. If not provided, EUR is taken as default. Limits can vary depending on currency as there might be different account balance for each currency in the wallet

Response data structure

Parameter
Type
Remarks
Description
amount
integer
always
Amount in cents of maximum available limit to reserve automatically using active allowance in this wallet
currency
string
always
Same as provided in the request or EUR if it was not provided
amount_decimal
string
always
Decimal amount of maximum available limit to reserve automatically using active allowance in this wallet

Example request

GET /rest/v1/allowance/limit/14471?currency=USD HTTP/1.1
Host: wallet.paysera.com
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="bD/T1UHs3wBUhk/NpkdMiUgm+p9VWp5M3yTwMNuaw+Y="
Info In this example we are requesting maximum limit for USD currency to be reserved using active allowance in wallet which ID is 14471

Example response

HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
{
    "amount": 1920,
    "amount_decimal": "19.20",
    "currency": "USD"
}
Info This response means, that 19.20 USD can be reserved using active allowance for this wallet

Cancel allowance

This method cancels active allowance. Status of allowance must be active to cancel it.
Info Canceling allowance has no significant result for the user - client can just choose not to make any payments.
Info Client doesn't have to cancel allowance before creating the new one - it will get canceled when the new one will be confirmed.

Request to cancel allowance by ID

DELETE 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

Request to cancel active allowance by a wallet

DELETE 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)

Response data structure

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

Example request by allowance ID

DELETE /rest/v1/allowance/10145 HTTP/1.1
Host: wallet.paysera.com
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="OTQVEDLrbtyFiuUe+/AVcXByiqbNtOji2dHmpqAGfOE="
Info In this example we are canceling allowance which ID is 10145

Example response if the allowance has not been confirmed yet

HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
{
    "id": 10145,
    "transaction_key": "pDAlAZ3z",
    "created_at": 1355314332,
    "status": "inactive",
    "currency": "EUR",
    "description": "Allowance for some services",
    "max_price": 1500,
    "max_price_decimal": "15.00"
}

Example request by wallet ID

DELETE /rest/v1/allowance/active/1012 HTTP/1 HTTP/1.1
Host: wallet.paysera.com
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="IAPDW5iFnig+nROUxS03LopiUwYCia6an/pIkzIpoYc="
Info In this example we are canceling active allowance related to wallet which ID is 1012

Example response

HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
{
    "id": 10145,
    "transaction_key": "pDAlAZ3z",
    "created_at": 1355314332,
    "status": "inactive",
    "currency": "EUR",
    "wallet": 1012,
    "confirmed_at": 1355314392,
    "description": "Allowance for some services",
    "max_price": 1500,
    "max_price_decimal": "15.00"
}