Release Version 4.17.0 (March 1, 2024)

01. 03. 2024

What’s new


New Accounting Model was implemented for all supported operations. It gives an opportunity to see in-system money circulation in the separate wallet balance (type=issuing_balance) on the runtime. All incomes/outcomes to/from the system circulation (in certain currency) going through the issuing_transit account and issuing_balance account. Example: all incomes/outcomes to/from the system circulation in Currency1 reflect on the issuing1_balance account and issuing1_transfer account (both accounts have one unique Currency – Currency1) To reconcile the volume of circulation (in a particular issued Currency, e.g. Currency USD1) compare the balances of the Currency1 issuing1_transfer account with the balance of issuing1_balance account – this balances show a volume of circulation and it must be equal. The current atomic transactions inside the Business Processes were chnaged according to the schema of technical transactions. If the “integrator” (or “client”) uses the fields from node `transactions` from the API endpoints POST /transactions/view or GET/transactions/{transactionId} for their system – they should note that the atomic transaction has changed (see schemas below). Internal operations Transfer OUT commission Transfer IN commission Transfer SHARED commission Top up via bank Top up via cash desk Withdrawal via cash desk Cash desk investment Cash desk input Cash desk collect Invoice Merchant payment Voucher creation Voucher activation Currency exchange Top up exchange reserve Withdraw exchange reserve Provider operations (Gate) Top up via provider total commission>provider commission Top up via provider total commission<provider commission Withdrawal via provider total commission>provider commission Withdrawal via provider total commission<provider commission Purchase via provider total commission>provider commission Purchase via provider total commission<provider commission Issue card
The ability to Top up/Withdraw the Exchange Reserve account was added. Exchange Reserve account – it is the currency exchange reserve account, used only for Currency Exchange operations (see accounting model description for Currency exchange operation). See “API Changes” section of the release notes to know more about changes related to API For the Business user to be able to perform currency exchange operations, the Service user (any service user with appropriate permission) must first top up the balances on exchange_reserve wallets for the required currencies. The Service user (Service role with appropriate permission) can create a request to Top up or Withdraw from the Exchange Reserve account via bank transfer. After the request is created the Service user with appropriate permission must accept or decline a request to process such operation further. New Business process types were added: exchange_reserve_top_up and exchange_reserve_withdraw To create Top up/Withdrawal Exchange Reserve Request user must specify the: coin serial (required) – serial number of the exchange reserve account to top up OR withdraw amount (required) – amount to top up OR withdraw bank account number (conditional) – IBAN OR bank account number, required if bank account ID is not provided bank account ID (conditional) – bank account internal identifier, required if bank account number is not provided custom information (optional) – Additional information description (optional) – description for top-up request Top-up/Withdraw Exchange reserve wallet can be performed with the provided bank account ID – it means, that there is a bank account registered in the system and linked with the wallet. If a bank account number OR IBAN was provided – it means, that there is no linked bank account for the current wallet in the system. To accept or decline a request user must specify the identifier of the request. The Status of the Top-up/Withdraw Exchange Reserve operation returns in the response (with other operation details).
A new approach to approve/decline business process requests was implemented. The main idea of the approach is to use general API requests to manage created business process requests for all types of business processes. Currently, it is available only for operations related to `exchange_reserve` coin: top_up and withdraw. Going to be implemented for all other types of business process requests. To Approve and Decline APIs requires two types of permissions: access permission to call the APIs: `BUSINESS_REQUEST_MANAGER` permission to process requests (set of permissions related to the different types of business requests), such as: BUSINESS_REQUEST_EXCHANGE_RESERVE_TOP_UP BUSINESS_REQUEST_EXCHANGE_RESERVE_WITHDRAWAL BUSINESS_REQUEST_BANK_TOP_UP BUSINESS_REQUEST_BANK_WITHDRAWAL BUSINESS_REQUEST_CASH_DESK_TOP_UP BUSINESS_REQUEST_CASH_DESK_WITHDRAWAL BUSINESS_REQUEST_CASH_DESK_CHARGE BUSINESS_REQUEST_CASH_DESK_INVESTMENT BUSINESS_REQUEST_CASH_DESK_COLLECT BUSINESS_REQUEST_CASH_DESK_INPUT BUSINESS_REQUEST_TRANSFER BUSINESS_REQUEST_CURRENCY_EXCHANGE BUSINESS_REQUEST_GATE_CARD_ATTACHMENT BUSINESS_REQUEST_GATE_TOP_UP BUSINESS_REQUEST_GATE_WITHDRAWAL BUSINESS_REQUEST_GATE_PURCHASE BUSINESS_REQUEST_GATE_ISSUE_CARD BUSINESS_REQUEST_MERCHANT_PAYMENT_CASHBACK BUSINESS_REQUEST_MERCHANT_INVOICE_CASHBACK See “API Changes” section of the release notes to know more about changes related to API

New Accounting Model was implemented for all supported operations. It gives an opportunity to see in-system money circulation in the separate wallet balance (type=issuing_balance) on the runtime.

All incomes/outcomes to/from the system circulation (in certain currency) going through the issuing_transit account and issuing_balance account.

Example: all incomes/outcomes to/from the system circulation in Currency1 reflect on the issuing1_balance account and issuing1_transfer account (both accounts have one unique Currency – Currency1)

To reconcile the volume of circulation (in a particular issued Currency, e.g. Currency USD1) compare the balances of the Currency1 issuing1_transfer account with the balance of issuing1_balance account – this balances show a volume of circulation and it must be equal.

The current atomic transactions inside the Business Processes were chnaged according to the schema of technical transactions. If the “integrator” (or “client”) uses the fields from node transactions from the API endpoints POST /transactions/view or GET/transactions/{transactionId} for their system – they should note that the atomic transaction has changed (see schemas below).

Internal operations
Transfer OUT commission

Transfer IN commission

Transfer SHARED commission

Top up via bank

Release Version 4.17.0 (March 1, 2024)

Top up via cash desk

Release Version 4.17.0 (March 1, 2024)

Withdrawal via cash desk

Cash desk investment

Cash desk input

Cash desk collect

Invoice

Merchant payment

Voucher creation

Voucher activation

Currency exchange

Top up exchange reserve

Withdraw exchange reserve

Provider operations (Gate)
Top up via provider total commission>provider commission

Top up via provider total commission<provider commission

Withdrawal via provider total commission>provider commission

Withdrawal via provider total commission<provider commission

Purchase via provider total commission>provider commission

Purchase via provider total commission<provider commission

Issue card

The ability to Top up/Withdraw the Exchange Reserve account was added.

Exchange Reserve account – it is the currency exchange reserve account, used only for Currency Exchange operations (see accounting model description for Currency exchange operation). See “API Changes” section of the release notes to know more about changes related to API

For the Business user to be able to perform currency exchange operations, the Service user (any service user with appropriate permission) must first top up the balances on exchange_reserve wallets for the required currencies.

The Service user (Service role with appropriate permission) can create a request to Top up or Withdraw from the Exchange Reserve account via bank transfer. After the request is created the Service user with appropriate permission must accept or decline a request to process such operation further.

New Business process types were added: exchange_reserve_top_up and exchange_reserve_withdraw

To create Top up/Withdrawal Exchange Reserve Request user must specify the:

coin serial (required) – serial number of the exchange reserve account to top up OR withdraw
amount (required) – amount to top up OR withdraw
bank account number (conditional) – IBAN OR bank account number, required if bank account ID is not provided
bank account ID (conditional) – bank account internal identifier, required if bank account number is not provided
custom information (optional) – Additional information
description (optional) – description for top-up request

Top-up/Withdraw Exchange reserve wallet can be performed with the provided bank account ID – it means, that there is a bank account registered in the system and linked with the wallet. If a bank account number OR IBAN was provided – it means, that there is no linked bank account for the current wallet in the system.

To accept or decline a request user must specify the identifier of the request. The Status of the Top-up/Withdraw Exchange Reserve operation returns in the response (with other operation details).

A new approach to approve/decline business process requests was implemented. The main idea of the approach is to use general API requests to manage created business process requests for all types of business processes. Currently, it is available only for operations related to exchange_reserve coin: top_up and withdraw. Going to be implemented for all other types of business process requests.

To Approve and Decline APIs requires two types of permissions:

access permission to call the APIs: BUSINESS_REQUEST_MANAGER
permission to process requests (set of permissions related to the different types of business requests), such as:

BUSINESS_REQUEST_EXCHANGE_RESERVE_TOP_UP BUSINESS_REQUEST_EXCHANGE_RESERVE_WITHDRAWAL BUSINESS_REQUEST_BANK_TOP_UP BUSINESS_REQUEST_BANK_WITHDRAWAL BUSINESS_REQUEST_CASH_DESK_TOP_UP BUSINESS_REQUEST_CASH_DESK_WITHDRAWAL BUSINESS_REQUEST_CASH_DESK_CHARGE BUSINESS_REQUEST_CASH_DESK_INVESTMENT BUSINESS_REQUEST_CASH_DESK_COLLECT BUSINESS_REQUEST_CASH_DESK_INPUT BUSINESS_REQUEST_TRANSFER BUSINESS_REQUEST_CURRENCY_EXCHANGE BUSINESS_REQUEST_GATE_CARD_ATTACHMENT BUSINESS_REQUEST_GATE_TOP_UP BUSINESS_REQUEST_GATE_WITHDRAWAL BUSINESS_REQUEST_GATE_PURCHASE BUSINESS_REQUEST_GATE_ISSUE_CARD BUSINESS_REQUEST_MERCHANT_PAYMENT_CASHBACK BUSINESS_REQUEST_MERCHANT_INVOICE_CASHBACK

See “API Changes” section of the release notes to know more about changes related to API

Improvements

The ability to update bank account details via UI was added for Individual

How to edit a Bank account via Front-office UI:

Log in as an Individual
Select “Account” (press on the certain account to see linked Bank accounts)
Select the needed bank account to edit and update details:

Use as default bank account
Bank Account Number – conditional field, OR you can provide IBAN in “IBAN”
IBAN – conditional field, provide existing IBAN OR press “Generate IBAN” to get new, generated IBAN and use it as bank account details
Bank ID – required to generate IBAN
Full Name – required

Press “Update bank account”. A bank account will be updated.

[Bank-office] A New Transactions list form for the Administrator was implemented
A default sorting option was added in the UI for all columns of all tables in the Back-office
Filter memory (chips) was added to all tables with filter
Permission ISSUE_CARD_OWNER was added to the Individual role by default
Amount mapping for Withdrawal/top via bank request details was corrected in the UI
The ability to see a list of available APIs (quantity and descriptions) was added to the user login page
The organization type for all gate-provider wallets was changed to “gate”
Commission amounts field mapping was corrected for Merchant payment and Invoice operations
The view of user notes in JSON format was changed on the UI
DB migrations were performed (scripts for manual DB migrations were created to have appropriate DB for test and pre-prod environments)
Set up a Total commission less than the Provider for Gate operations were allowed on the UI
The mapping for Transactions list form (Administrator view) was corrected
Performing in-system operations (transfer, bank top-up, etc.) if the commission rule is inactive was prohibited

Fixes

The issue with the error message when trying to perform a transfer using an invalid card number was fixed. The message was changed from the validator.transfer.card_not_found=A user with this email is not found to the validator.transfer.card_not_found=A card is not found
The issue with wrong commission wallets are using for the operations of Merchant users was fixed. Commission for Merchant operations is collected on the “business_system_commission“ and “business_gate_ commission“ wallets
Front-end issues with the Transactions table component were fixed
Displaying dashes when there is no info about some fields in API response was added to Individual’s Transactions
The issue with placement of “Close” button in wide modal windows was fixed
The schema of POST /v1/exchange response was changed in Swagger
The issue with limits for invoices, currency exchanges, and top via bank operations was fixed
The page on the success of the Currency exchange operation was added
Filter by “Type” for “Currency exchange” operation was fixed on the Transaction List for the Merchant role
The issue with operational time for all operations in Individual’s Transactions List was fixed

API Changes


Endpoint	Updated
POST /v1/exchange	Response were changed: children business processes (withdraw and top_up) was removed field `exchangeDirectionType` : possible options `SELL` \| `BUY` was added `type` for Exchange Operation Business process was changed to `exchange_transaction`
PATCH {{host}}/profiles/{userId}/additional PATCH {{host}}/profiles/my/additional	Value for field `type` in the `additional` in the request and response was changed `common` changed to `CommonProfileExtDto` `raw` changed to `RawProfileExtDto` `{ "additional": { "type": "CommonProfileExtDto", ... } }`
Endpoint	Added
POST /v1/exchange/reserve-top-up/create-request	For the Business user to be able to perform currency exchange operations, the Service user (any service user with appropriate permission) must first top up the balances on exchange_reserve wallets for the required currencies. Use this API to create a request to top up exchange_reserve wallet. The request will be created, but money will be loaded to the wallet when the request is confirmed. In the response, you will receive a `requestIdentifier` along with exchange reserve top-up details. Pass `requestIdentifier` to the APIs to approve or decline request to top up exchange_reserve wallet. Permission to call this API: `BUSINESS_REQUEST_EXCHANGE_RESERVE_TOP_UP`. Request body: `{ "coinSerial": "string", "amount": 0, "bankAccountId": "string", "bankAccountNumber": "string", "description": "string", "customInformation": "string" }` Response body: `{ "records": [ { "identifier": 12345, "status": "waiting_for_approval", "businessProcessId": "9ac46353-c9a6-4979-8d2e-a9e6c0dd0419", "businessProcessType": "exchange_reserve_top_up", "businessProcessStatus": "pending" } ] }` To approve/decline/view business request call corresponding APIs: `POST /business-requests/{requestIdentifier}/approve`, `POST /business-requests/{requestIdentifier}/decline`, `POST /business-requests`
POST /v1/exchange/reserve-withdrawal/create-request	Use this API to create a request to withdraw exchange_reserve wallet. The request will be created, but money will be withdrawn from the wallet when the request is confirmed. In the response, you will receive a requestIdentifier along with exchange reserve withdrawal details. Pass requestIdentifier to the APIs to approve or decline request to withdraw exchange_reserve wallet. Permission to call this API: `BUSINESS_REQUEST_EXCHANGE_RESERVE_WITHDRAWAL` Request body: `{ "coinSerial": "string", "amount": 0, "bankAccountId": "string", "bankAccountNumber": "string", "description": "string", "customInformation": "string" }` response body: `{ "records": [ { "identifier": 12345, "status": "waiting_for_approval", "businessProcessId": "9ac46353-c9a6-4979-8d2e-a9e6c0dd0419", "businessProcessType": "exchange_reserve_withdraw", "businessProcessStatus": "pending" } ] }` To approve/decline/view business request call corresponding APIs: `POST /business-requests/{requestIdentifier}/approve`, `POST /business-requests/{requestIdentifier}/decline`, `POST /business-requests`
POST /business-requests/{requestIdentifier}/approve	Use this API to approve requests to top up/withdraw exchange_reserve wallet. Business request identifier. `requestIdentifier` is returned in the API response for POST `/business-requests` in field `id`. Permissions to call this API: `BUSINESS_REQUEST_MANAGER` `BUSINESS_REQUEST_EXCHANGE_RESERVE_TOP_UP` - for top up request `BUSINESS_REQUEST_EXCHANGE_RESERVE_WITHDRAWAL` - for withdrawal request Response body: `{ "records": [ { "identifier": 12345, "status": "approved", "businessProcessId": "9ac46353-c9a6-4979-8d2e-a9e6c0dd0419", "businessProcessType": "exchange_reserve_topup", "businessProcessStatus": "processed" } ] }`
POST /business-requests/{requestIdentifier}/decline	Use this API to decline requests to top up/withdraw exchange_reserve wallet. Business request identifier. `requestIdentifier` is returned in the API response for POST `/business-requests` in field `id`. Permissions to call this API: `BUSINESS_REQUEST_MANAGER` `BUSINESS_REQUEST_EXCHANGE_RESERVE_TOP_UP` - for top up request `BUSINESS_REQUEST_EXCHANGE_RESERVE_WITHDRAWAL` - for withdrawal request Response body: `{ "records": [ { "identifier": 12345, "status": "declined", "businessProcessId": "9ac46353-c9a6-4979-8d2e-a9e6c0dd0419", "businessProcessType": "exchange_reserve_topup", "businessProcessStatus": "rejected" } ] }`
POST /business-requests	Use this API to view pending business requests to top up/withdraw exchange_reserve wallet with filter and pagination. Available filter: identifiers - business request identifier statuses - business request status businessProcessTypes - business process type Permission to call this API: `BUSINESS_REQUEST_MANAGER` for Service roles `BUSINESS_REQUEST_VIEWER` for Business roles Request body: `{ "pageNumber": 0, "pageSize": 10, "filter": { "identifiers": [ 202802890 ], "statuses": [ "limited" ], "businessProcessTypes": [ "exchange_reserve_top_up" ] }, "sort": { "date": "asc" } }` Response body: `{ "pageNumber": 0, "pageSize": 10, "totalPages": 1, "totalRecords": 10, "records": [ { "identifier": 12345, "status": "limited", "businessProcessId": "9ac46353-c9a6-4979-8d2e-a9e6c0dd0419", "businessProcessType": "bank_topup", "businessProcessStatus": "limited" } ] }`
Endpoint	Deprecated/Deleted