Whillet Documentation for Developers
Interaction between Partner services and Whillet is performed via VPN. The messaging protocol used is HTTP(S) at the application level. Interaction with the service is done by passing REST requests to the URL.
The authenticity of transmitted data is ensured by using the Partner's private key. Key generation and exchange, as well as other actions with the key data are performed according to the Electronic Document Interchange Agreement. The request authenticity is verified using the following parameters transmitted in the header:
- PartnerId
- Signature
- Timestamp
The request signature is obtained by concatenating the parameters: Where:
SIGNATURE = BASE64(SIGNATUREMETHOD(UTF8(URL + TIMESTAMP + REQUESTBODY + SIGNATUREKEY)));- BASE64 — a function that converts binary data (array of bytes) to a BASE64 string
- SignatureMethod — a cryptographic function used to calculate the EDS (Partner's key signing method SHA256)
- UTF8 — a function that converts the string to UTF8 encoding and returns an array of bytes
- URL — the URL address to which the request is sent
- Timestamp — a timestamp in UTC (with deviation of not more than 5 minutes)
- RequestBody — contains the request parameter values sorted in alphabetical order
- SignatureKey — the Partner's private key
The rules for converting transferred data to a string:
- Fractional numbers (Float, Double, Decimal) are rounded to two digits after the separator and then converted to a string. A dot (".") is used as a separator. Even if the separator is followed by zeros, the zeros must also be present in the string. Thus, the number "1" will look like "1.00" after conversion to a string for the hash function. Extra examples: 1.6578 = 1.66 1.843 = 1.84 55.4 = 55.40
- Dates are converted using the following format: yyyy-MM-ddTHH:mm:ss. The value of the parameter normalized to the UTC time zone is used.
- Uninitialized (null) parameters are not taken into account when forming the signature.
- The values of enumerations converted to a string have values equal to their string representations.
- Other simple data types are converted to strings without any transformation.
- If a method requires a parameter described by a more complex data type (structure) to be passed, the order of such parameter conversion to a string should be specified separately.
Partner (in terms of the developed interface) is an external service that can register wallets in Whillet app and at the same time fully manage the financial flow of these wallets.
Mandatory call parameters (Partner ID, signature, timestamp) are passed in the request header. In the methods description the details about passing of these parameters will be omitted.
Each response to a particular service method call is accompanied by a header (ResponseHeader), which has the following three fields:
- Date (DateTime type) – contains the date in UTC format without explicitly specifying the time zone and indicates when the reply message was generated.
- IncomingSignature – a string with the signature passed by the Partner when calling.
- ResponseSignature – a string representing the EDS of the server response, obtained by the following formula:
Where:
- BASE64 — a function that converts binary data (array of bytes) to a BASE64 string
- SignatureMethod — a cryptographic function used to calculate the EDS (Partner's key signing method)
- UTF8 — a function that converts the string to UTF8 encoding and returns an array of bytes
- IncomingSignature — a string with the signature transmitted by the Recorder in the request
- Body — the meaningful content of the method response
There are the following groups of API methods:
Group | Purpose |
---|---|
Basic methods | Methods intended for registration of the Wallet in the System and getting the balance of the Wallet |
Financial transactions | |
Perform purchase or a batch purchase | The method is intended for carrying out a purchase operation in the system |
Return purchase | The method is designed for canceling purchase transactions |
Get the transaction(s) status | The method is designed to get the status of transaction(s) for the selected Wallet of the User |
Perform payment or a batch payment to a Wallet | The method is designed to carry out the payment operation to the Users' Wallets from the Partner's Wallet |
Change transfer state | The method is designed to change the transfer status within the system |
Wallet to Wallet transfer | The method is designed to make transfer between two user wallets |
Perform payment to an external system | The method is designed to withdraw money to an external system (bank card, checking account, cell phone number, e-wallet, etc.) |
POST /wallet
Registering a new Wallet. The method receives one parameter (client ID, which is unique within the Partner's accounting system). If a Wallet with such external ID has already been created before, the request will return the existing Wallet number. The Partner sends this returned number to the client and stores it on its side for further operations. Using the Wallet number, the Client can put money into the Wallet in any available way. The list of funding methods should be approved under the agreement with the Partner.
Example request:
Service response:
GET /wallet/{walletId}/balance
Getting the current balance of the Wallet. The response contains a UserBalance structure that describes the current balance in the requested currency. The currency identifier corresponds to the generally accepted ISO 4217 standard.
Example request: {baseUrl}/wallet/{walletId}/balance
Where:
- walletId — User's wallet ID, for which you want to get a balance
Service response:
UserBalance structure:
Field name | Data type | Description |
---|---|---|
CurrencyId | Int | Currency ID as per ISO 4217 |
Amount | Decimal | Current balance of the wallet |
OverLimitAmount | Decimal | Overlimit amount on the wallet |
Overdraft | Decimal | Amount of credit limit available for spending |
AvailableAmount | Decimal | The total amount available for spending. At the moment it is calculated as Amount + Overdraft |
SafeAmount | Decimal | Balance amount limited for withdrawal to external systems |
BalanceLimit | Decimal | Balance limit |
DailyLimit | Decimal | Daily spending limit |
MonthlyLimit | Decimal | Monthly spending limit (from the 1st of the month) |
OperationLimit | Decimal | Transaction limit (number of operations) |
KycLevel | Int | The level of the user identification for this currency. Possible levels of identification: 0 - not identified, 5 - simplified identification performed, 10 - full identification performed |
KycRequestStateId | String | Status of the last identification request. Possible values: Accepted - identification performed, Canceled - rejected by operator or identification agent, Created - created, Declined - canceled due to a new request, OperatorReview - pending operator review, Processing - in processing, Expired - identification is invalid. Spending transactions are prohibited |
Possible error codes:
Error code | Fatal | Description |
---|---|---|
WALLET_ID_NOT_FOUND | Yes | User ID not found (not registered in the System) |
POST /purchase
Money transfer from User's Wallet to Partner's Wallet. The method returns a Transfer structure describing the transfer.
Input parameters of the method:
Field name | Data type | Description |
---|---|---|
WalletId | Long | Transfer sender ID (always a user's Wallet) |
Amount | Decimal | Amount to be received |
CurrencyId | Int | Currency ID |
OrderId | String | External transfer ID unique for the sender. Used to control integrity and to avoid repeated operations |
Description | String | A string note to the transfer visible to both the sender and the receiver. It is saved in the operations history |
Example request:
Service response:
CreatePurchaseResult structure:
Field name | Data type | Description |
---|---|---|
TransferId | Long | Transfer ID |
FromUserId | Long | Transfer sender ID |
ToUserId | Long | Transfer receiver ID |
TransferType | Long | Transfer/purchase type |
Amount | Decimal | Amount to be received |
Description | String | A text note to the transfer |
CommissionAmount | Decimal | Commission amount |
TransferStateId | Enum | Transfer status |
OrderId | String | External transfer ID in the sender's accounting system |
CreateDate | DateTime | Transfer creation date. It contains the date in UTC format without explicitly specifying the time zone |
UpdateDate | DateTime | Date of the last status change. It contains the date in UTC format without explicitly specifying the time zone |
ExpireDate | DateTime | Confirmation expiration date. It contains the date in UTC format without explicitly specifying the time zone |
Possible error codes:
Error code | Fatal | Description |
---|---|---|
USER_ID_NOT_FOUND | Yes | User ID not found |
AMOUNT_RANGE_ERROR | Yes | Sent amount is out of permissible range |
SELF_OPERATION_ERROR | Yes | A user is attempting to transfer money to himself |
CURRENCY_ID_NOT_FOUND | Yes | Currency ID not found |
BALANCE_IS_INSUFFICIENT | Yes | Not enough funds on the sender's account to complete the transaction |
IDENTIFICATION_EXPIRED | Yes | Passport data must be updated |
FINANCIAL_LIMIT_EXCEEDED | Yes | Financial transaction limit exceeded |
POST /purchase_batch
Batch money transfer from User's Wallet to Partner's Wallet. The method returns a CreatePurchaseBatchResult structure describing the batch purchase of the ticket. Input parameters of the method: an array of CreatePurchase input model objects
Example request:
Service response:
Where:
- TransferBatchId — batch transaction ID
- TotalCount — total number of transactions in the batch
- Transfers — an array of purchase transactions in the batch
PATCH /purchase/{transferId}/refund
Partial or full refund of the transfer. Refund creates a transfer from the Partner's Wallet to the User's Wallet. The method returns a Refund structure describing the transfer.
Input parameters of the method:
Field name | Data type | Description |
---|---|---|
transferId | String (path) | Refund ID parent for as per accounting system Whillet |
ExternalId | String | Refund ID as per Partner's accounting system. It must be unique within the payment to be refunded |
Amount | Decimal | Refund amount |
CurrencyId | Int | Currency ID |
Description | String | A string note to the refund visible to both the sender and the receiver. It is saved in the operations history |
Example request:
Service response:
CreatePurchaseRefundResult structure:
Field name | Data type | Description |
---|---|---|
RefundId | Long | Refund ID as per processing accounting system |
TransferId | Long | Original payment ID as per processing accounting system |
ExternalId | String | Refund ID as per Recorder's accounting system |
Amount | Decimal | Amount to be received |
CurrencyId | Int | Currency ID |
Description | String | A string note to the refund |
RefundStateId | Enum | Refund status. Possible values: - Accepted – the refund was performed successfully. The money is transferred to the receiver - Rejected – the refund was rejected - Expired – the deadline for confirming the refund has expired - Processing – the refund is being processed by the system - ProcessError - an error occurred when processing the refund - Created – refund was created but not confirmed |
CreateDate | DateTime | Refund creation date. It contains the date in UTC format without explicitly specifying the time zone |
UpdateDate | DateTime | Date of the last status change. It contains the date in UTC format without explicitly specifying the time zone |
Possible error codes:
Error code | Fatal | Description |
---|---|---|
AMOUNT_RANGE_ERROR | Yes | The amount transferred is incorrect. For example, the amount together with the refunds exceeds the amount of the original payment. For operation # amount refunded in full |
TRANSFER_ID_NOT_FOUND | Yes | The original payment ID is not transmitted or does not exist |
ARGUMENT_CHECK_ERROR | Yes | One of the fields is not valid. For example, the currency ID does not match the currency ID of the original payment, or other, or ExternalId is not specified |
REFUND_FORBIDDEN | Yes | Refund creation forbidden |
CLIENT_OPERATION_ID_ALREADY_USED | Yes | The specified ExternalId has already been used before |
POST /payout
Money transfer from Partner's Wallet to User's Wallet. The method returns a CreatePayoutResult structure describing the transfer. Input parameters of the method:
Field name | Data type | Description |
---|---|---|
WalletId | Long | Transfer receiver ID (always a User's Wallet) |
Amount | Decimal | Amount to be received |
CurrencyId | Int | Currency ID |
OrderId | String | External transfer ID unique for the sender. Used to control integrity and to avoid repeated operations |
Description | String | A string note to the transfer visible to both the sender and the receiver. It is saved in the operations history |
Example request:
Service response:
Possible error codes:
Error code | Fatal | Description |
---|---|---|
USER_ID_NOT_FOUND | Yes | Sender's or receiver's ID not found |
AMOUNT_RANGE_ERROR | Yes | Sent amount is out of permissible range |
SELF_OPERATION_ERROR | Yes | A user is attempting to transfer money to himself |
CURRENCY_ID_NOT_FOUND | Yes | Currency ID not found |
BALANCE_IS_INSUFFICIENT | Yes | Not enough funds on the sender's account to complete the transaction |
IDENTIFICATION_REQUIRED | Yes | The receiver is not identified by the specified currency |
OPERATION_LIMIT_EXCEEDED | Yes | Payment amount is bigger than User's limit |
POST /payout_batch
Batch money transfer from Partner's Wallet to User's Wallet. The method returns a CreatePayoutBatchResult structure describing the batch transfer. Input parameters of the method: array of objects, the input model of the CreatePayout object
Example request:
Service response:
Where:
- TransferBatchId — batch transaction ID
- TotalCount — total number of transactions in the batch
- Transfers — an array of purchase transactions in the batch
Possible error codes:
Error code | Fatal | Description |
---|---|---|
USER_ID_NOT_FOUND | Yes | Sender's or receiver's ID not found |
AMOUNT_RANGE_ERROR | Yes | Sent amount is out of permissible range |
SELF_OPERATION_ERROR | Yes | A user is attempting to transfer money to himself |
CURRENCY_ID_NOT_FOUND | Yes | Currency ID not found |
BALANCE_IS_INSUFFICIENT | Yes | Not enough funds on the sender's account to complete the transaction |
IDENTIFICATION_REQUIRED | Yes | The receiver is not identified by the specified currency |
OPERATION_LIMIT_EXCEEDED | Yes | Payment amount is bigger than User's limit |
POST /processpayment
The method processes requests to withdraw funds to external payment systems and other service providers. Withdrawal is a multistep operation. Typical scenario of method calls for service providers with one form is as follows: The first call transfers only one parameter - the string ID of the service provider (all other parameters are null). In response to the first call the service creates payment in the system and returns information about it (ID, status, number of the current step, number of steps) and description of the form to be filled at the current step. An interface is formed in which the necessary details must be entered. The sender enters data necessary for the next call of ProcessPayment method. This call contains all parameters filled in form including payment ID. Next it is necessary to use SetTransferState method.
Input parameters of the method:
Field name | Data type | Description |
---|---|---|
WalletId | Long | Sender ID |
ProviderId | String | Service provider ID |
PaymentId | Long | Unique ID of the payment. Not necessary when performing the first call |
Params | Array | An array of provider parameters describing the data entered by the User in the payment form |
Example request:
Filling in the provider parameters (Params) is described in the separate section
Service response: | 200 OK |
Possible error codes:
Error code | Fatal | Description |
---|---|---|
PAYMENT_PROVIDER_IS_NOT_ACTIVE | Yes | The provider with the requested ID is temporarily unavailable for payment |
PAYMENT_FIELD_FORMAT_ERROR | Yes | One of the form fields is filled out incorrectly |
PAYMENT_FIELD_MIN_LENGTH_ERROR | Yes | The minimum length limit of one of the fields has been violated |
PAYMENT_FIELD_MAX_LENGTH_ERROR | Yes | The maximum length limit of one of the fields has been violated |
PAYMENT_FIELD_REQUIRED_ERROR | Yes | The value of a required form field is not passed |
PAYMENT_FIELD_REGEX_ERROR | Yes | One of the field values does not satisfy the regular expression for validation |
PAYMENT_FIELD_ITEM_ID_ERROR | Yes | An invalid list field value was passed |
AMOUNT_RANGE_ERROR | Yes | The payment amount is not within the allowable range for this provider |
PAYMENT_ID_NOT_FOUND | Yes | Payment ID was not found, or the time period for filling out the form has expired |
IDENTIFICATION_REQUIRED | Yes | Identification required |
OPERATION_LIMIT_EXCEEDED | Yes | Exceeded transaction limit |
POST /createwallettransfer
The method allows to create a transfer between two User's Wallets within the system.
Input parameters of the method:
Field name | Data type | Description |
---|---|---|
FromUserId | Long | Sender ID |
ToUserId | Long | Receiver ID |
Amount | Decimal | Transfer amount |
Description | String | Transfer description |
OrderId | String | Transaction ID in Partner's system |
Example request:
Service response:
Possible error codes:
Error code | Fatal | Description |
---|---|---|
FROMUSERID_NOT_FOUND | Yes | Sender's Wallet not found |
TOUSERID_NOT_FOUND | Yes | Receiver's Wallet not found |
AMOUNT_RANGE_ERROR | Yes | The payment amount is not within the allowable range for this provider |
IDENTIFICATION_REQUIRED | Yes | Identification required |
OPERATION_LIMIT_EXCEEDED | Yes | Exceeded transaction limit |
PATCH /operation/{transferId}
The method allows to change status of an already created transfer. For example, it can accept (set to "Accepted") or reject (set to "Rejected") a transfer with "Created" status. The sender can change transfer status from "Created" to "Canceled"; it will mean the cancellation of the created transfer. The method is used to confirm the payment to the external system.
Input parameters of the method:
Field name | Data type | Description |
---|---|---|
transferId | Long | Transaction ID |
WalletId | Long | User ID |
TransferStateId | Enum | The code of the state to which the transfer should be transferred |
Example request:
Service response:
Possible error codes:
Error code | Fatal | Description |
---|---|---|
USER_ID_NOT_FOUND | Yes | No transfer found with this sender and passed ID |
TRANSFER_ID_NOT_FOUND | Yes | Transfer with passed ID not found |
TRANSFER_STATE_ID_CHANGE_ERROR | Yes | Switching the transfer to the specified state is prohibited |
GET /operation/{transferId}
The method allows to get the status of the transaction (single or batch one).
Method call: {baseUrl}/operation/{transferId}
Input parameters of the method:
Field name | Data type | Description |
---|---|---|
transferId | String (path) | Transaction ID |
Service response: