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

Sanzhar Aubakirov edited this page Oct 2, 2018 · 43 revisions

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

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

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

СОДЕРЖАНИЕ

  1. ПРИНЦИПЫ ВЗАИМОДЕЙСТВИЯ МЕЖДУ МАГАЗИНОМ И ПС ALLPAY
  2. ПОЛУЧЕНИЕ ЭЦП ДЛЯ ПОДПИСИ ЗАПРОСОВ
  3. СЦЕНАРИЙ ПЛАТЕЖА
  4. ТЕХНИЧЕСКИЕ ДЕТАЛИ ВЗАИМОДЕЙСТВИЯ
  5. ОПИСАНИЕ ФОРМАТА СООБЩЕНИЙ
    1. WesbshopRequest
    2. WebshopResponse
    3. WebshopCustomerResponse
  6. ИСПОЛЬЗОВАНИЕ ТЕСТОВОЙ СИСТЕМЫ ALLPAY
  7. ПРИМЕРЫ ДЕМО РЕАЛИЗАЦИЙ

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

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

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

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

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

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

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

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

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

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

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

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

  1. Покупатель формирует корзину на сайте магазина
  2. Покупатель выбирает ПС Allpay в качестве способа оплаты
  3. Сайт магазина формирует HTTP POST запрос, и перенаправляет Покупателя на портал ПС Allpay https://mfs.allpay.kz/mfs/WebShopPayment.xhtml. В параметры HTTP POST запроса должно быть указано два значения:
  • webshopRequest – Запрос в ПС от магазина, XML сообщение WebShopRequest.
  • loginName - дополнительное необязательное поле для предзаполненного логина на странице входа.
  1. Покупатель авторизуется на портале ПС Allpay.
  2. Проверяется подпись XML.
  3. По полученным XML данным заполняется форма подтверждения платежа.
  4. Покупатель подтверждает платеж.
  5. ПС отправляет подписанное сообщение XML WebShopResponse на веб-сервис магазина при помощи HTTP POST запроса.
  6. Покупатель перенаправляется на веб-страницу магазина, указанную в сообщении WebShopRequest Со стороны магазина для интеграции требуется два веб-сервиса 1) для выдачи запросов WebShopRequest и 2) для получения WebShopResponse. Ключи для подписи и верификации будут выдаваться ПС Allpay после подписания договора.

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

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: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>

  1. WSReq:ShopName Название магазина, которое будет видеть Покупатель на странице подтверждения платежей. Обязательное для заполнения
  2. WSReq:InvoiceNumber Номер заказа, поле должно быть уникальным в базе данных магазина. Обязательное для заполнения
  3. WSReq:Merchant Составное поле, описывающее аккаунт магазина в ПС Allpay. Обязательное для заполнения
  • WSReq:MerchantID Идентификатор магазина в ПС. Выдается в момент заключения договора. Обязательное для заполнения
  • WSReq:WalletID Идентификатор счета в ПС. На этот счет будут переводится деньги от Покупателя. Выдается в момент заключения договора. Обязательное для заполнения
  1. WSReq:Cart Составное поле, описывающее товары в корзине Покупателя.
  • WSReq:Items Составное поле. Описание одной товарной позиции
  • WSReq:Code Код товара
  • WSReq:Name Название товара
  • WSReq:Description Описание товара
  • WSReq:Quantity Количество товара в соответствующей мере измерения
  • WSReq:Cost Стоимость товара
  1. WSReq:TotalCost Общая сумма к оплате. Обязательное для заполнения
  2. WSReq:TimeOutInSeconds Таймаут транзакции. Минимальное значение 600, максимальное 86400. Обязательное для заполнения
  3. WSReq:SuccessLink URL Ссылка магазина, на которую попадёт Покупатель после удачного платежа. Обязательное для заполнения
  4. WSReq:ResponseURL URL Ссылка магазина, на которую высылается ответ после удачного/неудачного платежа. Обязательное для заполнения
  5. WSReq:ProtocolVersion Номер протокола, по которому будут обрабатываться ответы на WebshopResponse. Подробнее
  6. WSReq:FailureLink URL Ссылка магазина, на которую попадёт Покупатель в случае неудачного платежа. Обязательное для заполнения
  7. WSReq:AutoTransaction Автономное проведение транзакции. Необходимо выставить значение true, параметр устарел и оставлен для совместимости.
  8. Signature Подпись. Обязательное для заполнения

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>

Пример подписанной 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>

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

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>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.

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

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

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

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

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

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

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

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

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.