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.

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

Request parameters:

invoice = Invoice number, according to your accounting system. Maximum 100 characters (required)

buyer = Buyer. Phone: +6531588872, E-mail: [email protected], Wallet: VM123456789, ID Account: 123456789 (required)
	IMPORTANT!!! If the invoice is provided to the client which is not registered in the system Velespay specified E-mail.

currency = Digital or string currency code according to the ISO 4217 standard, for example: 840 or USD (required)

who_fee = who pays fees. true - seller, false - buyer (by default) (optional)

fiscalization = An object with fiscal parameters (optional)
	fiscalization.enabled = Print fiscal receipts, true - yes (by default), false - no.
	
	fiscalization.cashbox = ID of your cashbox for sending receipts, if you have several cashbox.
	
	fiscalization.agent = Agent flag, true - Enables, false - Disables the agent parameters in the cashbox settings. The agent parameters must be filled in in the cashbox settings. By default, in the cashbox settings, you can disable agent operations and pass true for such an operation, thereby activating it.
IMPORTANT!!! Sending to the cashbox is carried out after setting up and activating the "checks" Service.

internal = false - If the invoice is issued to a client who is not registered in the Velespay system, true - the client is registered in the Velespay system (optional)

lifetime = by what time it is possible to pay the invoice, by default, 15 days. (optional)
	Format: yyyy-mm-dd'T'HH:MM:ss'Z'
	Time zone: UTC

description = Additional information that the buyer will see (optional)

payment_method = an array with the codes of electronic currencies with which it is possible to pay an invoice (optional)
	ps_code field by link.	If not specified, the buyer will be able to 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 (optional)

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

send_email = false - without sending a message to the buyer's email, true - sending (by default) (optional)

product = an array of objects that lists the Goods/Services for which the invoice is issued (required)
	product.0.name = Name of Goods or Services (required)

	product.0.quantity = Quantity, by default 1 (optional)

	product.0.price = Final price per unit of Goods/Services, including VAT and other fees (required)
		IMPORTANT!!! Must be a positive number.

	product.0.img = Full URL to a small image in JPG, JPEG, GIF, BMP, PNG format (optional)

	product.0.vat = Object  (optional)
	product.0.vat.code = VAT rate code (required)
		none - Without VAT
		composite - Composite/Combined
		vat0 - VAT at the rate of 0%
		vat10 - VAT at the rate of 10%
		vat20 - VAT at the rate of 20%
		vat110 - VAT at the rate of 10/110 (settlement rate)
		vat120 - VAT at the rate of 20/120 (settlement rate)
		vat(number) - a different bid. Example:
			1) vat18 = 18%
			2) vat118 = 18/118 (settlement rate)
	product.0.vat.value = tax amount, calculated automatically (optional)
		IMPORTANT!!! If product.0.vat.code = composite is specified, this parameter is required

	product.0.measure = The unit of measurement of the quantity of the calculation object, by default, piece (optional)
		piece - individually or in units
		gram - Gram
		kilogram - Kilogram
		ton - Ton
		centimeter - Centimetre
		decimeter - Decimeter
		meter - Metre
		square_centimeter - Square centimeter
		square_decimeter - Square decimeter
		square_meter - Square meter
		milliliter - Milliliter
		liter - Litre
		cubic_meter - Cubic meter
		kilowatt_hour - Kilowatt hour
		gigacalorie - Gigacalory
		day - Day
		hour - Hour
		minute - Minute
		second - Second
		kilobyte - Kilobytes
		megabyte - Megabytes
		gigabyte - Gigabyte
		terabyte - Terabyte
		other - other unit of measurement

	product.0.payment_method = Indication of the calculation method, by default full_payment (optional)
		full_prepayment - Full prepayment
		partial_prepayment - Partial prepayment
		advance - Advance
		full_payment - Full payment
		partial_payment - Partial payment and credit
		credit - Credit
		credit_payment - Credit payment

	product.0.payment_object = Indication of the subject of calculation, by default payment (optional)
		commodity - Goods
		excise - Excisable goods
		job - Job
		service - Service
		gambling_bet - A bet in a gambling game
		gambling_prize - Winning in a gambling game
		lottery - Lottery ticket
		lottery_prize - Winning the lottery
		intellectual_activity - Results of intellectual activity
		payment - Payment
		agent_commission - Agency fee
		property_right - Property rights
		non_operating_gain - Non-operating income
		insurance_premium - Insurance fee
		sales_tax - Trading fee
		resort_fee - Resort fee
		composite - Several options
		another - Other

	product.0.excise = Excise tax amount, by default 0 (optional)
	
	product.0.country = Three-digit code of the country of origin of the goods, Example: 156 = China or 643 = Russia (optional)
	
	product.0.declaration_number = Number of the customs declaration. Maximum of 32 characters (optional)
	
	product.0.marking_code = Product labeling (optional)
		IMPORTANT!!! it is transmitted in the form as it is printed on the product packaging.
		This parameter is mandatory only for those stores that sell products that are subject to mandatory labeling.
		The marking code is located on the product packaging, next to the barcode or in the form of a QR code.
	
sci = an object with data of redirects and notifications for redefining values in the personal account (optional)
	sci.success = an object containing information where to redirect the buyer after a successful payment (optional)
		sci.success.url = Redirect URL (optional)
		sci.success.method = The method of passing parameters is POST or GET (by default) (optional)
	sci.fail = an object containing information where to redirect the buyer after an unsuccessful payment (optional)
		sci.fail.url = Redirect URL (optional)
		sci.fail.method = The method of passing parameters is POST or GET (by default) (optional)
	sci.ipn = an object containing information where to send a notification about a successful payment (optional)
		sci.ipn.url = The URL for the notification (optional)
		sci.ipn.method = The method of passing parameters is POST or GET (by default) (optional)

IMPORTANT!!! When using the "checks" Service (the "checks" Solution, the "Cash" Solution, the "Cloud" Solution).
product parameters are transmitted to the fiscalization (to your CRM or online-cashbox) in the form they were received from you.
The information is transmitted to the tax service, and is also displayed in the buyer's fiscal receipt.
Be careful, you are responsible for the incorrect transmission of parameters.

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.

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.

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.