English

Currency Conversion

Info This feature is not available by default and is enabled only for some clients

To make currency conversions in user's account, convert_currency scope is needed. As this is extended scope, sending of SMS message with code in one of supported ways needs to initiated. After this code is provided to the client, it should be sent with token refresh request to extend current token scope with convert_currency.

Calculating currency conversion result

This request allows to calculate probable result of currency conversion. As the rates can change in time, the result is not guaranteed to be valid when actual conversion takes place.

Calculation request

GET https://wallet.paysera.com/rest/v1/currency-conversion

Parameters

Parameters are passed in the query string.

Parameter
Type
Remarks
Description
from_currency
string
required
Currency of currency conversion price
to_currency
string
required
Currency of currency conversion result
from_amount
integer
required if to_amount or to_amount_decimal is not provided. unavailable if to_amount or to_amount_decimal is provided
Currency conversion price in cents
from_amount_decimal
string
required if to_amount or to_amount_decimal is not provided. unavailable if to_amount or to_amount_decimal is provided
Currency conversion decimal price
to_amount
integer
required if from_amount or from_amount_decimal is not provided. unavailable if from_amount or from_amount_decimal is provided
Currency conversion result in cents
to_amount_decimal
string
required if from_amount or from_amount_decimal is not provided. unavailable if from_amount or from_amount_decimal is provided
Currency conversion decimal result
account_number
string
optional
Account number in which currency conversion is to be performed. This is needed if account owner has different currency conversion rate than the default one

Response data structure

Parameter
Type
Remarks
Description
from_currency
string
always
Same as provided in the request
to_currency
string
always
Same as provided in the request
from_amount
integer
always
Currency conversion price in cents
from_amount_decimal
string
always
Currency conversion decimal price
to_amount
integer
always
Currency conversion result in cents
to_amount_decimal
string
always
Currency conversion decimal result
account_number
string
only if it was provided in the request
Same as provided in the request

Example requests

GET /rest/v1/currency-conversion?from_currency=EUR&to_currency=USD&to_amount=200 HTTP/1.1
Host: wallet.paysera.com
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="TjBTboV3iZkrUvu6wHxXeflNF0INZ8TZmzK/G8Utj4E="
Info This requests to calculate needed price to convert EUR to 2.00 USD
GET /rest/v1/currency-conversion?from_currency=EUR&to_currency=USD&from_amount=150 HTTP/1.1
Host: wallet.paysera.com
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="KwCRgR3O9cWGni/fkUPjVBLfl5cCURgLHIc7yppjFHw="
Info This requests to calculate conversion result if 1.50 EUR would be converted to USD

Example response

HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
{
    "from_currency": "EUR",
    "to_currency": "USD",
    "from_amount": 150,
    "from_amount_decimal": "1.50",
    "to_amount": 200,
    "to_amount_decimal": "2.00"
}

Converting currency

Currency conversion request

POST https://wallet.paysera.com/rest/v1/currency-conversion

Parameters

Parameter
Type
Remarks
Description
from_currency
string
required
Currency of currency conversion price
to_currency
string
required
Currency of currency conversion result
from_amount
integer
required if to_amount or to_amount_decimal is not provided.
unavailable if to_amount or to_amount_decimal is provided
Currency conversion price in cents
from_amount_decimal
string
required if to_amount or to_amount_decimal is not provided.
unavailable if to_amount or to_amount_decimal is provided
Currency conversion decimal price
to_amount
integer
required if from_amount or from_amount_decimal is not provided.
unavailable if from_amount or from_amount_decimal is provided
Currency conversion result in cents
to_amount_decimal
string
required if from_amount or from_amount_decimal is not provided.
unavailable if from_amount or from_amount_decimal is provided
Currency conversion decimal result
account_number
string
required
Account number in which currency conversion is to be performed
max_from_amount
integer
optional, unavailable if from_amount or from_amount_decimal provided
Expected maximum conversion price in cents. If price would be bigger than this value, conversion is not performed and error is returned
max_from_amount_decimal
string
optional, unavailable if from_amount or from_amount_decimal provided
Expected maximum conversion decimal price. If price would be bigger than this value, conversion is not performed and error is returned
min_to_amount
integer
optional, unavailable if to_amount to_amount_decimal provided
Expected minimum conversion result in cents. If result would be smaller than this value, conversion is not performed and error is returned
min_to_amount_decimal
string
optional, unavailable if to_amount to_amount_decimal provided
Expected minimum conversion decimal result. If result would be smaller than this value, conversion is not performed and error is returned

Response data structure

Parameter
Type
Remarks
Description
id
integer
always
ID of this currency conversion
date
integer
always
Conversion date in UNIX timestamp
from_currency
string
always
Same as provided in the request
to_currency
string
always
Same as provided in the request
from_amount
integer
always
Currency conversion price in cents
from_amount_decimal
string
always
Currency conversion decimal price
to_amount
integer
always
Currency conversion result in cents
to_amount_decimal
string
always
Currency conversion decimal result
account_number
string
always
Same as provided in the request

Error codes

not_found
account was not found by given ID
no_rights
user has no needed permissions to execute currency conversions in this account
not_enough_funds
there is not enough funds to perform this operation
limits_exceeded
currency conversion limits were exceeded
expectation_failed
conversion price or result did not match expectations (provided by max_from_amount or min_to_amount parameters)

Example request

POST /rest/v1/currency-conversion 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="+ZVwDWDVqqhjTeA5t6cW4ZtgcXI9ikDH3oKzzWEHDfI=", ext="body_hash=%2FnvaEOVnCNABstYnlN4pVfw3f6FElVlYw5CNvgYzBls%3D"
{
    "from_currency": "EUR",
    "to_currency": "USD",
    "to_amount": 200,
    "account_number": "EVP0010001000101",
    "max_from_amount": 150
}
Info This requests to convert EUR to 2.00 USD if price is no bigger than 1.50 EUR

Example response

HTTP/1.1 200 OK
Content-type: application/json;charset=utf-8
{
    "id": 11221,
    "date": 1391686980,
    "from_currency": "EUR",
    "to_currency": "USD",
    "from_amount": 150,
    "from_amount_decimal": "1.50",
    "to_amount": 200,
    "to_amount_decimal": "2.00",
    "account_number": "EVP0010001000101"
}