Payments API

The API allows developers to integrate their applications into the Capitalist system for automated downloading payments into the system.

Requirements

To use the API, you should have the status of a Verified Business User. Access to the API is activated upon agreement with the Customer Support.

All financial operations performed via the API are labeled using a "security certificate", so the "Certificate" option should be activated for your account. This option can be activated in the Security Settings page in the Profile section.

The data required for using the API

  • Username (not the e-mail)
  • Password
  • Certificate file
  • The password to the certificate file if it is encrypted
  • The batch payments data in a special format

The address for queries

https://api.capitalist.net/

Query format

An API query is a regular HTTP 1.1 POST query with the necessary parameters passed in its body.
The content type may be application/x-www-form-urlencoded or multipart/form-data.

Required query parameters

The query should be sent in UTF-8 encoding.
Dot "." shall be used as the decimal separator for amounts.

Parameter Description
login Username
operation Operation name. For exapmle, get_token.

Access with Plain password

You can use plain password with API (Operation get_token will not required in this case).

Use plain_password parameter instead of token and encrypted_password ones where is authorization is needed.

API operations

Currently, the API supports the following operations:

Operation Description
Authorization
get_token Obtaining encryption attributes.
Making payments
import_batch_advanced Uploading a batch payment into the system with a possibility to choose the verification method.
process_batch Batch payment confirmation.
get_batch_info Getting detailed information about the loaded batch payment.
get_document_fee Calculating the commission fee based on document parameters.
get_documents_history (DEPRECATED) Obtaining operations history.
get_documents_history_ext Obtaining operations history.
documents_search Search by payment number from your system.
add_payment_notification Sending a payment notification to the recipient.
is_verified_account Checking whether the account holder is verified.
Working with your accounts
get_accounts Obtaining a list of your accounts (wallets).
create_account Creating your account (wallet).
get_cashin_requisites Getting details for account replenishing.
Profile, registration
register_invitee Registration of a new user.
registration_email_confirm E-mail confirmation for a new user — entering confirmation code.
profile_get_verification_code A request to resend the confirmation code to an email address.
profile_change_email Changing user"s email address.
password_recovery_generate_code Sending the confirmation code for changing the password.
password_recovery Changing the password.
Other
currency_rates Obtaining of a currency rates.

Format of the reply

By default, the reply is sent in CSV format (separated by semicolons and line wraps) in UTF-8 encoding.

Choosing the response format

Currently two formats are supported: json, csv.

To get the reply in a more convenient format, the query should contain the 'x-response-format' HTTP header, e.g.

Header Chosen format
x-response-format: json A full-fledged JSON with named parameters
x-response-format: csv CSV is selected by default

The HTTP headers of the response return the homonym header 'x-response-format' that contains a real format of the response. They coincide in all cases.

Handling errors

By default (i.e. for the CSV format) the first parameter in the first line of the reply is always an integer (hereinafter referred to as "Error Code" for convenience). If the error code is zero, the operation was successful. Otherwise, the second parameter in the first line is the text of the error. For reply formats json, the code and the error text are passed in the code and message attributes.

Error codes

Code Description
0 Operation was successful
1 System error
2 Run-time error (error text should be analyzed)
5 User not found (wrong username passed)
10 Error attempting to decrypt the password
15 Invalid password
16 The number of login attempts exceeded. Try 30 minutes later
20 Invalid authentication token
25 Information queries in batch downloads with over 1,000 entries is forbidden without page-by-page breakdown
110 Signature verification error
111 The transfer data contains invalid characters
112 112 Exceeded number of records in a single batch payment
125 Uploaded file cannot be parsed
130 Account not found
131 At least one source account required
132 Batch is empty
135 Insufficient finds for operations
150 A non-POST query received
151 Unknown operation
152 API unavailable for the user
155 – 160 Errors associated with registering a new user (the register_invitee operation)
155 A user with this login already exists
156 A user with this email address already exists
157 Incorrect login format (the login should be 3 to 16 characters long, Latin characters or numbers)
158 Incorrect format of the email address
159 Incorrect format of the nickname (nickname should be 3 to 50 Latin characters, numbers, hyphens or underscores)
160 Error in the phone number (optional; it should consist of minimum 7 digits, including the international country code and the area code)
170 Error creating the wallet
180 Unknown confirmation method
181 The chosen confirmation method is inactive
182 Digital signature missing
185 Error importing a batch payment. The payment amount is equal to zero. The 2nd line is "payment id" (see the import_batch_advanced operation)
186 Error importing a batch payment. Contact Support for details.
187 Error importing mass payment due to temporary unavailability of one of the types of payments.
Second line contains zero-based number of record in batch file.
188 This error similar to error 185. Used for single-record masspayments. Error text contains declination comment.
190 – 210 get_document_fee operation errors
190 Unknown document type
191 Unknown service provider code
192 Unknown payment urgency (wire)
193 Recipient not specified
194 You should be the owner of the beneficiary account
195 You should be the owner of the debit account
196 Transfer amount should be greater than zero
197 Failure sending confirmation code
198 Invalid verification code
200 Account does not exist
202 Wrong request params

If you failed to find the Error Code description, please refer to customer service.

Examples of working with PHP

The archive is available for downloading at

The contents of the archive

Code Description
config.php The configuration file used in all examples
the "include" directory Required libraries
include/Client.php The main connection library
get_accounts.php An example of invoking get_accounts
create_account.php An example of invoking create_account, get_accounts
import_batch_advanced.php An example of invoking import_batch_advanced, get_batch_info, process_batch (MOBILE)
import_batch_advanced_signature.php An example of invoking import_batch_advanced signed with a certificate (SIGNATURE).
get_cashin_requisites.php An example of invoking get_cashin_requisites
api_password_recovery.php An example of invoking password_recovery_generate_code, password_recovery
api_registration_confirm.php An example of invoking registration_email_confirm
get_document_fee.php An example of invoking get_document_fee
get_documents_history.php An example of invoking get_documents_history
register_invitee An example of invoking register_invitee
sample-responses.txt Examples of replies in various formats: csv, json
API Capitalist