Create payment

This method creates payment in Paysera system. After creating payment, user should be redirected to payment confirmation page or payment should be confirmed in other ways.
Warning Payments with status new are deleted automatically 1 month after creation time.

Request

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

Request body structure

Parameter
Type
Remarks
Description
description
string
required if items is not provided
Description about payment - what services or items are bougth
price
integer
required if items and price_decimal is not provided or if commission is used without price_decimal
unavailable if price_decimal is provided
Total price of whole payment in cents. If items with prices are provided and total price does not match this one, error is returned.

When using commission of type out_commission (or decimal), price should be set to the amount that needs to be paid + out_commission (or decimal) amount.
currency
string
required if items is not provided
Currency in which the price is provided
price_decimal
string
required if items and price is not provided or if commission is used without price
unavailable if price_decimal is provided
unavailable if price is provided
Total decimal price of whole payment. If items with prices are provided and total price does not match this one, error is returned

When using commission of type out_commission (or decimal), price_decimal should be set to the amount that needs to be paid + out_commission (or decimal) amount.
commission
object
optional
Commission to be added in case client want to include commission to payment
items
array of objects
required if description, price and currency are not provided
Items that are bougth with this payment. See data structure of each item bellow
beneficiary
object
optional
Beneficiary's identifier. If provided, payment will be made to the account of beneficiary, not you. This type of payment should be used only when you provide services to transfer money between your customers. See structure of beneficiary bellow
price_rules
object
optional
If provided, user can change the price of this payment by provided rules. currency must be also provided with this element. See data stucture of price rules below
password
object
optional
Password for this payment. If provided, beneficiary or some other party must give the password before transaction can be confirmed. Password is known to the payer, so usually she gives it to the beneficiary
freeze
object
optional
It's used with one of parameter inside: for or until
unavailable if freeze_for or freeze_until is provided
It is used with one of additional parameters inside:
for - freeze time in seconds. If provided, beneficiary will be unable to use received money until the freeze time comes to end. Freeze time starts from the moment payment is confirmed, not created
until - freeze time in UNIX timestamp. If provided, beneficiary will be unable to use received money until the moment specified by timestamp
freeze_for
integer
optional
unavailable if freeze_until or freeze is provided
Deprecated. Use parameter freeze with subparameter for instead.
Freeze period in hours. If provided, beneficiary will be unable to use received money until the freeze period comes to end. Freeze period starts from the moment payment is confirmed, not created
freeze_until
integer
optional
unavailable if freeze_for or freeze is provided
Deprecated. Use parameter freeze with subparameter until instead.
Freeze period in UNIX timestamp. If provided, beneficiary will be unable to use received money until the moment specified by timestamp
parameters
any
optional
Parameters about the item that is bought. Exactly those parameters will be returned in payment confirmation and can be get from API
cashback
integer
optional
Cashback amount. Cashback is always made after confirming the payment from the account, related with your project, back to the payer's account. currency must be set if cashback is provided.
purpose
string
optional
Purpose of this payment. One of the following: cash, tips.

Item data structure

Parameter
Type
Remarks
Description
title
string
required
description
string
optional
Description about the item
image_uri
string
optional
URI of an image to be shown with the item in payment confirmation page
price
integer
required if price_decimal is not provided,
unavailable if price_decimal is provided
Price of the item in cents
currency
string
required
Currency in which the price is provided
price_decimal
string
required if price is not provided,
unavailable if price is provided
Decimal price of the item
quantity
float
optional, if not provided 1 is used
Quantity of item that is bought. Final price is calculated as the product of quantity and price
total_price
integer
optional,
unavailable if total_price_decimal is provided
Final price of the items in cents. If not provided final price will be calculated as the product of quantity and price and price is rounded up to the next highest integer.
total_price_decimal
string
optional,
unavailable if total_price is provided
Final decimal price of the items. If not provided final price will be calculated as the product of quantity and price_decimal and price is rounded up to the next highest integer.
parameters
any
optional
Parameters about the item that is bought. Exactly those parameters will be returned in payment confirmation and can be get from API
Warning Currency of all items in the same payment must match. If you need to make multi-currency payment, make few separate payments in one transaction

Beneficiary data structure

Parameter
Type
Remarks
Description
id
integer
required if no other field is provided
unavailable if at least one other field is provided
Beneficiary ID in our system. You can get it by using OAuth or from previous transactions
email
string
required if no other field is provided
unavailable if at least one other field is provided
Beneficiary's email address
phone
string
required if no other field is provided
unavailable if at least one other field is provided
Beneficiary's phone number
barcode
string
required if no other field is provided
unavailable if at least one other field is provided
Beneficiary's special barcode number

If there is a user with a specified email address or phone number (it must be confirmed and related to the wallet), the payment will be made to this user. In other case, the user will receive a registration request to the specified email address or phone number, and only after relating the address or phone number with the wallet the payment will reach it's final state.

Transfer will fail if user is not registered and won't register until reserve, specified when creating the transaction (defaults to 86400 seconds from accepting the transaction).

Price rules data structure

Parameter
Type
Remarks
Description
min
integer
optional, unavailable if choices or min_decimal is provided
Minimum amount for this payment in cents. Defaults to 1 if max is provided
min_decimal
string
optional, unavailable if choices or min is provided
Minimum decimal amount for this payment.
max
integer
optional, unavailable if choices or max_decimal is provided
Maximum amount for this payment in cents
max_decimal
string
optional, unavailable if choices or max is provided
Maximum decimal amount for this payment.
choices
array of integer
optional, unavailable if min or max is provided
Available amounts for this payment

At least one element must be provided in price rules structure.

Default price for payment is provided in price element. This price must be valid in provided price rules context.

If min is 0, or choices contains 0, this payment is optional for the user, as she can select zero as the price. Transaction must always have at least one non-optional payment.

Important price element will contain user's selected price after reservation - as price can change after transaction creation, API client should always check price value if price_rules was passed.

Password data structure

Parameter
Type
Remarks
Description
type
string
required
Type of the password, one of: provided, generated
value
string
required if type is provided,
unavailable otherwise
The password for this payment. Usually given by the payer herself
status
string
unavailable, provided only in response
Status of the password. One of these: pending, unlocked

If type of the password is generated, email or SMS message will be sent to the payer with generated payment's password. If type is provided, user will not be notified about the password. In any case, passwords can be always seen in clear text when logged into Paysera account. They can be also get by API using special OAuth scope.

Info Payment passwords are case-insensitive

Commission data structure

Parameter
Type
Remarks
Description
out_commission
integer
required if out_commission_decimal is not provided,
unavailable if out_commission_decimal is provided
Price of the out commission in cents.

When using out_commission, the price (or decimal) parameter should be set to the total of price (or decimal) + out_commission
out_commission_decimal
string
required if out_commission is not provided,
unavailable if out_commission is provided
Decimal price of the out commission.

When using out_commission_decimal, the price (or decimal) parameter should be set to the total of price (or decimal) + out_commission_decimal
in_commission
integer
required if in_commission_decimal is not provided,
unavailable if in_commission_decimal is provided
Price of the in commission in cents
in_commission_decimal
string
required if in_commission is not provided,
unavailable if in_commission is provided
Decimal price of the out commission

Available payment purposes

One of these purposes can be specified for the payment:

cash - This value must be passed if this payment is as part of cash-related transaction, such as in cash-in or cash-out scenarios.

tips - This purpose is used when this particular payment is as tips for waiter etc. This allows to provide information for the user in predefined way for such scenarios. Payment with this purpose cannot have items element, as they will not be displayed.

Response data structure

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

Errors

beneficiary_not_found (status code 404, only if id was used), limit_violation (status code 400), invalid_parameters (status code 400, if email or phone is invalid).

Example request for payment with no items

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="Xk/+C/KOEapGtvaLjV6mKvk/0BfWydb/zlHFyoBx/Us=", ext="body_hash=esRCxyYPpkKwaNzTaj0wtFwLG6gNw%2FCHw%2FIz2j5vp7Q%3D"
{
    "description": "Payment for order No. 1234",
    "price": 1299,
    "currency": "EUR",
    "parameters": {
        "orderid": 1234
    }
}
Info Price of this payment is 12 Euros and 99 cents. You can add any data to parameters to relate the payment to your services.

Example response

HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
{
    "id": 2987,
    "transaction_key": "pDAlAZ3z",
    "created_at": 1355314332,
    "status": "new",
    "price": 1299,
    "currency": "EUR",
    "price_decimal": "12.99",
    "description": "Payment for order No. 1234",
    "parameters": {
        "orderid": 1234
    }
}

Example request for payment with items

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="ml1uu/M6mqlXnHYdFykYxZNhVWh4XXE3sTpCZnMGbUg=", ext="body_hash=ymFtrzhE7e5e1iei0gswRnXD0iStTaHrxMH7GyyxEf8%3D"
{
    "items": [
        {
            "title": "Cape",
            "description": "Nice new cape for your character",
            "image_uri": "http://www.sxc.hu/pic/m/m/mr/mr_basmt/935633_hero.jpg",
            "price": 199,
            "currency": "EUR",
            "parameters": {
                "itemid": 12,
                "color": "red"
            }
        },
        {
            "title": "Hat",
            "price": 49,
            "currency": "EUR",
            "quantity": 2,
            "parameters": {
                "itemid": 13,
                "some_other_params": [
                    1,
                    2
                ]
            }
        }
    ],
    "price": 297,
    "currency": "EUR",
    "parameters": {
        "userid": 222
    }
}
Info You can add parameters to each item and the payment itself
Warning Here payment price and currency are provided only for checking that the final price is as you expect it to be. They are optional when items are provided
Warning items parameter is always an array, even when you provide just one item

Example response

HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
{
    "id": 2987,
    "transaction_key": "pDAlAZ3z",
    "created_at": 1355314332,
    "status": "new",
    "price": 297,
    "currency": "EUR",
    "price_decimal": "2.97",
    "items": [
        {
            "title": "Cape",
            "description": "Nice new cape for your character",
            "image_uri": "http://www.sxc.hu/pic/m/m/mr/mr_basmt/935633_hero.jpg",
            "price": 199,
            "currency": "EUR",
            "price_decimal": "1.99",
            "parameters": {
                "itemid": 12,
                "color": "red"
            }
        },
        {
            "title": "Hat",
            "price": 49,
            "currency": "EUR",
            "price_decimal": "0.49",
            "quantity": 2,
            "parameters": {
                "itemid": 13,
                "some_other_params": [
                    1,
                    2
                ]
            }
        }
    ],
    "parameters": {
        "userid": 222
    }
}

Example request for payment with custom beneficiary

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="ocZOi7ePtfUQIJsi9F3okN8PopUm8PpmdRwpJJHLytw=", ext="body_hash=zk4d9ErjdUudTktKi1JUukMT22WkM%2FKmSwyuzWRpHK0%3D"
{
    "items": [
        {
            "title": "Some item sold between users",
            "price": 2000,
            "currency": "EUR",
            "quantity": 1,
            "parameters": {
                "itemid": 102
            }
        }
    ],
    "beneficiary": {
        "email": "email@example.com"
    },
    "freeze": {
        "for": 604800
    },
    "parameters": {
        "from_user": 1028,
        "to_user": 2154
    }
}
Info Freeze time in the example is one week (604800 seconds). This means that you can reject the payment that was already confirmed up to a week after it was made.

Example response

HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
{
    "id": 2987,
    "transaction_key": "pDAlAZ3z",
    "created_at": 1355314332,
    "status": "new",
    "price": 2000,
    "currency": "EUR",
    "price_decimal": "20.00",
    "items": [
        {
            "title": "Some item sold between users",
            "price": 2000,
            "currency": "EUR",
            "price_decimal": "20.00",
            "quantity": 1,
            "parameters": {
                "itemid": 102
            }
        }
    ],
    "beneficiary": {
        "id": 20,
        "email": "email@example.com"
    },
    "freeze": {
        "for": 604800
    },
    "parameters": {
        "from_user": 1028,
        "to_user": 2154
    }
}
Warning Freeze time starts with payment confirmation, so freeze with parameter until field is provided only when payment is confirmed (when status of payment is confirmed)
Info If beneficiary was found by phone or email, beneficiary object will also contain id element

Example request for payment with variable price

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="Goa6x4IWMJkN3qnL9HFdyQUKPDeKCVghxGBTCG5NAsQ=", ext="body_hash=2FQL4HY1R3Br0LfqEDimQCL5vlzrR70cSwmd7KFh5wY%3D"
{
    "description": "Payment for order No. 1234",
    "price": 1299,
    "currency": "EUR",
    "price_rules": {
        "min": 100
    }
}
Info Price for this payment can be changed by the user. Selected price will be 1.00 EUR or larger
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="ZWLEQixADQOTZgDa7QrzWs6wmh/8EvIeA01qtH9cYRA=", ext="body_hash=1ktVxvRq45EWbb5owOc0gnpib%2BoHDTtkL65%2FqcqJKq8%3D"
{
    "description": "Payment for order No. 1234",
    "price": 500,
    "currency": "EUR",
    "price_rules": {
        "choices": [
            100,
            200,
            500,
            1000
        ]
    }
}
Info Price for this payment can be changed by the user. Selected price will be 1.00 EUR, 2.00 EUR, 5.00 EUR or 10.00 EUR

Example request for payment with commission

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="MGE1UrY1nukCx98HOxuH0M0QMggrLNVEiqt2Upnfd0U=", ext="body_hash=4gWgSZ14DrAc5qIpaN7NWjd46YnlsTMHsBMa1shJ1Ao%3D"
{
    "description": "Payment for order No. 1234",
    "price": 1099,
    "currency": "EUR",
    "parameters": {
        "orderid": 1234
    },
    "commission": {
        "out_commission": 100
    }
}
Info Two types of commission are available to use: out_commission and in_commission

out_commission
  • When using out_commission, the price parameter should be set to the total amount that needs to be paid, i.e. price + out_commission.
  • The price of this payment is 9 EUR and 99 cents + 1 EUR out_commission = 10 EUR and 99 cents in total.
  • The payer will pay 10.99 EUR and the receiver will receive 9.99 EUR.
in_commission
  • For in_commission, the price does not change.
  • The in_commission will be taken from the receiver's account
  • If the price is 9.99 EUR and in_commission is 1 EUR, the payer will pay 9.99 EUR, but the receiver will receive 8.99 EUR
Which type of commission to use?
  • out_commission if the commission has to be paid by the payer.
  • in_commission if the commission has to be paid by the receiver.

Example response

HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
{
    "id": 2987,
    "transaction_key": "pDAlAZ3z",
    "created_at": 1355314332,
    "status": "new",
    "price": 1099,
    "currency": "EUR",
    "price_decimal": "10.99",
    "description": "Payment for order No. 1234",
    "parameters": {
        "orderid": 1234
    },
    "commission": {
        "out_commission_decimal": "1.00",
        "out_commission": 100
    }
}

Get payment information

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

Request

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

Parameters

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

Response data structure

Parameter
Type
Remarks
Description
id
integer
always
ID of the payment
transaction_key
string
always
See transaction for more information
created_at
integer
always
Date of payment creation in UNIX timestamp
status
string
always
Status of payment. One of: new, waiting, waiting_funds, waiting_registration, waiting_password, revoked, rejected, failed, reserved,confirmed, done, canceled, deleted
price
integer
always
Total price of payment in cents. If payment is not yet reserved, it's equal to price that was provided when creating the payment or the sum of all amounts in items of this payment. If payment is not yet done and price_rules was provided, this is user's selected price for this payment. If final price was provided when finalizing the payment, this is the final price of this payment
currency
string
always
Currency of the price of this payment.
price_decimal
string
always
Total decimal price of payment. If payment is not yet reserved, it's equal to price_decimal that was provided when creating the payment or the sum of all amounts in items of this payment. If payment is not yet done and price_rules was provided, this is user's selected price for this payment. If final price was provided when finalizing the payment, this is the final price of this payment
wallet
integer
Only if this payment was already related with some wallet,
always if status is reserved, confirmed, done or canceled
Wallet ID in Paysera system, by which payment was accepted or rejected
beneficiary
object
Only if it was provided when creating the payment
Same as provided when creating the payment. If email or phone identificator was used, can also contain id field if beneficiary is already resolved
price_rules
object
Only if it was provided when creating the payment
Same as provided when creating the payment
password
object
Only if it was provided when creating the payment
Type and status of the password for this payment
confirmed_at
integer
Only if status is confirmed, done or canceled
Date of payment confirmation in UNIX timestamp
freeze
object
optional
It's used with one of parameter inside: for or until
It is used with one of additional parameters inside:
for - freeze time in seconds. If provided, beneficiary will be unable to use received money until the freeze time comes to end. Freeze time starts from the moment payment is confirmed, not created
until - freeze time in UNIX timestamp. If provided, beneficiary will be unable to use received money until the moment specified by timestamp
freeze_until
integer
Only if status is confirmed or
it was provided when creating the payment
Deprecated. Use parameter freeze with subparameter until instead.
Date in UNIX timestamp until when the payment is frozen. After that time beneficiary (provided by beneficiary parameter or yourself in other case) can use the money
freeze_for
integer
Only if it was provided when creating the payment
Deprecated. Use parameter freeze with subparameter for instead.
Same as provided when creating the payment
description
string
Only if it was provided when creating the payment
Same as provided when creating the payment
items
array of objects
Only if it was provided when creating the payment
Same as provided when creating the payment
parameters
any
Only if it was provided when creating the payment
Same as provided when creating the payment
cashback
integer
Only if it was provided when creating the payment
Same as provided when creating the payment
transfer_id
integer
Only if available and only when status is one of reserved, confirmed, done, canceled
Transfer ID to relate payment with account statements
purpose
string
Only if it was provided when creating the payment
One of available purpose values, specifying purpose of this payment

Meaning of payment status codes

Status of payment is always the same as of it's transaction with one exception: if transaction is confirmed, payment can be confirmed, done or canceled.

This means that all payments in transaction have the same state up until the transaction is confirmed. After that, each payment separately can be canceled or become done.

confirmed - Payment is accepted by the user and confirmed by you. Both buyer and seller sees this payment, but the incoming funds of this payment is frozen for the seller

done - Payment is successfully made, money is no longer frozen

canceled - Payment was confirmed and canceled after that. Money has been returned to payer

See meaning of transaction status codes for more information.
Info Only payments with status new can change their current transaction

Example request

GET /rest/v1/payment/10145 HTTP/1.1
Host: wallet.paysera.com
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="/qxTA8FOgT0Dd0MHh9k/sUQ3Q38ckx8+S0PBxpIuttY="
Info In this example we are requesting information about payment which ID is 10145

Example response

HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
{
    "id": 10145,
    "transaction_key": "pDAlAZ3z",
    "created_at": 1355314332,
    "status": "confirmed",
    "price": 1299,
    "currency": "EUR",
    "price_decimal": "12.99",
    "wallet": 14471,
    "confirmed_at": 1355314392,
    "freeze": {
        "until": 1357992732
    },
    "items": [
        {
            "title": "Item",
            "price": 1499,
            "price_decimal": "14.99",
            "currency": "EUR"
        },
        {
            "title": "Other item",
            "price": 299,
            "price_decimal": "2.99",
            "quantity": 2,
            "currency": "EUR"
        }
    ],
    "transfer_id": 87745,
    "purpose": "cash"
}
Info freeze with subparameter until is the date until when the money is frozen. The money is frozen if payment is made to custom beneficiary or if your service agreement with Paysera system is set to freeze money for some amount of time
Info See more response examples in create payment method

Cancel payment

This method cancels already confirmed payment. status of the payment must be confirmed, that is, it must not be already done. After canceling payment, it's status is changed to canceled and money is returned to payer.

Request

DELETE https://wallet.paysera.com/rest/v1/payment/:id

Parameters

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

Response data structure

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

Errors

invalid_state if status of payment does not allow canceling it.

Example request

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

Example response

HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
{
    "id": 10145,
    "transaction_key": "pDAlAZ3z",
    "created_at": 1355314332,
    "status": "canceled",
    "price": 1499,
    "currency": "EUR",
    "price_decimal": "14.99",
    "wallet": 1012,
    "confirmed_at": 1355314392,
    "description": "payment B",
    "transfer_id": 578842
}
Info This response means that the payment was successfuly canceled and 14.99 Euros were returned to Paysera wallet which ID is 1012

Change freeze time

Freeze time can be changed only if the payment status is confirmed and freeze was provided when creating the payment. That is, if freeze time has been set and hasn't yet ended.

Request

PUT https://wallet.paysera.com/rest/v1/payment/:id/freeze

Parameters

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

Request body structure

Parameter
Type
Remarks
Description
freeze
object
required if freeze_for or freeze_until is not provided
It's used with one of parameter inside: for or until
unavailable if freeze_for or freeze is provided
It is used with one of additional parameters inside:
for - freeze time in seconds. If provided, beneficiary will be unable to use received money until the freeze time comes to end. Freeze time starts from the moment payment is confirmed, not created
until - freeze time in UNIX timestamp. If provided, beneficiary will be unable to use received money until the moment specified by timestamp
freeze_until
integer
required if freeze_for or freeze is not provided
unavailable if freeze_for or freeze is provided
Deprecated. Use parameter freeze with subparameter until instead.
Date in UNIX timestamp until when the freeze time should be set. Only dates in the future are accepted or value 0
freeze_for
integer
required if freeze_until or freeze is not provided is not provided
unavailable if freeze_until or freeze is provided
Deprecated. Use parameter freeze with subparameter for instead.
Period in hours for which freeze time should be extended
Info Set freeze parameter until to 0 if you want to unfreeze the money. You can also finalize payment to get the same result.

Response data structure

On success API returns corresponding payment object. See get payment information for more info.
Warning Payment can be left in the confirmed state if the money is still frozen
Warning freeze with subparameter until can be different than provided one. If your service agreement in Paysera system sets default freeze time, the maximum of calculated default freeze time and provided freeze with subparameter until is taken into account

Example request

PUT /rest/v1/payment/10145/freeze 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="ntzA+iY4wHWtKbITubjVY2p8/qy8uZMFooq4Ewda4QM=", ext="body_hash=8kaZahF2OEJXFX070ZE0q6BpDF3TzHfWHIWyyZoNZLc%3D"
{
    "freeze": {
        "until": 1357992732
    }
}
Info In this example we are extending (or just changing) freeze time of payment which ID is 10145

Example request to extend freeze time

PUT /rest/v1/payment/10145/freeze 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="Dcl8faZlyEvM2w3WPUBtXj7H2Fq4DZk/yY13dPVZMcQ=", ext="body_hash=1eDY9X1raQho8Klxshppa%2BiDX2ql2%2FVqZLMHOwdvYlA%3D"
{
    "freeze": {
        "for": 604800
    }
}
Info In this example we are extending freeze time of payment which ID is 10145 for 1 week

Example response

HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
{
    "id": 10145,
    "transaction_key": "pDAlAZ3z",
    "created_at": 1355314332,
    "status": "confirmed",
    "price": 1299,
    "currency": "EUR",
    "price_decimal": "12.99",
    "wallet": 14471,
    "confirmed_at": 1355314392,
    "freeze": {
        "until": 1357992732
    },
    "description": "Payment for order No. 1234"
}

Example request to unfreeze money

PUT /rest/v1/payment/10145/freeze 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="0zGnMC77c3lRRDgSTqr8My4GQKGPIr/b2D1teR6VqiU=", ext="body_hash=aGFASfppuNJZ3Hn9aON62J4MnmIJiHVQ%2BlPjnqAcGqI%3D"
{
    "freeze": {
        "until": 0
    }
}
Info In this example we are unfreezing money of payment which ID is 10145

Example response

HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
{
    "id": 10145,
    "transaction_key": "pDAlAZ3z",
    "created_at": 1355314332,
    "status": "done",
    "price": 1299,
    "currency": "EUR",
    "price_decimal": "12.99",
    "wallet": 14471,
    "confirmed_at": 1355314392,
    "description": "Payment for order No. 1234",
    "transfer_id": 578842
}

Finalize payment

Payment can be finalized only when it's status is confirmed and freeze was provided when creating the payment. That is, if freeze time has been set and hasn't yet ended.

When finalizing the payment, you can specify a final payment price, which is smaller than the original. In this case, difference between final and original prices is returned back to the payer.

Request

PUT https://wallet.paysera.com/rest/v1/payment/:id/finalize

Parameters

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

Request body structure

Request body is optional in this request.
Parameter
Type
Remarks
Description
price
integer
required if price_decimal is not provided,
unavailable if price_decimal is provided
Final price of this payment in cents. Cannot be bigger than original price, must be positive.
currency
string
required
Must be the same as in original price
price_decimal
string
required if price is not provided,
unavailable if price is provided
Final decimal price of this payment. Cannot be bigger than original price, must be positive.
Info If you don't provide request body, this request does the same as changing freeze time to 0.

Response data structure

On success API returns corresponding payment object. See get payment information for more info.

Example request

PUT /rest/v1/payment/10145/finalize 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="uxvhqCv99gwrnPUX0O70Qhoog1QMN5mm9qAs+JOCRQ0=", ext="body_hash=hHVrOkPtrvtmFKNWKEsktgv6Dx%2F7WbDEtg93yHvcRtw%3D"
{
    "price": 299,
    "currency": "EUR"
}
Info In this example we are finalizing payment which ID is 10145 and setting final price to 2.99 EUR

Example response

HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
{
    "id": 10145,
    "transaction_key": "pDAlAZ3z",
    "created_at": 1355314332,
    "status": "done",
    "price": 299,
    "currency": "EUR",
    "price_decimal": "2.99",
    "wallet": 14471,
    "confirmed_at": 1355314392,
    "description": "Payment for order No. 1234",
    "transfer_id": 578842
}

Provide password for a payment

When payment's status is waiting_password, password can be provided for this payment by API. Password can be also provided by using OAuth-related API call or in Paysera system, so payment can be unlocked not only using this method.

Request

PUT https://wallet.paysera.com/rest/v1/payment/:id/password

Parameters

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

Request body structure

Parameter
Type
Remarks
Description
password
string
required
Password for this payment

Response data structure

On success API returns corresponding payment object. See get payment information for more info.

Example request

PUT /rest/v1/payment/10145/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="42yf4XxAHFNvbNqmFJuIHlt/l2U3iljodEhVG+dxwds=", ext="body_hash=AGR2TJUZ%2BQBepUliLhilu7TBof4cYOrF7mFQdqwZO4o%3D"
{
    "password": "some secret"
}

Example response

HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
{
    "id": 10145,
    "transaction_key": "pDAlAZ3z",
    "created_at": 1355314332,
    "status": "reserved",
    "price": 299,
    "currency": "EUR",
    "price_decimal": "2.99",
    "wallet": 14471,
    "description": "Payment for order No. 1234",
    "password": {
        "type": "provided",
        "status": "unlocked"
    },
    "transfer_id": 578842
}

Search payments

This method returns payment ID list by provided filters.

Request

GET https://wallet.paysera.com/rest/v1/payments/id?status=:status&wallet=:wallet&beneficiary=:beneficiary

Parameters

status - optional; status of payment to search for. Can be any of default payment statuses (see get payment information response data structure), except deleted

wallet - optional; ID of the wallet in Paysera system which confirmed the payment.

beneficiary - optional; same as provided when creating payments. Use value none to search for those payments that have no beneficiary

Response data structure

Response is array of integers - list of found payments' IDs

Example request when searching for new payments

GET /rest/v1/payments/id?status=new HTTP/1.1
Host: wallet.paysera.com
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="1au9XvlfPKgYcFy7BXqGRIhsGnXXhGFFJFK8hQhq4Kc="

Example request when searching for payments that were successfuly made to yourself

GET /rest/v1/payments/id?beneficiary=none&status=done HTTP/1.1
Host: wallet.paysera.com
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="By1q0FSjW1UlhGH9mRykpteA50Rr+WWm8spKmxH1znM="

Example response

HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
[
    1278,
    1992,
    2012,
    3012
]