Allowance resource

About

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

About

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 is not provided Total maximum 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, 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 Maximum amount in cents 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="1343822400", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="JhfX/LyydJN8+K+S3gU3CpMcF/H+7Je0Qqvx7bKghV8=", 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
}

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="1343822400", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="2JKGFpCuWA2+nGpI6FHFYBceKEp8igkP7ubXWM/o+xA=", 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,
    "limits": [
        {
            "max_price": 300,
            "time": 604800
        }
    ]
}

Get allowance information

About

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
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="1343822400", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="3CyVOnh9/ot6GQoMk/SzqywjTuc2YBm7ZCM9Lmxgdqw="
InfoIn 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="1343822400", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="wUhRa1EPtDMz3VFONh5k/HkQPSG3cemBtNIkseLlbAk="
InfoIn 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,
    "limits": [
        {
            "max_price": 100,
            "time": 86400
        },
        {
            "max_price": 300,
            "time": 604800
        }
    ]
}
InfoSee more response examples in create allowance method

Get maximum price for active allowance

About

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

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="1343822400", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="QSvzqvNCBGRVpTtXjHlNt8eP/KigStnazkI7acruPKk="
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,
    "currency": "USD"
}
InfoThis response means, that 19.20 USD can be reserved using active allowance for this wallet

Cancel allowance

About

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="1343822400", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="x1qKGiJFDYQhZv6ErlZpOd8bE3R9lDH7sIBg3WQBsWI="
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
}

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="1343822400", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="WuhAF7fiMO2XQ1/9SRvDXEVduBRhgwiPsAoylTIeBMU="
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
}