Freedom Pay
  1. Transfer
Freedom Pay
  • Overview
  • Gateway API
    • Overview
    • Sync API
      • Overview
      • Purchase
        • Overview
        • Create payment
        • Any amount
        • Card
        • 3DSecure
        • Cancel
        • Clearing
        • Refund
        • Status
      • Payout
        • Overview
        • Card
        • IBAN
        • Balance
        • Status
      • Transfer
        • Overview
        • Card
        • 3DSecure
        • Rates
        • Status
      • Card
        • Overview
        • Add
        • 3DSecure
        • List
        • Remove
        • Status
      • Token
        • Overview
        • Token Pay
        • Apple Pay
        • Google Pay
        • Token Payout
        • Status
    • Async API
      • Overview
      • create
        • create payment
        • create payment recurrent
      • read
        • read payment
        • read request
      • edit
        • edit payment.refund
        • edit payment.reverse
        • edit payment.clearing
      • delete
  • Merchant API
    • Overview
    • Purchase
      • Overview
      • Checkout
      • Card token
        • Overview
        • Tokenize card
        • Delete token
        • Card token list
        • Create payment (with CVC)
        • Confirm payment (with CVC)
        • Create payment
        • Confirm payment
      • Create payment
      • Any amount
      • Cancel payment
      • Clearing
      • Refund payment
      • Status
    • Payout
      • Overview
      • Card token
        • Tokenize card
        • Delete token
        • Card token list
        • Create payment
      • Create payment
      • IBAN
      • Balance status
      • Status by order_id
      • Status by Payment ID
      • Status
    • Mobile balance
      • Overview
      • Init
      • Pay
      • Approve
      • Resend code
      • Status
    • Invoice
      • Overview
      • Init
      • Info
      • Pay
      • Status
    • SDK
      • JS SDK
      • Google Pay
      • Freedom QR
        • Reader SDK (Android)
        • Provider SDK (Android)
      • Payment SDK
        • iOS
        • Android
    • CMS
      • Overview
      • Get Merchant ID and key
      • WordPress
        • Overview
        • Installation
        • Configuration
        • Test
        • Live payments
        • Update
      • Tilda
        • Overview
        • Installation
        • Configuration
        • Test
        • Live payments
      • InSales
        • Overview
        • Installation
        • Configuration
        • Test
        • Live payments
      • Ecwid
        • Overview
        • Installation
        • Configuration
        • Test
        • Live payments
      • Bitrix
        • Overview
        • Installation
        • Configuration
        • Test
        • Live payments
      • PrestaShop
        • Overview
        • Installation
        • Configuration
        • Test
        • Live payments
      • OpenCart
        • Overview
        • Installation
        • Configuration
        • Test
        • Live payments
    • Redirect back
    • Result notify
    • Payout notify
    • Check request
  • Card API
    • Overview
    • Payment Cards
      • Overview
      • Dictionaries
      • Bulk issue
      • Issue card
      • Issue plastic card
      • Activate card
      • Block card
      • Unblock card
      • Set PIN
      • Reset PIN counter
      • Close card
      • Update client
      • Card info
      • Balance
      • Secret data
      • Secret data (version 2)
      • Statement
      • Statement extended
      • Create client
      • Edit client
      • Сards' list
      • Request' status
      • Create transaction
      • Clearing transaction
      • Refund transaction
      • Transaction request' status
      • Transaction info
    • Gift Cards
      • Overview
      • List
      • Issue
      • Confirm
      • Resend
      • Resend code
      • Status
  • Partner API
    • Rates
      • Overview
      • Rates
    • Products
      • Overview
      • Dictionaries
      • Add client with product
      • Request status
    • E-Money
      • Overview
      • Add
      • Owner identification
      • Info
      • Close
      • Block
      • Balance
      • Statement
      • Request Status
    • Freedom ID
      • Overview
      • Design
      • iOS SDK
      • Android SDK
      • OAuth2
        • Authorization link
        • Token exchange
        • Token refresh
        • User info
        • Request profile
        • Get profile status
        • Create user
        • Update user
      • OIDC
        • Authorization endpoint
        • Token exchange
        • Userinfo
      • Error codes
      • Examples
        • Keycloak
    • Transfer
      • Overview
      • Get token
        POST
      • Refresh token
        PATCH
      • Get agents
        GET
      • Fees
        POST
      • Create person
        POST
      • Create business
        POST
      • Create transfer
        POST
      • Print application
        POST
      • Confirm
        POST
      • Search
        POST
      • Payout
        POST
      • Payout confirm
        POST
      • Cancel
        POST
      • Get person info
        POST
      • Get business info
        POST
      • Status
        GET
      • Info
        GET
    • Device ID
      • Android SDK
      • iOS SDK
  1. Transfer

Overview

General information#

International Money Transfer System is a comprehensive international money transfer system designed to facilitate fast, secure, and efficient cross-border transfers between persons and businesses.

Transfer Types:
On-Demand Transfers
For scenarios where the sender does not specify a particular receiving agent (bank or financial institution) at the time of transfer initiation. Instead, the transfer is made available "on-demand" across all authorized agents within the recipient's country. This model provides maximum convenience and flexibility for recipients.
Use Case:
Ideal for situations where the recipient may not have a designated bank account or prefers to collect the funds at their convenience from a wide network of agents (e.g., exchange offices, cash desks, retail points).
Phone-Based Transfers
For scenarios where the sender wants to direct funds to a specific receiving agent. This approach is often required when the sender has prior knowledge of the recipient’s bank or financial institution and wants to ensure funds are delivered to that particular entity.
Use Case:
Ideal for transfers where the recipient prefers to receive funds directly into their bank account, card, or when the sender specifies a particular agent for payout (e.g., corporate clients, payroll disbursements, direct-to-account payments).

How It Works#

Transfer Process#

Commission Calculation
The system calculates the applicable commission based on sender type, destination country, transfer amount, and currency pair.
Client - sender Registration
The partner must register the client - sender (individual or company) in the IMTS system.
Transfer Creation
After the client -sender is registered, the transfer can be created.
Fees are recalculated and the transfer status is set to “new”.
Transfer Confirmation
The partner confirms the transfer by initiating processing.
The results of the client AML check determine whether the transfer can proceed.
Transfer payout
The recipient client’s identity is verified and the transfer is paid after the client’s AML check is successful.
Payout confirmation
After the payout, the transfer status is updated to “successful”.
Cancellation and status check
Partners can cancel transfers or check the status of transfers at any time using dedicated API methods.

Interaction scheme: On-Demand Transfers#

Фин. взаимодействие МСДП-в страну, до востребования.drawio.png

Interaction scheme: Phone-Based Transfers#

Фин. взаимодействие МСДП-Копия в страну, до востребования.drawio.png

Partner Service Registration#

 To work with the IMTS API, a partner service needs credentials (Login and Password). These can be obtained by contacting the product support team via email: support@freedompay.kz.
Your email should include:
Service Name
Platforms (e.g., web, iOS, Android)
Contact Information of responsible personnel

Example Email
Subject: Request for Service Integration with IMTS API  

Dear IMTS  Support Team,  

My name is [Your Name], representing the platform [Your Company Name]. We aim to integrate our service with the IMTS API for unified user authorization.  

Service Name: [Your Service Name]  
Platforms: [Platform List]  
Contact Details:  
- Name: [Responsible Person's Name]  
- Position: [Position]  
- Email: [Email Address]  
- Phone: [Phone Number] 

Request Signature#

The request signature (pg_sig) is a cryptographic hash generated to ensure the integrity and authenticity of the request. It helps verify that the request data was not tampered with during transmission and that it was genuinely created by an authorized partner.

Operation Principle#

The Agent forms a request and adds the necessary parameters.
A signature is generated on the agent-side based on specific fields and a secret key.
The request is sent to the IMTS API.
The IMTS API verifies the signature and checks the integrity of the data.

Request Signature Generation#

The request signature is calculated as follows:
Forming the Request String
Only significant parameters are used, excluding null and empty values.
Parameters are sorted alphabetically by their keys.
Field values are concatenated using a semicolon ;.
Generating the Hash
The secret key provided by the manager during integration with IMTS agent_secret is appended to the resulting string.
The HMAC-SHA256 algorithm is applied to generate the signature.
Adding the Signature to the Request
The generated signature (pg_sig) is included in the request body.

Signature Generation Examp:#

1. Forming the String for Signature
Exclude null and empty parameters.
Sort parameters alphabetically:
amount_from=100.50
currency_code_from=USD
order_id=ORD123456
pg_salt=random_string
receiver_country=KZ
transfer_purpose=Family support
transfer_type=send
2. Concatenate values using semicolons
100.50;USD;ORD123456;KZ;Family support;send
3. Add the secret key (agent_secret)
100.50;USD;ORD123456;KZ;Family support;send;agent_secret
4. Generating the Signature
Apply HMAC-SHA256:
hmac_sha256("100.50;USD;ORD123456;KZ;Family support;send;agent_secret")
5. Example of the generated hash:
5a1d5f17e4c1f5a3b44c3f29b5e2d77cd11b1b5fefc3dcb5b1c2f8e73f9c22a1

Encryption#

To ensure the security of personal data transferred between IMTS and its partners, all personal data must be encrypted. This process uses symmetric encryption with a predefined partner_key.
partner_key - generated during the initial integration with IMTS and issued by the IMTS manager to the Agent
Encryption requirements
Encryption Method: Symmetric Data Encryption
Algorithm: AES (Advanced Encryption Standard)
Key Length: 256 bits
Encryption Key: partner_key (Provided by IMTS during integration)
Mode of Operation: AES-256-CBC (Cipher Block Chaining)
nitialization Vector (IV): Randomly generated for each encryption operation (recommended size: 16 bytes)

Encryption Process (For Sending Data to IMTS)#

Generate Initialization Vector (IV). This should be randomly generated for each encryption operation and have a length of 16 bytes.
Encrypt the data using the partner_key and the IV with AES-256-CBC mode.
Encode the encrypted data and IV in Base64 format before transmission.
Send the encrypted_data to IMTS.

Decryption Process (For Receiving Data from IMTS)#

Receive the encrypted_data and decode from Base64.
Extract the IV and encrypted data.
Decrypt the data using the same partner_key and IV with AES-256-CBC mode.
Retrieve the original data.

Callbacks#

For the IMTS service to be able to send a callback, the Partner (agent) must send a URL to IMTS, which the IMTS service will contact to send notifications.
Universal notification service:
IMTS sends notifications to the Partner (agent) URL about a change in the status of a transfer or the receipt of a transfer by phone number, IBAN or PAN (in the future, the list of available notifications may be enriched).

Notification examples:#

Notification about a change in the status of a transfer status_update:
Notification of receipt of transfer
Expected response from Partner

When is the callback called?#

When the transfer status was changed.
When the parameter agent_id (Unique identifier of the recipient agent) was passed during the transfer registration request.
Retry :
In case of no response from the partner IMTS will send Retry every 15 minutes, 3 times.

Statuses#

The IMTS system provides transfer statuses, which change depending on the operations performed.

Main statuses#

StatusDescription
newNew transfer created via API /v5/partner/transfer/create
processThe transfer is in the process of being processed, awaiting client registration and AML verification.
waitingThe transfer has been successfully confirmed and is ready for payout.
successThe transfer has been successfully payout.
canceledThe transfer was cancelled by the user via API /v5/partner/transfer/cancel
errorError confirming transfer or AML verification of client.

How it works#

1.
Creating a transfer:
API: /v5/partner/transfer/create
status = new
2.
Confirming a transfer:
API: /v5/partner/transfer/confirm
If the client-originator has passed the AML check (approved), the transfer goes to the process status.
If the client has not passed the AML check (rejected), the transfer gets the error status.
3.
Registering the transfer payout:
API: /v5/partner/transfer/payout
If the client-destination has passed the AML check (approved), the transfer goes to the waiting status
If the client has not passed the AML check (rejected), the transfer gets the error status.
4.
Confirming the transfer payout:
API: /v5/partner/transfer/payout/confirm
The transfer gets the final status: success.
5.
Cancelling a transfer:
API: /v5/partner/transfer/cancel
A transfer can be cancelled from any of the new, process, waiting statuses and goes into the canceled status.
Diagram
Blank diagram - Page 1 (2).png
Previous
Keycloak
Next
Get token