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:

• 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:

1. 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
2. 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.
3. Uninitialized (null) parameters are not taken into account when forming the signature.
4. The values of enumerations converted to a string have values equal to their string representations.
5. Other simple data types are converted to strings without any transformation.
6. 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:

1. Date (DateTime type) – contains the date in UTC format without explicitly specifying the time zone and indicates when the reply message was generated.
2. IncomingSignature – a string with the signature passed by the Partner when calling.
3. 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:

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:

Possible error codes:

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:

Example request:

Service response:

CreatePurchaseResult structure:

Possible error codes:

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:

Example request:

Service response:

CreatePurchaseRefundResult structure:

Possible error codes:

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:

Example request:

Service response:

Possible error codes:

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:

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:

Example request:

Filling in the provider parameters (Params) is described in the separate section

Service response: | 200 OK |

Possible error codes:

POST /createwallettransfer

The method allows to create a transfer between two User's Wallets within the system.

Input parameters of the method:

Example request:

Service response:

Possible error codes:

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:

Example request:

Service response:

Possible error codes:

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:

Service response: