Мы используем cookie-файлы
Хорошо

API SDK

Introduction

The API SDK is a method for integrating with the Freedom Pay system by sending tokens. The SDK API allows you to set up a convenient method for the merchant to contact our API by sending card data that will be securely encrypted. Payments comply with PCI DSS rules, subject to certain requirements by the merchant

To use the SDK API, you need to contact your personal manager. If you want to implement a payment form, then you can use the JS SDK to integrate.
Using the API

The route group was created to work with the JS SDK, which is provided to merchants to implement payment acceptance without using frames or payment pages.
Request submission mechanics
Request headers
Example of a standard request

{
    "data": [
        "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"
    ],
    "token": "merchant-token"
}
Each request consists of two fields:
Authorization

Request authorization is done by passing a unique token in the request body.

Also, the request body itself must be encrypted with a public key, which is issued to the merchant upon connection along with the token.
Request Body Encryption Process

  1. First, we translate the data into a JSON string that does not contain hyphens and extra spaces.
  2. We encode the received string in Base64.
  3. We split the received string into substrings of 200 symbols each.
  4. We encrypt each substring separately with a public key.
  5. We encode each string in Base64 again.
  6. We write the received substrings to the data array.

// Example of sending a request:
$array = [
  'type' => 'bank_card',
  'options' => [
    'card_number' => '4405645000001234',
    'card_holder_name' => 'NAME',
    'card_exp_month' => '02',
    'card_exp_year' => '25',
  ]
];
$json = json_encode($array); // Convert data to json
$base64 = base64_encode($json); // Encode in Base64
$chunks = str_split($base64, 200); // Split into parts of 200 symbols
$result = [];
foreach ($chunks as $chunk) {
    openssl_public_encrypt($chunk, $encrypted, $publicKey); // Encrypt with public key
    $result[] = base64_encode($encrypted); // Encode in base64 again
}
print_r($result);
The uniqueness of the request

Each request must be accompanied by passing a Request-Id parameter in Headers.

It is recommended to use Uuid V4 in order to exclude intersections with other requests.

If the service receives a second request with the Request-Id that was received earlier, an error will be returned.
Card tokenization

Card tokenization for further payment.
Request example:

{
    "type": "bank_card",
    "options": {
        "card_number": "4405645000001234",
        "card_holder_name": "NAME",
        "card_exp_month": "02",
        "card_exp_year": "25"
    }
}
Пример ответа:

{
    "status": "success",
    "data": {
        "token": "eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0.LyIIVulOXIj3tV_ttHigOsCFEhjy2_CZRGI8T7jx8QqtkpgI9gu52aBgUFZ1NHMVYihxcl6P4m5vC2BP88oWGDYtTLW4SzJkCd27LXqMMYtZo9XretbodQS-MF6k5lAeTqfC_lILWXl0eGmoYg5tLXStiVsiTHjVksu9VqSgp8PxBdR-RMZ5gDJ0dkEnHghv4_WK8KudcXU6MiabxtqYPACoy_NZ9rR2zic0tSTW2Ev8e-k75kgwWLNSTxw7QvrrtOfmOGW5_jWssjaK31FZnvrjhpJ8snmMxBzXLfj98GvwjEj9a96sDyK3bApas9e6SLoSxpH9mGgrBA_H7_wPkg.dyHVsu7o9zlWTOG7_MIMTQ.RYrLoCxYDeOSoxHG4XlXfKDlQPZACMZro9poUxFUkyrfDnGNEv2BIQm9WFkIaR4PXf-G8cD1L44hgZNjZ-v5o3kS0ABiFtaEWL-QE9Zl8KutPFMPU_1uIxFbcfNwgO4QX2zJxdYX2Bjm2nDUml3oUg.vKd5QUUKWiKwhA4FSh5DFQ"
    }
}
Request URL

POST https://api.freedompay.kz/v5/sdk/tokenize

Headers
Making a payment

Request to make a payment using a previously tokenized card.
Request example:

{
  "order_id": "my-order",
  "auto_clearing": 1,
  "amount": 20,
  "currency": "KZT",
  "description": "Order description",
  "test": 0,
  "options": {
    "custom_params": {},
    "user": {
      "email": "string",
      "phone": "string"
    }
  },
  "transaction": {
    "type": "tokenized_card",
    "options": {
      "token": "eyJhbGciOiJSU0ExXzUiLCJlbmMiOiJBMTI4Q0JDLUhTMjU2In0.eTYB5I4ttwS6CM1oawgYRf9aLfTFzcEK3mKjJ5AMNCM69SdWysQdjrWVTh3Mh7BQtJYypmnbYNZb5SdSkvMawqnnEaEjS4UFFLM_bXYa8Eut3ZX4tXL-rZfouzUdpjatXsMvcxOixGiQm2UP6pEo7tAOx_t5h2_y8vk9so8garyTBbOQqF3MKDGShRLQUyNqcYzg1qezE_OZiFnpS1uU_x6La2XqqgkejIfiS2f3lc4DkD5aygM_yGwDcQMeGRdgBI_rg23q71zbOxuFOXoXVRdIdx2Y_V_tZ3JnXX1KkZSqdUNL2-XMGCC4Nnk2A3W1YQ_Ld0gN02b4Om43Nmpr9Q.xcXMT0eeva-2UnX3zNK1KQ._thk7WP3-pcIh_XuS_tnUkCYcNsnw0-yUbzx1rsq182jy1SH0PDaM_54KYfsqzgsemplO5U2tzPivx_k9VzoLwFFxjHfIMmVc3SFleyVIIKO0xY0KsU7fzNf4_BKwvXR6Ur4Q3E1g8NE4sWQJpy6tQ.vKqh65_qZS9-G2JmxYLErQ",
      "card_cvv": 223
    }
  }
}
Response example:

{
    "status": "success",
    "data": {
        "3ds": {
            "acsurl": "some_asc_url",
            "frame_url": "",
            "md": "MD",
            "pareq": "PaReq",
            "version": 1
        },
        "payment_id": "97397805",
        "payment_status": "need_confirm"
    }
}
If the merchant conducts the 3DS himself/herself, you need to send the client to AcsUrl using the POST method. In addition to the MD and PaReq parameters, it is required to pass TermUrl. The client will return to this TermUrl after passing 3ds with MD and PaRes parameters.
Sample form for client forwarding:

<form name="3dsForm" action="data.3ds.acsurl" method="POST">
  <input type="hidden" name="PaReq" value="data.3ds.pareq">
  <input type="hidden" name="MD" value="data.3ds.md">
  <input type="hidden" name="TermUrl" value="https://mysite.com/myTermUrl">
</form>
<script>
    document.getElementById('3dsForm').submit();
</script>
Request URL

POST https://api.freedompay.kz/v5/sdk/charge

Headers
Request for ACS Url

The method can be used in case of passing 3DS without JS SDK. After the client has returned to TermUrl with the MD and PaRes parameters, you need to call the current method.
Request example:

{
    "payment_id": 0,
    "pares": "string",
    "md": "string"
}
Response еxample:

{
    "status": "success",
    "data": {
        "auth_code": "123456",
        "payment_id": "123456",
        "payment_status": "success"
    }
}
Request URL

POST https://api.freedompay.kz/v5/sdk/charge

Headers
Checking payment status

It is recommended to check the status of each payment after it is made.
Request example:

{
  "order_id": "merchant_order_id",
  "payment_id": 123456
}
Response еxample:

{
    "status": "success",
    "data": {
        "order_id": "merchant_order_id",
        "payment_id": "123456",
        "payment_status": "success"
    }
}
Request URL

POST https://api.freedompay.kz/v5/sdk/charge

Headers
Reference books

Payment statuses
Error codes