Регламент API Мерчантам

Описание интеграции с Мерчантами

Мерчант - Юридическое лицо или индивидуальный предприниматель, принимающий электронные деньги innopay в качестве оплаты товаров и услуг. И в данной интеграции читатель выступает в роли мерчанта.

Данный материал предназначен для демонстрации сценариев интеграции Innopay, содержит описание сценариев взаимодействия, описание протоколов и примеры реализации на языках Java, PHP.

СОДЕРЖАНИЕ

ПРИНЦИПЫ ВЗАИМОДЕЙСТВИЯ МЕЖДУ МАГАЗИНОМ И ПС INNOPAY
ПОЛУЧЕНИЕ ЭЦП ДЛЯ ПОДПИСИ ЗАПРОСОВ
СЦЕНАРИЙ ПЛАТЕЖА
ТЕХНИЧЕСКИЕ ДЕТАЛИ ВЗАИМОДЕЙСТВИЯ
ОПИСАНИЕ ФОРМАТА СООБЩЕНИЙ
ИСПОЛЬЗОВАНИЕ ТЕСТОВОЙ СИСТЕМЫ INNOPAY
ПРИМЕРЫ ДЕМО РЕАЛИЗАЦИЙ

ПРИНЦИПЫ ВЗАИМОДЕЙСТВИЯ МЕЖДУ МАГАЗИНОМ И INNOPAY

Диаграмма последовательности

Обмен информацией происходит через браузер пользователя и веб-сервисы.

Для обмена данными используется формат XML, для всех видов передаваемых сообщений определена соответствующая схема XSD. Для безопасного обмена сообщениями все XML подписываются обеими сторонами. Подпись реализована по стандарту W3C описанными в XSD схеме XmlDSig. Для запроса на проведение платежа используется XSD схема WebShopRequest.xsd, для передачи результата о проведенном платеже используется XSD схема WebShopResponse.xsd. Каждое сообщение должно проходить валидацию по соответствующей XSD схеме, все обязательные поля должны быть заполнены по формату.

Используемая кодировка – UTF-8

ПОЛУЧЕНИЕ ЭЦП ДЛЯ ПОДПИСИ ЗАПРОСОВ

Для генерации ключей нужно

Авторизоваться мерчантом в системе innopay.
В меню "Настройки" выбрать "Управление сертификатами"
Нажать "Сгенерировать пару и скачать приватный ключ"

СЦЕНАРИЙ ПЛАТЕЖА

Покупатель формирует заказ на сайте продавца
Покупатель выбирает систему Innopay в качестве способа платежа
Покупатель попадает на портал Innopay для авторизации платежа
Покупатель подтверждает платеж
Сумма электронных денег за вычетом предусмотренных комиссий переводятся с электронного кошелька Покупателя на электронный кошелек Мерчанта
Innopay сообщает магазину о результате платежа посредством вызова заранее определённого веб-сервиса (URL на сайте продавца)

ТЕХНИЧЕСКИЕ ДЕТАЛИ ВЗАИМОДЕЙСТВИЯ

Схема взаимодействия онлайн магазина и ПС Innopay

Покупатель формирует корзину на сайте магазина
Покупатель выбирает ПС Innopay в качестве способа оплаты
Сайт магазина формирует HTTP POST запрос, и перенаправляет Покупателя на портал ПС Innopay https://mfs.innopay.kz/mfs/WebShopPayment.xhtml. В параметры HTTP POST(form data) запроса должно быть указано два значения:

webshopRequest – Запрос в ПС от магазина, XML сообщение WebShopRequest(закодированное в base64).
loginName - дополнительное необязательное поле для предзаполненного логина на странице входа.

Покупатель авторизуется на портале ПС Innopay.
Проверяется подпись XML.
По полученным XML данным заполняется форма подтверждения платежа.
Покупатель подтверждает платеж.
ПС отправляет подписанное сообщение XML WebShopResponse на веб-сервис магазина при помощи HTTP POST запроса.
Покупатель перенаправляется на веб-страницу магазина, указанную в сообщении WebShopRequest Со стороны магазина для интеграции требуется два веб-сервиса 1) для выдачи запросов WebShopRequest и 2) для получения WebShopResponse. Ключи для подписи и верификации будут выдаваться ПС Innopay после подписания договора.

ОПИСАНИЕ ФОРМАТА СООБЩЕНИЙ

WebShopRequest(формат xml подписанной и закодированной, передается через браузер клиента)

Пример XML

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<WSReq:WebShopRequest xmlns:WSReq="http://allpay.kz/xsd/1.0.0/WebShopRequest.xsd"
                      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                      xsi:schemaLocation="http://allpay.kz/xsd/1.0.0/WebShopRequest.xsd">
    <WSReq:ShopName>string</WSReq:ShopName>
    <WSReq:InvoiceNumber>string</WSReq:InvoiceNumber>
    <WSReq:Merchant>
        <WSReq:MerchantID>string</WSReq:MerchantID>
        <WSReq:WalletID>string</WSReq:WalletID>
    </WSReq:Merchant>
    <!--Optional:-->
    <WSReq:Cart>
        <!--1 or more repetitions:-->
        <WSReq:Items>
            <WSReq:Code>string</WSReq:Code>
            <WSReq:Name>string</WSReq:Name>
            <!--Optional:-->
            <WSReq:Description>string</WSReq:Description>
            <WSReq:Quantity>1000.00</WSReq:Quantity>
            <WSReq:Cost>1000.00</WSReq:Cost>
        </WSReq:Items>
    </WSReq:Cart>
    <WSReq:TotalCost>1000.00</WSReq:TotalCost>
    <!--Optional:-->
    <WSReq:SuccessLink>string</WSReq:SuccessLink>
    <!--Optional:-->
    <WSReq:FailureLink>string</WSReq:FailureLink>
    <WSReq:TimeoutInSeconds>600</WSReq:TimeoutInSeconds>
    <WSReq:ResponseURL>string2</WSReq:ResponseURL>
    <WSReq:AutoTransaction>false</WSReq:AutoTransaction>
    <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
        <SignedInfo>
            <CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments"/>
            <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
            <Reference URI="">
                <Transforms>
                    <Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
                </Transforms>
                <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
                <DigestValue>WvtifmGYsFTzrV9eMVJcSxs2WHQ=</DigestValue>
            </Reference>
        </SignedInfo>
        <SignatureValue>FyvvSKXotxTQ6pzuBY4UWUS8U/upHDHtxFstpCFG2vvi5GeUl8HFo5E3vxOetC26+a3SS9MmAIGa
            DxvcHz2VH4KgwbbyCm/H3kH9XXKBUSYUojpnaUZ4Ton3yo0WUHQ9NjLTBhBrwh9CuwpU7nEC2mUL
            h5POSYjbUcgdliTNwDk=
        </SignatureValue>
    </Signature>
</WSReq:WebShopRequest>

Пример подписанной XML

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<WSReq:WebShopRequest xmlns:WSReq="http://allpay.kz/xsd/1.0.0/WebShopRequest.xsd"
                      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                      xsi:schemaLocation="http://allpay.kz/xsd/1.0.0/WebShopRequest.xsd">
    <WSReq:ShopName>string</WSReq:ShopName>
    <WSReq:InvoiceNumber>string</WSReq:InvoiceNumber>
    <WSReq:Merchant>
        <WSReq:MerchantID>string</WSReq:MerchantID>
        <WSReq:WalletID>string</WSReq:WalletID>
    </WSReq:Merchant>
    <!--Optional:-->
    <WSReq:Cart>
        <!--1 or more repetitions:-->
        <WSReq:Items>
            <WSReq:Code>string</WSReq:Code>
            <WSReq:Name>string</WSReq:Name>
            <!--Optional:-->
            <WSReq:Description>string</WSReq:Description>
            <WSReq:Quantity>1000.00</WSReq:Quantity>
            <WSReq:Cost>1000.00</WSReq:Cost>
        </WSReq:Items>
    </WSReq:Cart>
    <WSReq:TotalCost>1000.00</WSReq:TotalCost>
    <!--Optional:-->
    <WSReq:SuccessLink>string</WSReq:SuccessLink>
    <!--Optional:-->
    <WSReq:FailureLink>string</WSReq:FailureLink>
    <WSReq:ResponseURL>string2</WSReq:ResponseURL>
    <WSReq:TimeoutInSeconds>600</WSReq:TimeoutInSeconds>
    <WSReq:AutoTransaction>false</WSReq:AutoTransaction>
    <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
        <SignedInfo>
            <CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments"/>
            <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
            <Reference URI="">
                <Transforms>
                    <Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
                </Transforms>
                <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
                <DigestValue>WvtifmGYsFTzrV9eMVJcSxs2WHQ=</DigestValue>
            </Reference>
        </SignedInfo>
        <SignatureValue>FyvvSKXotxTQ6pzuBY4UWUS8U/upHDHtxFstpCFG2vvi5GeUl8HFo5E3vxOetC26+a3SS9MmAIGa
            DxvcHz2VH4KgwbbyCm/H3kH9XXKBUSYUojpnaUZ4Ton3yo0WUHQ9NjLTBhBrwh9CuwpU7nEC2mUL
            h5POSYjbUcgdliTNwDk=
        </SignatureValue>
    </Signature>
</WSReq:WebShopRequest>

WSReq:ShopName Название магазина, которое будет видеть Покупатель на странице подтверждения платежей. Обязательное для заполнения
WSReq:InvoiceNumber Номер заказа, поле должно быть уникальным в базе данных магазина. Обязательное для заполнения
WSReq:Merchant Составное поле, описывающее аккаунт магазина в ПС Innopay. Обязательное для заполнения

WSReq:MerchantID Идентификатор магазина в ПС. Выдается в момент заключения договора. Обязательное для заполнения
WSReq:WalletID Идентификатор счета в ПС. На этот счет будут переводится деньги от Покупателя. Выдается в момент заключения договора. Обязательное для заполнения(прим. terminal_id)

WSReq:Cart Составное поле, описывающее товары в корзине Покупателя.

WSReq:Items Составное поле. Описание одной товарной позиции
WSReq:Code Код товара
WSReq:Name Название товара
WSReq:Description Описание товара
WSReq:Quantity Количество товара в соответствующей мере измерения
WSReq:Cost Стоимость товара

WSReq:TotalCost Общая сумма к оплате. Обязательное для заполнения
WSReq:TimeOutInSeconds Таймаут транзакции. Минимальное значение 600, максимальное 86400. Обязательное для заполнения
WSReq:SuccessLink URL Ссылка магазина, на которую попадёт Покупатель после удачного платежа. Обязательное для заполнения
WSReq:ResponseURL URL Ссылка магазина, на которую высылается ответ после удачного/неудачного платежа. Обязательное для заполнения
WSReq:ProtocolVersion Номер протокола, по которому будут обрабатываться ответы на WebshopResponse. Подробнее
WSReq:FailureLink URL Ссылка магазина, на которую попадёт Покупатель в случае неудачного платежа. Обязательное для заполнения
WSReq:AutoTransaction Автономное проведение транзакции. Необходимо выставить значение true, параметр устарел и оставлен для совместимости.
Signature Подпись. Обязательное для заполнения

WebShopResponse(формат http запроса от innopay в магазин мерчанта)

Пример XML

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<WSResp:WebShopResponse xmlns:WSResp="http://allpay.kz/xsd/1.0.0/WebShopResponse.xsd"
                        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                        xsi:schemaLocation="http://allpay.kz/xsd/1.0.0/WebShopResponse.xsd">
    <WSResp:InvoiceNumber>123456890</WSResp:InvoiceNumber>
    <WSResp:Transaction>
        <WSResp:TransactionId>String</WSResp:TransactionId>
        <WSResp:Status>String</WSResp:Status>
        <WSResp:StatusDescription>String</WSResp:StatusDescription>
    </WSResp:Transaction>
    <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
        <SignedInfo>
            <CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments"/>
            <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
            <Reference URI="">
                <Transforms>
                    <Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
                </Transforms>
                <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
                <DigestValue>iN6CHtvVOCF+cbzSp2SarMY/Sf4=</DigestValue>
            </Reference>
        </SignedInfo>
        <SignatureValue>wrCvdbJCV6v2tKwVQp7Iukh3deTOO6kKDePBmcXz69CGo77SW3KxCE0FxltgtKhB0hJ2HLofUaZ2
            BBtqq/l6h8RuPM5hZVgaAWjS+z2k9uLJx1KC9eluBRXKO9rDiafLEqRYQuOdmw8qE9nnuZi9ZtEw
            EmroWD6/xcEdiDMT49s=
        </SignatureValue>
    </Signature>
</WSResp:WebShopResponse>

Пример подписанной XML

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<WSResp:WebShopResponse xmlns:WSResp="http://allpay.kz/xsd/1.0.0/WebShopResponse.xsd"
                        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                        xsi:schemaLocation="http://allpay.kz/xsd/1.0.0/WebShopResponse.xsd">
    <WSResp:InvoiceNumber>123456890</WSResp:InvoiceNumber>
    <WSResp:Transaction>
        <WSResp:TransactionId>String</WSResp:TransactionId>
        <WSResp:Status>String</WSResp:Status>
        <WSResp:StatusDescription>String</WSResp:StatusDescription>
    </WSResp:Transaction>
    <Signature xmlns="http://www.w3.org/2000/09/xmldsig#">
        <SignedInfo>
            <CanonicalizationMethod Algorithm="http://www.w3.org/TR/2001/REC-xml-c14n-20010315#WithComments"/>
            <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/>
            <Reference URI="">
                <Transforms>
                    <Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
                </Transforms>
                <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/>
                <DigestValue>iN6CHtvVOCF+cbzSp2SarMY/Sf4=</DigestValue>
            </Reference>
        </SignedInfo>
        <SignatureValue>wrCvdbJCV6v2tKwVQp7Iukh3deTOO6kKDePBmcXz69CGo77SW3KxCE0FxltgtKhB0hJ2HLofUaZ2
            BBtqq/l6h8RuPM5hZVgaAWjS+z2k9uLJx1KC9eluBRXKO9rDiafLEqRYQuOdmw8qE9nnuZi9ZtEw
            EmroWD6/xcEdiDMT49s=
        </SignatureValue>
    </Signature>
</WSResp:WebShopResponse>

WSResp:InvoiceNumber Номер заказа магазина. Может отсутствовать в случае ошибок в WebshopRequest полученном от магазина
WSResp:Transaction Составное поле. Описывает транзакцию
WSResp:TransactionId Номер транзакции в ПС Innopay. По этому номеру можно проверить статус транзакции в веб интерфейсе и проводить манипуляции через веб сервис. Обязательное для заполнения
WSResp:Status Статус транзакции. Обязательное для заполнения
WSResp:StatusDescription Описание статуса транзакции. Содержит логин пользователя(клиента), который совершает транзакцию, если у мерчанта есть привилегия к просмотру логинов пользователей. Если привилегии нет, то поле остается пустым. Обязательное для заполнения
Signature Подпись. Обязательное для заполнения

WebshopCustomerResponse(формат http ответа, генерируется магазином мерчанта для ответа в innopay, http status должен быть 200)

Пример XML завершенного платежа

<?xml version="1.0" encoding="UTF-8"?>
<WSCResp:WebShopCustomerResponse xsi:schemaLocation="http://allpay.kz/xsd/1.0.0/WebShopCustomerResponse.xsd"
                                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                                 xmlns:WSCResp="http://allpay.kz/xsd/1.0.0/WebShopCustomerResponse.xsd">
    <WSCResp:Status>DONE</WSCResp:Status>
    <WSCResp:Reason></WSCResp:Reason>
</WSCResp:WebShopCustomerResponse>

Пример XML отклоненного платежа

<?xml version="1.0" encoding="UTF-8"?>
<WSCResp:WebShopCustomerResponse xsi:schemaLocation="http://allpay.kz/xsd/1.0.0/WebShopCustomerResponse.xsd"
                                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                                 xmlns:WSCResp="http://allpay.kz/xsd/1.0.0/WebShopCustomerResponse.xsd">
    <WSCResp:Status>FAIL</WSCResp:Status>
    <WSCResp:Reason>Unknown error</WSCResp:Reason>
</WSCResp:WebShopCustomerResponse>

Пример XML платежа в ожидании

<?xml version="1.0" encoding="UTF-8"?>
<WSCResp:WebShopCustomerResponse xsi:schemaLocation="http://allpay.kz/xsd/1.0.0/WebShopCustomerResponse.xsd"
                                 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                                 xmlns:WSCResp="http://allpay.kz/xsd/1.0.0/WebShopCustomerResponse.xsd">
    <WSCResp:Status>PENDING</WSCResp:Status>
    <WSCResp:Reason></WSCResp:Reason>
</WSCResp:WebShopCustomerResponse>

Пример XML приведён в файле WebShopCustomerResponse.xml.

WSCResp:Status Статус платежа на интегрирующейся стороне. Значения смотрите в таблице. Обязательное для заполнения
WSCResp:Reason Описание причины данного статуса. Необходимость заполнения данного поля смотрите в таблице.

Status	Reason
DONE	not required
PENDING	not required
FAIL	required

При отправке WebShopResponse интегрирующейся стороне, ПС ждет ответа в формате WebShopCustomerResponse. Описание смотрите здесь

ИСПОЛЬЗОВАНИЕ ТЕСТОВОЙ СИСТЕМЫ INNOPAY

Для тестирования сервисов можно подключится к тестовой инфраструктуре ПС Innopay. Запрос на получение доступа к тестовому серверу необходимо отправить на почту techsupport@innopay.kz

ПРИМЕРЫ РЕАЛИЗАЦИЙ

Исходный код демо проектов находится здесь
Реализация на java здесь.
Реализация на языке php и описание здесь

Реализация подписи

Для платформ для которых не сущетствует нативной библиотеки для подписи, подпись будет необходимо реализовать самостоятельно. Здесь находится точка входа для подписи. Этот вызов ведет сюда и сорсы данного класса(SignatureUtils) можно взять за основу при реализации.

Пример подписи

Если взять приватный ключ: https://github.com/allpaykz/allpay-public/blob/develop/webshop-integration/webshop-integration-keypair/src/test/resources/mockKeys/TEST.priv.pem

и подписать им: https://github.com/allpaykz/allpay-public/blob/develop/webshop-integration/webshop-integration-keypair/src/test/resources/WebShopRequest.xml

То получится такой xml:

<?xml version="1.0" encoding="UTF-8" standalone="no"?><WSReq:WebShopRequest xmlns:WSReq="http://allpay.kz/xsd/1.0.0/WebShopRequest.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://allpay.kz/xsd/1.0.0/WebShopRequest.xsd http://allpay.kz/xsd/1.0.0/WebShopRequest.xsd">
    <WSReq:ShopName>string</WSReq:ShopName>
    <WSReq:InvoiceNumber>string</WSReq:InvoiceNumber>
    <WSReq:Merchant>
        <WSReq:MerchantID>string</WSReq:MerchantID>
        <WSReq:WalletID>string</WSReq:WalletID>
    </WSReq:Merchant>
    <!--Optional:-->
    <WSReq:Cart>
        <!--1 or more repetitions:-->
        <WSReq:Items>
            <WSReq:Code>string</WSReq:Code>
            <WSReq:Name>string</WSReq:Name>
            <!--Optional:-->
            <WSReq:Description>string</WSReq:Description>
            <WSReq:Quantity>1000.00</WSReq:Quantity>
            <WSReq:Cost>1000.00</WSReq:Cost>
        </WSReq:Items>
    </WSReq:Cart>
    <WSReq:TotalCost>1000.00</WSReq:TotalCost>
    <!--Optional:-->
    <WSReq:SuccessLink>string</WSReq:SuccessLink>
    <!--Optional:-->
    <WSReq:FailureLink>string3</WSReq:FailureLink>
    <WSReq:ResponseURL>string2</WSReq:ResponseURL>
    <WSReq:TimeoutInSeconds>600</WSReq:TimeoutInSeconds>
    <WSReq:AutoTransaction>false</WSReq:AutoTransaction>
<Signature xmlns="http://www.w3.org/2000/09/xmldsig#"><SignedInfo><CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#WithComments"/><SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"/><Reference URI=""><Transforms><Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/></Transforms><DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"/><DigestValue>zAxQWVotXo8PnKnZzJ+dRIYqKAQ=</DigestValue></Reference></SignedInfo><SignatureValue>FgwFP1Y6VKwLm/ZjRDWOoqVm2j5mnaOqzp20lFfUgUwTQ26uQyUoXZ2LZNmTrCCym7PNjsSN3sQ8
b0BQWI9Z7ILMZsLcLGRraFOq30oEM0nSSdYMHevzpRpxTu7T66nF/TyZ+MPC05ic//PV2Ab+OC+J
ue28zOnbZzWAqYqnVOQ=</SignatureValue></Signature></WSReq:WebShopRequest>

Который валидируется таким ключом: https://github.com/allpaykz/allpay-public/blob/develop/webshop-integration/webshop-integration-keypair/src/test/resources/mockKeys/TEST.pub.pem

innopay

Provide feedback

Saved searches

Use saved searches to filter your results more quickly