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_documents_history_ext | Obtaining operations history. |
| documents_search | Search by payment number from your system. |
| is_verified_account | Checking whether the account holder is verified. |
| Working with your accounts | |
| get_accounts | Obtaining a list of your accounts (wallets). |
| 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 format.
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 | At least one source account required |
| 135 | Insufficient finds for operations |
| 150 | A non-POST query received |
| 151 | Unknown operation |
| 152 | API unavailable for the user |
| 170 | Error creating the wallet |
| 180 | Unknown confirmation method |
| 181 | The chosen verification 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 SupportSupport 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 files is available at github