Financial operation

This section describes the functions and data structures used in financial transactions in the Velespay payment platform.

The queries is done using GET/POST/PUT/DELETE requests in UTF-8 to URL https://api.velespay.com/v1/money/<Function Name>.

Response from the server is a JSON object.


Successful response will contain field - result.
Example:

{
	"result": [Array or Object]
}

Not successful, response contains an error field with a code and a message.
Example:

{
	"error": {
		"code": digital error code,
		"message": text error message
	}
}

Authentication

All API requests must contain authorization headers, parameters are passed in JSON format and UTF-8 encoding. Each request from your server to the Velespay API must contain the following headers and authentication information:

Request header:

Content-Type: application/json; charset=UTF-8
Authorization: Basic Base64(<Your Key API>:<hash all parameters passed>)

You must create a hash using the following algorithm:

  • Generate URL-encoded string of all the passed parameters of the query;
  • Decode URL-encoded string;
  • Generate hash code based on using HMAC method with sha512 algorithm;
  • <Your API Key>: encode to Base64;

Example in PHP:

$url = "https://api.velespay.com/v1/money/<Function Name>";
$http_method = "GET";//HTTP request method - GET/POST/PUT/DELETE
$user_agent = "Velespay API Client";//Your user agent

$accessKey = "Your Key API";
$secretKey = "Your Password API";

$params = array(
	"lang"=>"en"
);

$headers[] = 'Accept: application/json';
$headers[] = 'Content-Type: application/json; charset=UTF-8';
$headers[] = 'Accept-Encoding: UTF-8';

$hash = hash_hmac('sha512', urldecode(http_build_query($params)), $secretKey);
$headers[] = 'Authorization: Basic '.base64_encode($accessKey.':'. $hash);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_FAILONERROR, false);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_USERAGENT, $user_agent);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $http_method);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($params));
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$res = curl_exec($ch);
curl_close($ch);

$res = json_decode($res);

Checking wallet balance

HTTP method: GET

Function: Balance

URL: https://api.velespay.com/v1/money/Balance

Available optional query parameters:

lang = Language code ISO 639-1 (for error output), default en
currency = Digital currency code according to ISO 4217

Result executing successful request = structure data Balance.

Intra-system transfer of funds

Sending or validating the sending (preview) of funds within the Velespay system to another user or between wallets.

HTTP method: GET (Validation)

HTTP method: POST (Sending)

Function: Send_Money

URL: https://api.velespay.com/v1/money/Send_Money

Required query parameters:

receiver = recipient. Phone: +6531588872, E-mail: [email protected], Wallet: VM123456789, ID Account: 123456789
currency = Digital currency code according to ISO 4217
amount = transaction amount

Optional query parameters:

who_fee = who is to pay the fees, false = sender, true = recipient
invoice = Identification number, according to your accounting system. Maximum 100 characters
period = If the translation with the code of protection. Protection period: from 1 to 30 days. default 0
code = If the translation with the code of protection. Transfer activation code. Maximum 20 characters
description = Note
lang = Language code ISO 639-1 (for error output), default en

Result executing successful request = structure data TxnInfo.

Activation of intra-system transfer of funds

If the intra-system transfer was sent with a protection code

HTTP method: PUT

Function: Send_Money

URL: https://api.velespay.com/v1/money/Send_Money/<Transaction ID>

Required query parameters:

code = Activation code. Maximum 20 characters

Optional query parameters:

lang = Language code ISO 639-1 (for error output), default en

Result executing successful request = structure data TxnInfo.

Cancellation of intra-system transfer of funds

If the intra-system transfer was sent with a protection code

HTTP метод: DELETE

Function: Send_Money

URL: https://api.velespay.com/v1/money/Send_Money/<Transaction ID>

Optional query parameters:

lang = Language code ISO 639-1 (for error output), default en

Result executing successful request = structure data TxnInfo.

Put invoice buyer

Create a payment invoice for the buyer and automatically send to the email of the user from whom you want to receive the payment. The user will be able to get information about you, pay the invoice, postpone or reject the payment.

HTTP method: GET (Validation)

HTTP method: POST (Create)

Function: Send_Invoice

URL: https://api.velespay.com/v1/money/Send_Invoice

Required query parameters:

invoice = Invoice number, according to your accounting system. Maximum 100 characters
buyer = Buyer. Phone: +6531588872, E-mail: [email protected], Wallet: VM123456789, ID Account: 123456789
	If the invoice is provided to the client which is not registered in the system Velespay specified E-mail
currency = Digital currency code according to ISO 4217
product = an array of objects which lists the Goods/Services for which the invoice is issued
	product[0]['name'] = Name of Goods or Services
	product[0]['quantity'] = Quantity
	product[0]['price'] = Price per unit of Goods/Service

Optional query parameters:

who_fee = who pays fees. false = buyer, true = seller
internal = false, If the invoice is issued to a customer who is not registered in the Velespay system
lifetime = up to what time it is possible to pay the bill, by default 15 days. Format: yyyy-mm-dd'T'HH:MM:ss'Z'
description = Additional information that the buyer will see
payment_method = array with codes of electronic currencies with which it is possible to pay the invoice
	field ps_code link to https://api.velespay.com/v1/info/Merchant?visible=true
	If not specified, buyer can pay in any available way
buyer_lang = Language code ISO 639-1 (In what language to send messages to the buyer or display the payment page), default en
lang = lang = Language code ISO 639-1 (for error output), default en

Result executing successful request = structure data TxnInfo.

Cancel invoice

HTTP method: DELETE

Function: Send_Invoice

URL: https://api.velespay.com/v1/money/Send_Invoice/<Transaction ID>

Optional query parameters:

lang = Language code ISO 639-1 (for error output), default en

Result executing successful request = structure data TxnInfo.

Internal currency exchange.

HTTP method: GET (Validation)

HTTP method: POST (Exchange)

Function: Currency_Exchange

URL: https://api.velespay.com/v1/money/Currency_Exchange

Required query parameters:

currency_from = From currency (Digital currency code according to ISO 4217)
currency_to = To currency (Digital currency code according to ISO 4217)
action = Takes two values:
	sell - sale amount (amount in currency currency_from will be sold)
	buy - purchase amount (amount in currency currency_to will be purchased)
amount = Amount

Optional query parameters:

lang = Language code ISO 639-1 (for error output), default en

Result executing successful request GET = structure data CurrencyExchange.

Result executing successful request POST = structure data TxnInfo.

Withdrawal of funds

Withdrawals to a third-party payment system, Bank account or debit card.

HTTP method: POST

Function: Withdraw

URL: https://api.velespay.com/v1/money/Withdraw

Required query parameters:

ps = E-Currency code. field ps_code link to https://api.velespay.com/v1/info/Withdraw?visible=true
amount = withdrawal amount (this amount will be deducted from your account in the system Velespay)
depending on the selected currency:
	payee = object with recipient data, depends on payment system/Bank, etc.
	payee[wallet] = Wallet number or debit card number (Example: VM123xxx, U123xxx, P123xxx etc)
	payee[email] = If the third-party PS is available to send funds by E-mail means this field is used
	payee[phone] = If the third-party PS is available to send funds by phone number then this field is used (international format Example: +6531588872)
		this field is used for QIWI output
	payee[account] = If this parameter is specified, it will be converted to payee[wallet] or payee[email] or payee[phone]

Optional query parameters:

invoice = Identification number, according to your accounting system. Maximum 100 characters
description = A comment that will be seen by an employee of the Finance Department. Used mainly for Bank transfers
who_fee = true - fees from the amount received, false - fees from the sent amount
send_email = false - without sending notifications, true with sending
lang = Language code ISO 639-1 (for error output), default en

Parameters for withdrawing funds using SWIFT/SEPA (Bank account):

Beneficiary:
	payee['beneficiary_number'] = Passport number, for companies registration number
	payee['beneficiary_name'] = Full name in English, as in the passport or company registration documents
	payee['beneficiary_name_cyr'] = Name in Cyrillic, as in the passport (full name) or company registration documents (if the output in the CIS countries)
	payee['beneficiary_inn'] = ITN/IIN/BIN
	payee['beneficiary_kpp'] = KPP for companies in Russia
	payee['beneficiary_country'] = Country (citizenship)
	payee['beneficiary_address'] = Apartment, house, Street (address)
	payee['beneficiary_city'] = City (town)
	payee['beneficiary_region'] = Region
	payee['beneficiary_zip_code'] = Postal code
Bank account:
	payee['bank_currency'] = Currency of account (Digital currency code according to ISO 4217)
	payee['bank_iban'] = IBAN/account Number
	payee['bank_code_type'] = Type of national Bank code, default 1 (SWIFT), see list in "Information data" -> " Bank code"
	payee['bank_code'] = Bank code or SWIFT code
	payee['bank_name'] = Bank name
	payee['bank_country'] = Bank country
	payee['bank_city'] = Bank city
	payee['bank_address'] = Address of the branch
	payee['bank_bik'] = BIK for Russian banks
	payee['bank_correspondent_account'] = Correspondent account for Russian banks
	payee['bank_sort_code'] = Sort code or Routing number

Parameters of money transfer via CONTACT system (cash):

Recipient:
	payee['lang'] = Language code ISO 639-1 (In what language to send the message/notification to the recipient of the translation), default en
	payee[email] = E-mail of the transfer recipient. A notification with the transfer data will be sent.
	payee[phone] = Phone number of the transfer recipient, optional
	payee[contact_trnPickupPoint] = Payout point code, 4 symbols.
	payee[contact_bName] = SURNAME transfer recipient.
	payee[contact_bLastName] = NAME transfer recipient.
	payee[contact_bSurName] = Middle name of the transfer recipient, optional
	
Some countries / points have features of payment transfer and require additional parameters:
	payee[contact_bCity] = City recipient in english.
	payee[contact_bAddress] = Full address of the recipient in english.

Result executing successful request = structure data TxnInfo.

Cancel withdrawal

Cancel is possible only if the application is not processed

HTTP method: DELETE

Function: Withdraw

URL: https://api.velespay.com/v1/money/Withdraw/<Transaction ID>

Optional query parameters:

lang = Language code ISO 639-1 (for error output), default en

Result executing successful request = structure data TxnInfo.

Transaction history

Get a list of operations or search for a specific operation

HTTP method: GET

Function: Transaction_History

URL: https://api.velespay.com/v1/money/Transaction_History

or

URL: https://api.velespay.com/v1/money/Transaction_History/<Transaction ID>

Optional query parameters:

receiver = Receiver. Phone: +6531588872, E-mail: [email protected], Wallet: VM123456789, ID Account: 123456789
type = transaction type value or array (digital), see the list in "Information data" -> "Transaction type"
status = transaction status value or array (digital), see the list in "Information data" -> "Statuses transaction"
currency = value or array of currencies (Digital currency code according to ISO 4217), see the list in" Information data " -> "Currencies"
begin = Starting date for the sample transaction (format yyyy-mm-dd, or UTC format, example: 2015-01-10)
end = End date for the sample transaction (format yyyy-mm-dd, or UTC format, example: 2015-01-10)
page_size = Number of transactions returned per page. Maximum value 50.
page_number = Page, default 1
view = all (entire transaction), in (incoming), out (outgoing)
lang = Language code ISO 639-1 (for error output), default en

Result executing successful request = structure data HistoryInfo.