Подготовка к интеграции

Регистрация и создание магазина через Tiyn Business

Для подготовки к интеграции необходимо:

1. Зарегистрировать личный кабинет Tiyn Business по кнопке Подключиться на странице tiyn.io;
2. В личном кабинете создать магазин в разделе Магазины, перейти в настройки магазина и заполнить раздел Общие настройки;
3. Перейти в раздел настроек магазина Технические настройки и сгенерировать новый секретный ключ (secretPhrase) для формирования подписи;
4. Если требуется передача уведомлений об изменении статусов счета в одну из ваших систем (Callback), заполнить поле ResultURL адресом для получения уведомлений;
5. Активировать созданный магазин, связавшись с персональным менеджером.

HTTP-заголовки

Взаимодействие с сервисом происходит посредством передачи HTTP-запросов.

Запросы могут включать следующие заголовки:

• Content-Type: application/json; charset=utf-8
• x-api-key: <API Key>
• x-sign: <электронно-цифровая подпись> (кроме получения данных счета и данных магазина)

Алгоритм формирования ЭЦП

ЭЦП формируется следующим образом:

1. От сформированного тела запроса (body) вычисляется хеш по алгоритму HMAC-SHA512. В качестве ключа используется secretPhrase), кодировка UTF-8
2. Полученное значение переводится в base64

Примеры реализации алгоритма формирования x-sign

Пример на языке C#

Пример на языке PHP

Схема проведения запроса

1. Магазин отправляет в Tiyn Business запрос на создание счета;
2. Tiyn Business обрабатывает запрос и, если счет создан корректно, возвращает данные, содержащие ссылку для перехода на оплату;
3. Плательщик переходит по ссылке выбирает способ оплаты и вводит платежные данные;
4. Tiyn Business отправляет запрос на списание денежных средств эквайеру;
5. Tiyn Business получает ответ об успешной/неуспешной оплате счета от эквайера; происходит переадресация плательщика на страницу магазина
   1. В случае успешной оплаты счета плательщик перенаправляется на страницу, указанную при создании счета в параметре successUrl;
   2. В случае неуспешной оплаты происходит перенаправление на страницу, указанную при создании счета в параметре failUrl;
6. Tiyn Business отправляет магазину уведомление об успешной/неуспешной оплате счета; Магазин возвращает ответ-подтверждение о проведенной операции.

Создание счета

Метод позволяет создать счет на оплату и отправить его плательщику.

Пример запроса на создание счета

curl https://business.tiyn.io/merchant-api/api/v2/invoices \
  -X POST \
  -H 'x-api-key: <Ключ доступа>' \
  -H 'x-sign: <ЭЦП>' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{
    "externalId": "3c5301df-d806-4fb0-9f96-f44d5d2d3827",
    "amount": 105.05,
    "currency": "KZT",
    "description": "Оплата заказа №12080",
    "customerPhone": "+74994550185",
    "customerEmail": "support@tiyn.io",
    "customerIp": "127.0.0.1",
    "customData": {
        "key1": "value1",
        "key2": 5
    },
    "successUrl": "https://empty.com/successUrl",
    "failUrl": "https://empty.com/failUrl",
    "deliveryMethod": "URL",
    "expirationDate": "2021-03-14 11:08:24.909150+03:00",
    "ofdData": null
}'

Описание параметров запроса на создание счета

Пример успешного ответа на запрос на создание счета

{
  "success": true,
  "data": {
    "uuid": "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a",
    "externalId": "3c5301df-d806-4fb0-9f96-f44d5d2d3827",
    "paymentLink": "https://business.tiyn.io/portal2/pay/i/cd422358-56dd-4039-9559-c1fb766dbbbd"
  }
}

Описание параметров успешного ответа при создании счета

Описание параметров объекта data

Пример ответа с ошибкой на запрос на создание счета

{
  "success": false,
  "error": {
    "code": "1",
    "message": "Ошибка создания счета",
    "correlationId": "01ee1da0-a25b-476d-a290-5eda640e14b2"
  }
}

Описание параметров ответа с ошибкой создания счета

Описание параметров объекта error

Отмена счета

Метод позволяет отменить возможность оплаты счета. Доступен только для тех счетов, по которым еще не было переходов на платежную страницу, в обратном случае запрос будет отклонен.

Пример запроса на отмену счета

curl https://business.tiyn.io/merchant-api/api/v2/invoices/<uuid>/cancel \
  -X PUT \
  -H 'x-api-key: <Ключ доступа>' \
  -H 'x-sign: <ЭЦП>' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{
    "requestId": "1df6b40c-e8a7-fcd1-a799-a0cfa3edab3a",
    "reason": "Отменен"
}'

uuid - идентификатор счета, полученный в успешном ответе при создании счета.

Описание параметров запроса на отмену счета

Пример успешного ответа на запрос на отмену счета

{
  "success": true,
  "data": {
    "uuid": "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a",
    "requestId": "d1f6b55c-e8a1-add7-a719-a1cfd3eda3ad"
  }
}

Описание параметров успешного ответа на запрос на отмену счета

Описание параметров объекта data

Пример ответа с ошибкой на запрос на отмену счета

{
  "success": false,
  "error": {
    "code": "3",
    "message": "error",
    "correlationId": "01ee1da0-a25b-476d-a290-5eda640e14b2"
  }
}

Описание параметров ответа с ошибкой на запрос на отмену счета

Описание параметров объекта error

Возврат

Используется для возврата денежных средств. Срок возврата зависит от банка, выпустившего карту плательщика.

Пример запроса на возврат

curl https://business.tiyn.io/merchant-api/api/v2/invoices/<uuid>/refund \
  -X PUT \
  -H 'x-api-key: <Ключ доступа>' \
  -H 'x-sign: <ЭЦП>' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{
    "requestId": "1df6b40c-e8a7-fcd1-a799-a0cfa3edab3a",
    "amount": 123.12,
    "reason": "Возврат по счету №22530"
}'

uuid - идентификатор счета, полученный в успешном ответе при создании счета.

Описание параметров запроса на возврат

Пример успешного ответа на запрос на возврат

{
  "success": true,
  "data": {
    "uuid": "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a",
    "requestId": "d1f6b55c-e8a1-add7-a719-a1cfd3eda3ad"
  }
}

Описание параметров успешного ответа на запрос на возврат

Описание параметров объекта data

Пример ответа с ошибкой на запрос на возврат

{
  "success": false,
  "error": {
    "code": "6",
    "message": "error",
    "correlationId": "01ee1da0-a25b-476d-a290-5eda640e14b2"
  }
}

Описание параметров ответа с ошибкой на запрос на возврат

Описание параметров объекта error

Получение данных счета

Метод позволяет запросить данные счета: статус счета, итоговая сумма счета, метод оплаты и др.

Пример запроса на получение данных

curl https://business.tiyn.io/merchant-api/api/v2/invoices/<uuid> \
  -X GET \
  -H 'x-api-key: <Ключ доступа>' \
  -H 'Content-Type: application/json; charset=utf-8' \

uuid - идентификатор счета, полученный в успешном ответе при создании счета.

Описание параметров запроса на получение данных

Пример успешного ответа на запрос на получение данных

{
  "externalId": "3c5301df-d806-4fb0-9f96-f44d5d2d3827",
  "uuid": "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a",
  "amount": 105.05,
  "finalAmount": 123.12,
  "currency": "KZT",
  "description": "Счет на оплату заказа №12080",
  "customerPhone": "+74994550185",
  "customerEmail": "support@tiyn.io",
  "customData": {
    "key1": "value1",
    "key2": 5
  },
  "successUrl": "http://empty.com/successUrl",
  "failUrl": "http://empty.com/failUrl",
  "deliveryMethod": "URL",
  "expirationDate": "2021-03-14 11:08:24.0909150+03:00",
  "ofdData": null,
  "status": {
    "name": "InvoicePaid",
    "time": "2020-03-14 11:08:24.0909150+03:00",
    "message": "message"
  },
  "payments": [
    {
      "paymentMethod": "BankCard",
      "details": {
        "account": "411111******1111",
        "paymentToken": "837c06b4-b791-4f2c-89b1-a45f78cb1568"
      },
      "status": {
        "name": "PaymentPaid"
      }
    }
  ]
}

Описание параметров успешного ответа на запрос на получение данных

Описание параметров объекта status

Описание параметров объекта payments

Описание параметров объекта details

Описание параметров объекта status

Пример ответа с ошибкой на запрос на получение данных

{
  "success": false,
  "error": {
    "code": "5",
    "message": "error",
    "correlationId": "01ee1da0-a25b-476d-a290-5eda640e14b2"
  }
}

Описание параметров ответа с ошибкой на запрос на получение данных

Описание параметров объекта error

Оплата счета

Метод позволяет передать детали платежа для осуществления оплаты.

Пример запроса оплаты счета

curl https://business.tiyn.io/merchant-api/api/v2/invoices/<uuid>/pay \
  -X PUT \
  -H 'x-api-key: <Ключ доступа>' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{
    "requestId": "1df6b40c-e8a7-fcd1-a799-a0cfa3edab3a",
    "paymentMethod": "BankCard",
    "details": {
        "key1": "value1",
        "key2": "value2"
        }
    }
}'

uuid - идентификатор счета, полученный в успешном ответе при создании счета.

Описание параметров запроса оплаты счета

Описание параметров details для способа оплаты BankCard

Пример успешного ответа на запрос оплаты счета, если не требуется перенаправление пользователя

{
  "success": true,
  "data": {
    "uuid": "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a",
    "requestId": "d1f6b55c-e8a1-add7-a719-a1cfd3eda3ad"
  }
}

Описание параметров успешного ответа на запрос оплаты счета

Описание параметров объекта data

Пример успешного ответа на запрос оплаты счета, если требуется перенаправление пользователя

{
  "success": true,
  "data": {
    "uuid": "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a",
    "requestId": "d1f6b55c-e8a1-add7-a719-a1cfd3eda3ad",
    "redirect": {
      "url": "http://example.com",
      "method": "POST",
      "params": [
        {
          "name": "name1",
          "value": "value1"
        }
      ]
    }
  }
}

Перенаправление может потребоваться в случае необходимости ввода кода 3DS.

Описание параметров успешного ответа на запрос оплаты счета

Описание параметров объекта data

Описание параметров объекта redirect

Пример ответа с ошибкой на запрос оплаты счета

{
  "success": false,
  "error": {
    "code": "5",
    "message": "error",
    "correlationId": "01ee1da0-a25b-476d-a290-5eda640e14b2"
  }
}

Описание параметров ответа с ошибкой на запрос оплаты счета

Описание параметров объекта error

Получение баланса магазина

Пример запроса на получение данных

Метод позволяет по ключу доступа получить баланс данного магазина. Если магазин работает с несколькими валютами, то баланс будет получен по каждой из валют.

curl https://business.tiyn.io/merchant-api/api/v2/balance \
  -X GET \
  -H 'x-api-key: <Ключ доступа>' \
  -H 'Content-Type: application/json; charset=utf-8' \

Пример успешного ответа на запрос на получение данных

{
  "success": true,
  "data": [
    {
      "currency": "KZT",
      "balance": 890.12
    }
  ]
}

Описание параметров успешного ответа на запрос на получение данных

Описание параметров элемента коллекции data

Пример ответа с ошибкой на запрос на получение данных

{
  "success": false,
  "error": {
    "code": "8",
    "message": "error",
    "correlationId": "01ee1da0-a25b-476d-a290-5eda640e14b2"
  }
}

Описание параметров ответа с ошибкой на запрос на получение данных

Описание параметров объекта error

Создание выплаты

Метод позволяет осуществлять вывод средств на банковскую карту. Для активации возможности создавать выплаты необходимо связаться с менеджером Tiyn Business.

Пример запроса на создание выплаты

curl https://business.tiyn.io/merchant-api/api/v2/payouts \
  -X POST \
  -H 'x-api-key: <Ключ доступа>' \
  -H 'x-sign: <ЭЦП>' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{
    "externalId": "3c5301df-d806-4fb0-9f96-f44d5d2d3827",
    "amount": 10005.05,
    "currency": "KZT",
    "description": "Вывод себе на карту",
    "destination": {
        "pan": "41233543544386", 
        "cardholder": "Ivan Pupkin"
    },
    "payoutMethod": "BankCard"
}'

Описание параметров запроса на создание выплаты

Описание параметров объекта destination для способа вывода на банковскую карту

{
    ...
    "destination": {
        "pan": "41233543544386", 
        "cardholder": "Ivan Pupkin"
    },
    "payoutMethod": "BankCard"
}

Пример успешного ответа на запрос на создание выплаты

{
  "success": true,
  "data": {
    "uuid": "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a",
    "externalId": "3c5301df-d806-4fb0-9f96-f44d5d2d3827"
  }
}

Описание параметров успешного ответа при создании выплаты

Описание параметров объекта data

Пример ответа с ошибкой на запрос на создание выплаты

{
  "success": false,
  "error": {
    "code": "9",
    "message": "Ошибка создания выплаты",
    "correlationId": "01ee1da0-a25b-476d-a290-5eda640e14b2"
  }
}

Описание параметров ответа с ошибкой создания выплаты

Описание параметров объекта error

Получение данных выплаты

Метод позволяет запросить данные выплаты: статус выплаты, сумму, метод вывода и др.

Пример запроса на получение данных

curl https://business.tiyn.io/merchant-api/api/v2/payouts/<uuid> \
  -X GET \
  -H 'x-api-key: <Ключ доступа>' \
  -H 'Content-Type: application/json; charset=utf-8' \

uuid - идентификатор выплаты, полученный в успешном ответе при создании выплаты.

Описание параметров запроса на получение данных

Пример успешного ответа на запрос на получение данных

{
  "success": true,
  "data": {
    "externalId": "8041905d-c3cb-4c83-a232-1a98891023b8",
    "uuid": "8904c0ef-7667-4ec2-b63a-57c50faf0248",
    "commission": {
      "amount": "12.33",
      "currency": "KZT"
    },
    "payoutMethod": "BankCard",
    "amount": 813.03,
    "currency": "KZT",
    "description": "some description",
    "destination": {
      "masked_pan": "411111******1111"
    },
    "status": {
      "name": "PayoutSucceeded",
      "time": "2022-04-13 08:42:22.501903+00:00",
      "message": "Получено событие о удачном проведении транзакции на выплату"
    }
  }
}

Описание параметров успешного ответа на запрос на получение данных

Описание параметров объекта data

Описание параметров объекта commission

Описание параметров объекта status

Описание параметров объекта destination

Пример ответа с ошибкой на запрос на получение данных

{
  "success": false,
  "error": {
    "code": "10",
    "message": "error",
    "correlationId": "01ee1da0-a25b-476d-a290-5eda640e14b2"
  }
}

Описание параметров ответа с ошибкой на запрос на получение данных

Описание параметров объекта error

Подтверждение двухэтапной выплаты

Метод позволяет подтверждать двухэтапную выплату. Подтверждение выполняется для выплаты в статусе PayoutWaitingConfirmation. Для активации возможности создавать двухэтапные выплаты необходимо связаться с менеджером Tiyn Business.

Пример запроса на подтверждение выплаты

curl https://business.tiyn.io/merchant-api/api/v2/payouts/<uuid>/confirm \
  -X POST \
  -H 'x-api-key: <Ключ доступа>' \
  -H 'x-sign: <ЭЦП>' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{}'

uuid - идентификатор выплаты, полученный в успешном ответе при создании выплаты.

Описание параметров запроса на подтверждение выплаты

Пример успешного ответа на запрос на подтверждения выплаты

{
  "success": true,
  "data": {
    "uuid": "8904c0ef-7667-4ec2-b63a-57c50faf0248"
  }

Описание параметров успешного ответа при создании выплаты

Описание параметров объекта data

Пример ответа с ошибкой на запрос на подтверждения выплаты

{
  "success": false,
  "error": {
    "code": "13",
    "message": "Ошибка подтверждения выплаты",
    "correlationId": "01ee1da0-a25b-476d-a290-5eda640e14b2"
  }
}

Описание параметров ответа с ошибкой подтверждения выплаты

Описание параметров объекта error

Отклонение двухэтапной выплаты

Метод позволяет отклонять двухэтапную выплату. Отклонение выполняется для выплаты в статусе PayoutWaitingConfirmation. Для активации возможности создавать двухэтапные выплаты необходимо связаться с менеджером Tiyn Business.

Пример запроса на отклонение выплаты

curl https://business.tiyn.io/merchant-api/api/v2/payouts/<uuid>/decline \
  -X POST \
  -H 'x-api-key: <Ключ доступа>' \
  -H 'x-sign: <ЭЦП>' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{}'

uuid - идентификатор выплаты, полученный в успешном ответе при создании выплаты.

Описание параметров запроса на отклонение выплаты

Пример успешного ответа на запрос на отклонение выплаты

{
  "success": true,
  "data": {
    "uuid": "8904c0ef-7667-4ec2-b63a-57c50faf0248"
  }

Описание параметров успешного ответа при отклонении выплаты

Описание параметров объекта data

Пример ответа с ошибкой на запрос на отклонение выплаты

{
  "success": false,
  "error": {
    "code": "14",
    "message": "Ошибка отклонения выплаты",
    "correlationId": "01ee1da0-a25b-476d-a290-5eda640e14b2"
  }
}

Описание параметров ответа с ошибкой отклонения выплаты

Описание параметров объекта error

Перечень возможных значений статусов счета

Перечень возможных значений статусов платежа

Перечень возможных значений статусов выплаты

Оповещение об изменении статуса счета

Оповещение об изменении статуса (Callback) происходит путем отправки POST-запроса по адресу, указанному в настройках магазина (раздел Технические настройки , параметр Result url)

Если на оповещение получен невалидный ответ/валидный ответ с ошибкой, или же ответ не получен, система отправляет повторное оповещение позднее. Оповещение отправляется повторно конечное число раз.

Пример оповещения от Tiyn Business

curl https://business.tiyn.io/resultUrl \
  -X POST \
  -H 'x-sign: <ЭЦП>' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{
    "externalId": "3c5301df-d806-4fb0-9f96-f44d5d2d3827",
    "uuid": "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a",
    "amount": 105.05,
    "finalAmount": 123.12,
    "currency": "KZT",
    "description": "Счет на оплату заказа №12080",
    "customerPhone": "+74994550185",
    "customerEmail": "support@tiyn.io",
    "customData": {
        "key1": "value1",
        "key2": 5
    },
    "successUrl": "http://empty.com/successUrl",
    "failUrl": "http://empty.com/failUrl",
    "deliveryMethod": "URL",
    "expirationDate": "2021-03-14 11:08:24.909150+03:00",
    "ofdData": null,
    "status": {
        "name": "InvoicePaid",
        "time": "2019 -03-14 11:08:24.0909150+03:00",
        "message": "message"
    },
    "payments": [
        {
            "paymentMethod": "BankCard",
            "details": {
                "account": "411111******1111",
                "paymentToken": "837c06b4-b791-4f2c-89b1-a45f78cb1568"
            },
            "status": {
                "name": "PaymentPaid"
            }
        }
    ]
}

Описание параметров оповещения от Tiyn Business

Описание параметров объекта status

Описание параметров объекта payments

Описание параметров объекта details

Описание параметров объекта status

Пример ожидаемого успешного ответа от системы мерчанта на оповещение от Tiyn Business

{
  "success": true,
  "uuid": "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a"
}

Пример ожидаемого ответа с ошибкой от системы мерчанта на оповещение от Tiyn Business

{
  "success": false,
  "uuid": "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a"
}

Описание параметров ожидаемых ответов от системы мерчанта на оповещение от Tiyn Business

Оповещение об изменении статуса выплаты

Оповещение об изменении статуса (Callback) происходит путем отправки POST-запроса по адресу, указанному в настройках магазина (раздел Технические настройки , параметр Payout Result URL)

Если на оповещение получен невалидный ответ/валидный ответ с ошибкой, или же ответ не получен, система отправляет повторное оповещение позднее. Оповещение отправляется повторно конечное число раз.

Пример оповещения от Tiyn Business

curl https://business.tiyn.io/PayoutResultURL \
  -X POST \
  -H 'x-sign: <ЭЦП>' \
  -H 'Content-Type: application/json; charset=utf-8' \
  -d '{
    "externalId": "3c5301df-d806-4fb0-9f96-f44d5d2d3827",
    "uuid": "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a",
    "commission": {
        "amount": "12.33",
        "currency": "KZT"  
    },
    "amount": 10005.05,
    "currency": "KZT",
    "description": "Вывод себе на карту",
    "destination": {
        "cardholder": "Ivan Pupkin",
        "masked_pan": "412335******4386"
    },
    "status": {
        "name": "PayoutSucceeded",
        "time": "2020-08-01 11:08:24.0909150+03:00",
        "message": "message"
    },
    "payoutMethod": "BankCard"
}

Описание параметров оповещения от Tiyn Business

Описание параметров объекта commission

Описание параметров объекта status

Описание параметров объекта destination для способа вывода на банковскую карту

Пример ожидаемого успешного ответа от системы мерчанта на оповещение от Tiyn Business

{
  "success": true,
  "uuid": "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a"
}

Пример ожидаемого ответа с ошибкой от системы мерчанта на оповещение от Tiyn Business

{
  "success": false,
  "uuid": "1fd64b0c-a8e7-4dc1-a799-f0cfa3ebad3a"
}

Описание параметров ожидаемых ответов от системы мерчанта на оповещение от Tiyn Business

Описание кодов ошибок

Тестирование

Тестовые карты для проведения платежей и осуществления выплат (для тестовых магазинов Tiyn Business)