Freedom Pay

https://docs.freedompay.kz
Admin
Freedom Pay is a payment gateway platform providing APIs for processing payments, payouts,...
Tokens:228,695
Snippets:1,431
Trust Score:7.5
Update:1 month ago
Show doc for...
Tokens:
Raw
### Initialize PayButton and PaymentsClient in Kotlin

Source: https://docs.freedompay.kz/android-1368420m0

Initialize the PayButton and create a PaymentsClient using Wallet.getPaymentsClient. The environment can be set to ENVIRONMENT_PRODUCTION or ENVIRONMENT_TEST; the example uses production.

```kotlin
val googlePayButton: PayButton = findViewById(R.id.buttonPaymentByGoogle)
googlePayButton.initialize(
    ButtonOptions.newBuilder()
        .setButtonType(ButtonType.CHECKOUT)
        .setButtonTheme(ButtonTheme.LIGHT)
        .build()
)

val googlePaymentsClient = Wallet.getPaymentsClient(
    this,
    Wallet.WalletOptions.Builder()
        .setEnvironment(WalletConstants.ENVIRONMENT_PRODUCTION)
        .setTheme(WalletConstants.THEME_LIGHT)
        .build()
)
```

--------------------------------

### Initiate Apple Pay with createApplePayment

Source: https://docs.freedompay.kz/ios-1820483m0

Use this method to start an Apple Pay transaction by providing a StandardPaymentRequest. The result callback handles success by storing the paymentId or logs errors.

```swift
func createApplePayment() {
    let standardPaymentRequest = StandardPaymentRequest(
        amount: Decimal(10.0),
        currency: .KZT,
        description: "some description",
        userId: "123",
        orderId: "456",
        extraParams: nil)
    freedomApi.createApplePayment(
        paymentRequest: standardPaymentRequest
    ) { result in
        switch result {
        case .success(let applePayment):
            self.paymentId = applePayment.paymentId
        case .error(let error):
            print("Apple Payment failed: \(error)")
        }
    }
}
```

--------------------------------

### makeRevokePayment refund example

Source: https://docs.freedompay.kz/android-1368420m0

Use to process a full or partial refund for a completed payment. The paymentId is required; amount is optional and defaults to null (full refund). The callback receives a FreedomResult<PaymentResponse> that is either Success or Error.

```kotlin
freedomApi.makeRevokePayment(paymentId = 123456L) { result: FreedomResult<PaymentResponse> ->
    when (result) {
        is FreedomResult.Success -> {
            // Refund process completed successfully.
        }
        is FreedomResult.Error -> {
            // Failed to process the refund.
        }
    }
}
```

--------------------------------

### SDK Initialization

Source: https://docs.freedompay.kz/js-sdk-869917m0

Add the SDK script to the head of your site and set your public key and token.

```APIDOC
## SDK Initialization

### Description
Add the SDK script to the head of your site and set your public key and token.

### Script Tag
```html
<script>
  (function (f, p, s, d, k) {
    d = f.createElement(p);
    k = f.getElementsByTagName(p)[0];
    d.src = 'https://cdn.freedompay.kz/sdk/js-sdk-1.0.0.js';
    k.parentNode.insertBefore(d, k);
  })(document, 'script');
</script>
```

### Setup
```javascript
FreedomPaySDK.setup('mypublickey', 'mytoken');
```

### Parameters
- **publickey** (string) - Required - Public key obtained from your manager.
- **token** (string) - Required - Token obtained from your manager.
```

--------------------------------

### 200 response body with partners array

Source: https://docs.freedompay.kz/get-partners-41316452e0

Example 200 response body for the GET /v5/installment/partners endpoint. Contains an array of partner banks, each with a code, name, logo, products (installment or loan programs), and amount limits. The currency is determined automatically by the host (e.g., .kz→KZT, .uz→UZS, .kg→KGS).

```json
{
    "partners": [
        {
            "code": "anorbank",
            "name": "Anorbank",
            "logo": "https://cdn.freedompay.kz/logos/anorbank.png",
            "products": [
                {
                    "term_months": 12,
                    "calculation_rate": 0.095,
                    "type": "installment",
                    "amount_limits": {
                        "currency": "UZS",
                        "min": 100000,
                        "max": 30000000
                    }
                },
                {
                    "term_months": 6,
                    "calculation_rate": 0.095,
                    "type": "credit",
                    "amount_limits": {
                        "currency": "UZS",
                        "min": 100000,
                        "max": 30000000
                    }
                }
            ]
        }
    ]
}
```

--------------------------------

### Get Partners

Source: https://docs.freedompay.kz/get-partners-41316452e0

Retrieves a list of partner banks with their installment programs, amount limits, and logos.

```HTTP
GET /v5/installment/partners
```

```JSON
{
    "X-Request-Id": "string"
}
```

```JSON
{
    "partners": [
        {
            "code": "anorbank",
            "name": "Anorbank",
            "logo": "https://cdn.freedompay.kz/logos/anorbank.png",
            "products": [
                {
                    "term_months": 12,
                    "calculation_rate": 0.095,
                    "type": "installment",
                    "amount_limits": {
                        "currency": "UZS",
                        "min": 100000,
                        "max": 30000000
                    }
                },
                {
                    "term_months": 6,
                    "calculation_rate": 0.095,
                    "type": "credit",
                    "amount_limits": {
                        "currency": "UZS",
                        "min": 100000,
                        "max": 30000000
                    }
                }
            ]
        }
    ]
}
```

--------------------------------

### Configure SDK with publickey and token

Source: https://docs.freedompay.kz/js-sdk-869917m0

Call this after the SDK is loaded to set your public key and token, which are obtained from your manager.

```javascript
FreedomPaySDK.setup('mypublickey', 'mytoken');
```

--------------------------------

### Full integration example for FreedomPay JS SDK

Source: https://docs.freedompay.kz/js-sdk-869917m0

Complete HTML page that loads the FreedomPay SDK, sets up with public key and token, and handles a one-step payment with optional 3DS confirmation. Includes placeholder functions for UI feedback and validation.

```html
<html lang="en">
 <head>
 <meta charset="UTF-8">
 <meta http-equiv="X-UA-Compatible" content="IE=edge">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 <script>
 (function (f, p, s, d, k) {
 d = f.createElement(p);
 k = f.getElementsByTagName(p)[0];
 d.src = 'https://cdn.freedompay.kz/sdk/js-sdk-1.0.0.js';
 k.parentNode.insertBefore(d, k);
 })(document, 'script');
 </script>
</head>
<body>
<div id="3dsForm"></div>
<button onclick="pay()">Pay</button>
<script>
window.onload = function () {
FreedomPaySDK.setup('mypublickey', 'mytoken');
}

async function pay() {
validateMyForm();

const JSPaymentOptions = {
order_id: "my-order", // must be unique for each request
auto_clearing: 0,
amount: 20,
currency: "KZT",
description: "Order description",
test: 0,
options: {
custom_params: {},
user: {
email: "client@email.com",
phone: "+77777777777"
}
},
};

const JSTransactionOptionsBankCard = {
 type: 'bank_card',
 options: {
 card_number: "11111111111111",
 card_holder_name: "test",
 card_exp_month: "09",
 card_exp_year: "25",
 card_cvv: 123
 }
 };

 try {
 setLoading(true);

 let JSPayResult = await FreedomPaySDK.charge(
 JSPaymentOptions, JSTransactionOptionsBankCard
 );

 if (JSPayResult.payment_status === "need_confirm") {
 showPopup('3dsFormWrapper');

 JSPayResult = await FreedomPaySDK.confirmInIframe(JSPayResult, "3dsForm");
 }

// open the payment result page, etc.
// ...
console.log(JSPayResult);

} catch(JSErrorObject) {
// Handle JSErrorObject.response
setLoading(false);
showError(JSErrorObject);
}
}

// optional functions, needed as an example
function showPopup(id) {
// open a pop-up window
}

function setLoading(status) {
// trigger for loading, form overlap, button blocking
}

function showError(error) {
// show the error
}

function validateMyForm() {
// validate the data entered by the user, for example, card data
}
</script>
</body>
</html>
```

--------------------------------

### GET /v5/partner/account/statement - Example Request

Source: https://docs.freedompay.kz/statement-28325776e0

Example request to generate a statement. The query parameters include account_number, date_start, date_end, and format. The date range must be within 30 calendar days and times must be in UTC (Z suffix).

```http
GET /v5/partner/account/statement?account_number=KZ123456789012345678&date_start=2026-01-01T00: 00: 00Z&date_end=2026-01-26T23: 59: 59Z&format=xlsx

```

--------------------------------

### GET /installment/status

Source: https://docs.freedompay.kz/application-status-41331029e0

Retrieves the current status of an installment application. The response includes application details such as status, approved amount, currency, and bank code.

```APIDOC
## GET /installment/status

### Description
Retrieves the current status of an installment application. The response includes application details such as status, approved amount, currency, and bank code.

### Method
GET

### Endpoint
/installment/status

### Parameters
#### Query Parameters
- **id** (string) - Required - The unique identifier of the application.
- **external_id** (string) - Required - The external identifier of the application.

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the application.
- **external_id** (string) - The external identifier of the application.
- **status** (string) - The current status of the application (e.g., new).
- **approved_amount** (number) - The approved amount for the installment.
- **currency** (string) - The currency of the approved amount (e.g., UZS, KZT, KGS).
- **bank_code** (string) - Code of the selected bank (Partner.code).
- **created_at** (string) - Date and time the application was created.
- **updated_at** (string) - Date and time of the last status change.

#### Response Example
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "external_id": "string",
  "status": "new",
  "approved_amount": 1500000,
  "currency": "UZS",
  "bank_code": "anorbank",
  "created_at": "2019-08-24T14:15:22.123Z",
  "updated_at": "2019-08-24T14:15:22.123Z"
}
```

--------------------------------

### OpenAPI specification for balance status endpoint

Source: https://docs.freedompay.kz/balance-status-28448094e0

Defines the GET /v5/partner/account/balance/status/{requestId} endpoint with request and response examples. Includes security scheme 'card-api' (JWT bearer) and server URLs for KZ, UZ, and KG environments.

```yaml
openapi: 3.0.1
info:
  title: ''
  description: ''
  version: 1.0.0
paths:
  /v5/partner/account/balance/status/{requestId}:
    get:
      summary: Balance status
      deprecated: false
      description: ''
      tags:
        - Partner API/Account
      parameters:
        - name: requestId
          in: path
          description: ''
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties: {}
            example: >-
              GET https:
              //api.freedompay.kz/v5/partner/account/balance/status/9b2d7c1a-3e3a-4e55-9d13-92b2f77e9999
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties: {}
              example:
                requestId: 9b2d7c1a-3e3a-4e55-9d13-92b2f77e9999
                status: process
                message: The balance is still being generated.
                dt: '2026-01-26T06:30:00Z'
          headers: {}
          x-apidog-name: Accepted
        x-200:OK:
          description: >-
            - All date and time values used in the API **must be sent and
            returned in UTC (UTC+0)** using the ISO 8601 standard with the `Z`
            suffix
          content:
            application/json:
              schema:
                type: object
                properties:
                  account_number:
                    type: string
                    description: >-
                      account_number of the account for which the balance was
                      requested
                  dt:
                    type: string
                    description: >-
                      Date and time in ISO 8601 format (UTC), e.g.
                      `2025-12-22T10:00:00Z`
                  balances:
                    type: array
                    items:
                      type: string
                    description: >-
                      Array of balance objects per currency for the given
                      account_number
                  balances[].currency:
                    type: string
                    description: Currency code in ISO 4217 format (e.g. `KZT`, `USD`)
                  balances[].amount:
                    type: string
                    description: >-
                      Balance amount for the given currency at time dt (e.g.
                      `123456.78)
                x-apidog-orders:
                  - account_number
                  - dt
                  - balances
                  - balances[].currency
                  - balances[].amount
                required:
                  - account_number
                  - dt
                  - balances
                  - balances[].currency
                  - balances[].amount
              example:
                requestId: 9b2d7c1a-3e3a-4e55-9d13-92b2f77e9999
                dt: '2025-12-22T10:00:00Z'
                status: success
                data:
                  account_number: KZ123456789012345678
                  balances:
                    - currency: KZT
                      amount: 123456.78
          headers: {}
          x-apidog-name: OK
        x-200:ERROR:
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties: {}
              example:
                requestId: 9b2d7c1a-3e3a-4e55-9d13-92b2f77e9999
                status: error
                message: Please create a new balance request.
                dt: '2026-01-26T07:30:00Z'
          headers: {}
          x-apidog-name: ERROR
      security: []
      x-apidog-folder: Partner API/Account
      x-apidog-status: released
      x-run-in-apidog: https://app.apidog.com/web/project/640842/apis/api-28448094-run
components:
  schemas: {}
  securitySchemes:
    card-api:
      type: jwt
      scheme: bearer
      bearerFormat: JWT
      x-apidog:
        addTokenTo: header
        headerPrefix: Bearer
servers:
  - url: https://api.freedompay.kz
    description: KZ
  - url: https://api.freedompay.uz
    description: UZ
  - url: https://api.freedompay.kg
    description: KG
security: []
```

--------------------------------

### Present Payment Sheet

Source: https://docs.freedompay.kz/ios-1820483m0

Initialize and present the PKPaymentAuthorizationViewController to the user.

```swift
@objc func applePayButtonTapped() {
    let paymentRequest = createPaymentRequest()
    guard let paymentVC = PKPaymentAuthorizationViewController(paymentRequest: paymentRequest) else {
        print("Error: Unable to present Apple Pay sheet.")
        return
    }
    paymentVC.delegate = self
    self.present(paymentVC, animated: true, completion: nil)
}
```

--------------------------------

### OpenAPI mark_list value examples for payment counts

Source: https://docs.freedompay.kz/create-payment-9890787e0

Shows the mark_list parameter value format: a single code for count=1 and two comma-separated codes for count=2. Used to specify custom payment descriptions per installment count.

```text
"mark_list": ["code1"]
```

```text
"mark_list": ["code1", "code2"]
```

--------------------------------

### Initialize Device ID SDK with DeviceID.create(context)

Source: https://docs.freedompay.kz/android-sdk-966303m0

Initializes the Device ID SDK by calling the create method with an Android context. The context parameter is required.

```kotlin
val context = Context
val deviceID = DeviceID.create(context)
```

--------------------------------

### Create application request body (POST /v5/installment/applications)

Source: https://docs.freedompay.kz/create-application-41328080e0

Example request body for creating an installment application. The phone field must be a JWE-encrypted value using PBES2-HS512+A256KW and A256GCM with the merchant's secret_key; encryption is performed before signing the body.

```json
{
    "external_id": "TGR1234",
    "total_amount": 1500000,
    "currency": "UZS",
    "goods": [
        {
            "name": "Смартфон Xiaomi Poco F3 256/8GB",
            "price": 1500000,
            "quantity": 1,
            "category": "electronics"
        }
    ],
    "customer": {
        "phone": "eyJhbGciOiJQQkVTMi1IUzUxMitBMjU2S1ciLCJlbmMiOiJBMjU2R0NNIiwicDJzIjoiLi4uIiwicDJjIjo2NTUzNn0....."
    },
    "callback_url": "https://shop.uz/fp/status-callback"
}
```

--------------------------------

### Curl example for init_payment.php with signature formation

Source: https://docs.freedompay.kz/overview-741636m0

Curl example for initiating a payment with the FreedomPay API. The signature is formed by concatenating the script name, fields in alphabetical order, and the secret key, then hashing with MD5. The signature is passed as pg_sig.

```bash
curl --location --request POST 'https://api.freedompay.kz/init_payment.php' \
--form 'pg_order_id=23' \
--form 'pg_merchant_id={{paybox_merchant_id}}' \
--form 'pg_amount=25' \
--form 'pg_description=Order description' \
--form 'pg_salt=some_random_string' \
--form 'pg_sig={{paybox_signature}}'
# Signature Formation:
'init_payment.php;25;Order description;{{paybox_merchant_id}};23;some_random_string;{{secret_key}}'
```

--------------------------------

### OpenAPI specification for batch statuses endpoint

Source: https://docs.freedompay.kz/batch-statuses-24102332e0

OpenAPI 3.0.1 specification for the GET /v5/partner/settlement-partitions/batch/{OrgnlMsgId}/status endpoint. Defines the path parameter OrgnlMsgId (1–35 characters, alphanumeric with hyphen/underscore), the 200 response with an XML example, and three servers (KZ, UZ, KG).

```yaml
openapi: 3.0.1
info:
  title: ''
  description: ''
  version: 1.0.0
paths:
  /v5/partner/settlement-partitions/batch/{OrgnlMsgId}/status:
    get:
      summary: Batch statuses
      deprecated: false
      description: "| XML Tag            | Type    | Required  | Description    | Constraints  |\n|----------------|---------|-------------|-------------|-------------|\n|**OrgnlMsgId**|string\t|+\t|Identifier of the original message from `pain.001`\t|\t1–35 characters, alphanumeric, may include hyphen (-) and underscore (_)\t|"
      tags:
        - Partner API/Account
      parameters:
        - name: OrgnlMsgId
          in: path
          description: ''
          required: true
          schema:
            type: string
      responses:
        '200':
          description: "|Tag|Name |Description|\n|---|---|---|\n|**GrpHdr**\t|\t\n|\\<MsgId>|\tMessage ID\t|Unique message identifier|\n|\\<CreDtTm>|\tCreation Date Time\t|Report creation date and time|\n|**OrgnlGrpInfAndSts**\t|\n|\\<OrgnlMsgId>|\tOriginal Message ID\t|Unique ID of the original request message (pain.001)|\n|\\<OrgnlMsgNmId>|\tOriginal Message Name ID\t|Indicates the type of the original message (e.g., pain.001.001.14)|\n|\\<GrpSts>|\tGroup Status\t|Status of the batch (e.g., ACCP, RJCT, PART, PDNG)|\n|**OrgnlPmtInfAndSts**\t|\n|\\<OrgnlPmtInfId>|\tOriginal Payment Info ID\t|ID of the payment information section from pain.001|\n|\\<TxInfAndSts>/\\<EndToEndId>|\tEnd-to-End ID\t|Unique identifier of the individual payment instruction|\n|\\<TxInfAndSts>/\\<TxSts>|\tTransaction Status\t|Payment processing status (e.g., ACCP, RJCT, PDNG)|\n|\\<TxInfAndSts>/\\<AcctSvcrRef>|\tAccount Servicer Reference\t|Internal identifier assigned by the servicing bank to the transaction|\n\n"
          content:
            application/xml:
              schema:
                type: object
                properties: {}
                x-apidog-orders:
                  - 01K9S7D62SPYQD20HX64RPF1P6
              example: "{\r\n\"status\": \"success\",\r\n\"error_code\": 0,\r\n\"error_description\": \"\",\r\n\"document_type\": \"iso20022\",\r\n\"document_body\": \"\r\n<?xml version=\\\"1.0\\\" encoding=\\\"UTF-8\\\"?>\\n\r\n<Document xmlns=\\\"urn:iso:std:iso:20022:tech:xsd:pain.002.001.14\\\">\\n  \r\n    <CstmrPmtStsRpt>\\n    \r\n        <GrpHdr>\\n      \r\n            <MsgId>k221YIoYrWbIbAnP133a07B5wmpEcJSOQ6X</MsgId>\\n\r\n            <CreDtTm>2025-11-05T10:40:24+00:00</CreDtTm>\\n\r\n        </GrpHdr>\\n\r\n        <OrgnlGrpInfAndSts>\\n      \r\n            <OrgnlMsgId>batch-payment-002</OrgnlMsgId>\\n\r\n            <OrgnlMsgNmId>pain.001.001.14</OrgnlMsgNmId>\\n\r\n            <GrpSts>PART</GrpSts>\\n\r\n        </OrgnlGrpInfAndSts>\\n\r\n        <OrgnlPmtInfAndSts>\\n      \r\n            <OrgnlPmtInfId>PMT-001</OrgnlPmtInfId>\\n\r\n            <TxInfAndSts>\\n        \r\n                <OrgnlEndToEndId>EXT-493723559479911</OrgnlEndToEndId>\\n\r\n                <OrgnlInstrId/>\\n\r\n                <TxSts>PDNG</TxSts>\\n\r\n                <AcctSvcrRef>176232737137</AcctSvcrRef>\\n\r\n            </TxInfAndSts>\\n\r\n            <TxInfAndSts>\\n        \r\n                <OrgnlEndToEndId>EXT-780273386982009</OrgnlEndToEndId>\\n\r\n                <OrgnlInstrId/>\\n\r\n                <TxSts>PDNG</TxSts>\\n\r\n                <AcctSvcrRef>176232737138</AcctSvcrRef>\\n\r\n            </TxInfAndSts>\\n\r\n            <TxInfAndSts>\\n        \r\n                <OrgnlEndToEndId>EXT-872174653393565</OrgnlEndToEndId>\\n\r\n                <OrgnlInstrId/>\\n\r\n                <TxSts>PDNG</TxSts>\\n\r\n                <AcctSvcrRef>176232737139</AcctSvcrRef>\\n\r\n            </TxInfAndSts>\\n\r\n        </OrgnlPmtInfAndSts>\\n\r\n    </CstmrPmtStsRpt>\\n\r\n</Document>\\n\",\r\n    \"dt\": \"2025-11-05T10:40:24+00:00\"\r\n}"
          headers: {}
          x-apidog-name: Success
      security: []
      x-apidog-folder: Partner API/Account
      x-apidog-status: released
      x-run-in-apidog: https://app.apidog.com/web/project/640842/apis/api-24102332-run
components:
  schemas: {}
  securitySchemes:
    card-api:
      type: jwt
      scheme: bearer
      bearerFormat: JWT
      x-apidog:
        addTokenTo: header
        headerPrefix: Bearer
servers:
  - url: https://api.freedompay.kz
    description: KZ
  - url: https://api.freedompay.uz
    description: UZ
  - url: https://api.freedompay.kg
    description: KG
security: []
```

--------------------------------

### Success Response XML Example

Source: https://docs.freedompay.kz/any-amount-11620875e0

Example of a successful payment initiation response from the Purchase endpoint. Contains pg_status, pg_payment_id, pg_redirect_url, pg_redirect_url_type, pg_salt, and pg_sig fields.

```xml
<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_payment_id>7999007876</pg_payment_id>
    <pg_redirect_url>https://customer.freedompay.kz/pay.html?customer=200be02010c4f2a54260e5e798605691</pg_redirect_url>
    <pg_redirect_url_type>need data</pg_redirect_url_type>
    <pg_salt>LNTZ7ciT1xjwzCFr</pg_salt>
    <pg_sig>760767e58ac9c2089e02471638b01111</pg_sig>
</response>
```

--------------------------------

### JWS Signature Example

Source: https://docs.freedompay.kz/overview-650923m0

Example of a generated JWS signature for the request.

```APIDOC
eyJ1cmkiOiIvdjUvZzJnL2NyZWF0ZSIsImF1dGhfaWQiOiIxMjM0NTYiLCJtZXRob2QiOiJQT1NUIiwicGFyYW1zIjoiIiwiYWxnIjoiSFMyNTYifQ..82NnkgrNjfYu2UnAajnVsJUn2AgJWsqnmCK4x5A7zt0
```

--------------------------------

### Process Response Example

Source: https://docs.freedompay.kz/card-9885527e0

Example of a payment response in process status. Contains pg_payment_id, pg_order_id, pg_payment_amount, pg_status, pg_currency_from, pg_payment_date, pg_payment_status, pg_3ds, and pg_3d_acsurl fields.

```xml
<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_payment_id>777777777</pg_payment_id>
    <pg_order_id>980399</pg_order_id>
    <pg_payment_amount>100</pg_payment_amount>
    <pg_status>pending</pg_status>
    <pg_currency_from>KZT</pg_currency_from>
    <pg_payment_date/>
    <pg_payment_status>process</pg_payment_status>
    <pg_3ds>1</pg_3ds>
    <pg_3d_acsurl>https://secure.freedompay.kz/v2/user/3ds-page/1234abcd-1234-5678-9aed-1234abcd</pg_3d_acsurl>
```

--------------------------------

### Initialize Freedom Payment SDK with FreedomAPI.create

Source: https://docs.freedompay.kz/ios-1820483m0

Initializes the Freedom Payment SDK by calling the `create` method of the `FreedomAPI` class. Requires three parameters: merchant ID, merchant secret key, and the payment region (e.g., `Region.kz`).

```swift
let merchantId = "123456"
let secretKey = "123456789ABCDEF"
let region = Region.kz
let freedomApi = FreedomAPI.create(merchantId: merchantId, secretKey: secretKey, region: region)
```

--------------------------------

### Error Response XML Example

Source: https://docs.freedompay.kz/any-amount-11620875e0

Example of an error response from the Purchase endpoint. Contains pg_status, pg_error_code, and pg_error_description fields. The example shows error code 9999 with a message about an internal service error.

```xml
<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>error</pg_status>
    <pg_error_code>9999</pg_error_code>
    <pg_error_description>Внутренняя ошибка сервиса, попробуйте повторить запрос позднее.</pg_error_description>
</response>
```

--------------------------------

### Add Client with Product

Source: https://docs.freedompay.kz/add-client-with-product-12075992e0

Endpoint to add a client with a product.

```APIDOC
## Add Client with Product

### POST /v5/partner/client/add

Adds a new client with a product.

#### Request Body

- **Content-Type:** `application/json`
- **Schema:**
  - `request_id` (string, required): Unique request identifier.
  - `company` (object, required): Client data object.
    - `company_id` (string, required): Identifier of the legal entity in the partner's system.
    - `name` (string, required): Name of the legal entity.
    - `bin` (string, required): Business Identification Number of the legal entity.
    - `address` (object, required): Registration address data object.
      - `country` (string, required): Country of registration (alpha-3 format).
      - `postal_code` (string, required): Postal code.
      - `address_line1` (string, required): Address line 1.
  - `product` (object, optional): Product parameters. The parameter set depends on the connected product and is described in the Reference Guide.

#### Response

- **Status Code:** `200`
- **Content-Type:** `application/json`
- **Schema:**
  - `status` (string): Request status. Possible values: `ok` (success), `error` (failure).
  - `request_status` (string): Execution status of the request. See reference documentation for details.
  - `dt` (string, date-time): Date and time of the request (format: `YYYY-MM-DDThh:mm:ss+hh:mm`).
```

--------------------------------

### Resend OTP XML Response Example

Source: https://docs.freedompay.kz/resend-code-11977162e0

Example of a successful XML response from the /mfs/resend_otp endpoint.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<root>
  <pg_status>string</pg_status>
</root>
```
Tokens:
Raw