WeChat

Введение

WeChat — метод, позволяющий проводить платежи в разных валютах с использованием электронного кошелька в Китае. Для этого метода в платёжной платформе ecommpay поддерживаются оплаты и возвраты.

В этой статье представлена информация о работе с методом WeChat: обзорный раздел с общими сведениями и последующие разделы с информацией о действиях, необходимых со стороны мерчанта для решения разных задач.

Характеристика

Схема работы

В проведении отдельного платежа с использованием метода WeChat задействуются веб-сервис мерчанта, один из интерфейсов ecommpay, а также технические средства сервиса WeChat.

Основные операции

Для проведения платежей и выполнения операций с использованием метода WeChat могут применяться различные интерфейсы платёжной платформы. Так, оплаты могут проводиться через Payment Page, Gate и Dashboard (с применением платёжных ссылок), а возвраты — через Gate и Dashboard.

Сценарии использования

Проведение оплат с использованием метода WeChat осуществляется с перенаправлением пользователей к сервису WeChat, выполнение возвратов — с заявкой со стороны пользователя и уведомлением со стороны веб-сервиса.

Сценарии выполнения операций через основные интерфейсы платёжной платформы соответствуют представленным на схемах. При использовании дополнительных возможностей (таких как платёжные ссылки) сценарии выполнения операций методом WeChat соответствуют специфике этих возможностей.

Общая информация

Для проведения оплаты через Payment Page с использованием метода WeChat со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay и принять оповещение о результате. Полная схема проведения оплаты выглядит следующим образом.

Информация о форматах запросов и оповещений, используемых для проведения оплат методом WeChat через Payment Page, приведена далее в этом разделе; общая информация о работе с Payment Page API — в отдельной статье Организация взаимодействия.

Формат запросов

При формировании запросов на открытие платёжной формы с применением метода WeChat необходимо учитывать следующее:

1. Должен использоваться базовый минимум параметров, обязательный для любого платежа:
   • project_id — идентификатор проекта, полученный от ecommpay при интеграции;
   • payment_id — идентификатор платежа, уникальный в рамках проекта;
   • payment_currency — код валюты платежа в формате ISO-4217 alpha-3;
   • payment_amount — сумма платежа в дробных единицах валюты;
   • customer_id — идентификатор пользователя в рамках проекта.
2. Должен использоваться базовый минимум параметров: project_id, payment_id, payment_currency, payment_amount, customer_id.
3. В некоторых случаях необходимо использование параметра language_code — код языка платёжной формы. Более подробная информация представлена в статье Управление языком платёжной формы. Необходимость использования данного параметра уточняйте у курирующего менеджера ecommpay.
4. Для предварительного выбора метода WeChat необходимо указывать код этого метода в параметре force_payment_method — wechat.
5. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page (подробнее).
6. После указания всех целевых параметров необходимо составлять подпись (подробнее).

Таким образом, корректный запрос на открытие платёжной формы с применением метода WeChat должен содержать идентификатор проекта, базовые сведения о платеже (идентификатор, сумму и код валюты), код языка, идентификатор пользователя и подпись.

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "language_code": "zh", 
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "EUR",
   "customer_id": "customer1",
   "language_code": "zh", 
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

Формат оповещений

Для оповещений о результатах оплат с применением метода WeChat используется типовой формат, описание которого представлено в статье Оповещения.

В следующем примере оповещение свидетельствует о том, что в рамках проекта 238 была проведена оплата в размере 1,00 EUR.

 {
        "project_id": 238,
        "payment": {
            "id": "TEST_154866061847343331",
            "type": "purchase",
            "status": "success",
            "date": "2019-01-28T08:07:22+0000",
            "method": "wechat",
            "sum": {
                "amount": 100,
                "currency": "EUR"
            },
            "description": "TEST_1548660618473453"
        },
        "operation": {
            "id": 9227000002916,
            "type": "sale",
            "status": "success",
            "date": "2019-01-28T08:07:22+0000",
            "created_date": "2019-01-28T08:06:40+0000",
            "request_id": "67af98801524dfa9c5cddb1a09129",
            "sum_initial": {
                "amount": 100,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 100,
                "currency": "EUR"
            },
            "provider": {
                "id": 1173,
                "payment_id": "423163569",
                "date": "2019-01-28T08:07:22+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "yuuYzrj3kD1cGJrJMo8oJqiyD7GgoTS+mvRA=="
    }

В следующем примере оповещение свидетельствует об отклонённой оплате.

{
        "project_id": 238,
        "payment": {
            "id": "TEST_154996862174000",
            "type": "purchase",
            "status": "decline",
            "date": "2019-02-12T10:56:22+0000",
            "method": "wechat",
            "sum": {
                "amount": 10000,
                "currency": "USD"
            },
            "description": "TEST_154996862174000"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 9172000003183,
            "type": "sale",
            "status": "decline",
            "date": "2019-02-12T10:56:22+0000",
            "created_date": "2019-02-12T10:56:18+0000",
            "request_id": "11d4aabf869cb74c0681927ad7",
            "sum_initial": {
                "amount": 10000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "USD"
            },
            "provider": {
                "id": 1169,
                "payment_id": "",
                "auth_code": ""
            },
            "code": "20105",
            "message": "Insufficient funds on customer account"
        },
        "signature": "ghmnbvc1oVdS/mE0AlVJRrqn7HiBOEIObz2tN5SLw=="
    }
}

Дополнительные материалы

Для организации работы с оплатами через Payment Page также могут быть полезны следующие материалы:

• Организация взаимодействия — о том, как организовать взаимодействие веб-сервиса с платёжной платформой через Payment Page.
• Работа с подписью к данным — о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой.
• Модель проведения платежей — о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций.
• Разовая оплата в одну стадию — о том, как проводить разовые оплаты через Payment Page.
• Информация о выполнении операций — о служебных кодах, которые используются в платёжной платформе, чтобы фиксировать информацию о выполнении операций.

Общая информация

Для проведения оплаты через Gate с использованием метода WeChat со стороны веб-сервиса необходимо:

1. Отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay.
2. Принять промежуточное оповещение от платёжной платформы и осуществить перенаправление пользователя к сервису WeChat.
3. Принять итоговое оповещение от платёжной платформы.

Полная схема проведения оплаты выглядит следующим образом.

Информация о форматах запросов и оповещений, используемых для проведения оплат методом WeChat через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье Организация взаимодействия.

Формат запросов

При работе с запросами на оплаты с применением метода WeChat необходимо учитывать следующее:

1. Для инициирования каждой оплаты должен использоваться отдельный POST-запрос к конечной точке /v2/payment/wallet/wechat/sale. Эта точка относится к группе /v2/payment/wallet/{payment_method}/sale.
2. В каждом запросе должны использоваться следующие объекты и параметры:
   • general — объект, содержащий основные идентификационные сведения запроса:
     • project_id — идентификатор проекта, полученный от ecommpay при интеграции;,
     • payment_id — идентификатор платежа, уникальный в рамках проекта;,
     • signature — подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью); (подробнее),
   • payment — объект, содержащий сведения о платеже:
     • amount — сумма платежа в дробных единицах валюты;,
     • currency — код валюты платежа в формате ISO-4217 alpha-3;,
     • description — описание платежа;,
   • customer — объект, содержащий сведения о пользователе:
     • id — идентификатор пользователя, уникальный в рамках проекта;,
     • ip_address — IP-адрес пользователя, актуальный для инициируемого платежа.
3. Дополнительно, в зависимости от провайдера, обрабатывающего платёж, рекомендуется указывать следующие объекты и параметры:
   • customer — объект, содержащий сведения о пользователе:
     • email — адрес электронной почты пользователя;
     • phone — номер телефона, на который зарегистрирована учетная запись пользователя в сервисе WeChat, указывается с кодом страны, без знаков пунктуации и специальных символов (например, 19121234567), подробнее о формате можно почитать в ответах на вопросы.

   Если какие-либо из этих параметров отсутствуют в запросе, список с названиями недостающих параметров может отправляться в оповещении на уточнение (подробнее — в статье Дополнение информации о платеже).

4. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.

Таким образом, корректный запрос на оплату с применением метода WeChat должен содержать идентификатор проекта, базовые сведения о платеже (идентификатор, сумму и код валюты), информацию о пользователе, а также подпись.

{
  "general": {
    "project_id": 200,
    "payment_id": "TEST_1559134591371-pz-2",
    "signature": "leNRGu/zTi7tB7T1HPmvelSMQmmWyDUcq3rJKqtw=="
  },
  "customer": {
    "ip_address": "192.0.2.0",
    "id": "customer123",
    "email": "customer@example.com",
    "phone": "19121234567"
  },
  "payment": {
    "amount": 1000,
    "currency": "EUR",
    "description": "test payment"
  }
}

{
  "general": {
    "project_id": 200,
    "payment_id": "TEST_1559134591371-pz-2",
    "signature": "leNRGu/zTi7tB7T1HPmvelSMQmmWyDUcq3rJKqtw=="
  },
  "customer": {
    "ip_address": "192.0.2.0",
    "id": "customer123",
    "email": "customer@example.com",
    "phone": "19121234567"
  },
  "payment": {
    "amount": 1000,
    "currency": "EUR",
    "description": "test payment"
  }
}

Форматы данных для перенаправления пользователей

Для перенаправления пользователя от веб-сервиса к сервису WeChat необходимо использовать данные из массива display_data, который передаётся в оповещении от платёжной платформы. Этот массив может содержать один или несколько объектов со следующими параметрами:

• type — тип объекта,
• title — название объекта,
• data — данные, соответствующие указанному типу объекта.

Массив display_data формируется с учётом следующих условий:

• Обязательным является объект с указанием данных для передачи QR-кода. Значение параметра data в таком объекте соответствует значению параметра type, который может принимать следующие значения:
  • qr_url — при передаче QR-кода как ссылки на изображение. В этом случае в параметре data передаётся URL.
  • qr_img — при передаче QR-кода как изображения. В этом случае в параметре data передаётся строка, закодированная с использованием схемы Base64.
  • qr_data — при передаче QR-кода как строки. В этом случае в параметре data передаётся строка, на основании которой на стороне веб-сервиса должен быть создан QR-код.
• В дополнение к обязательному объекту с указанием данных для передачи QR-кода могут передаваться один или несколько объектов c дополнительной информацией. Параметр type таких объектов принимает значение add_info, а в параметре data может передаваться разнообразная информация.
• Если в массиве присутствуют один или несколько объектов с дополнительной информацией, то в такой массив включается объект с информацией о сроке действия QR-кода с момента его создания на стороне сервиса WeChat. Параметру title такого объекта присваивается значение QR Code Timeout, а срок действия указывается в секундах в параметре data.

Далее приведён фрагмент оповещения, содержащего строку для создания QR-кода и срок его действия в качестве дополнительной информации.

 "display_data": [
            {
                "type": "qr_data",
                "title": "QR code",
                "data": "weixin://wxpay/bizpayurl?pr=dMrSpJG"
            },
            {
                "type": "add_info",
                "title": "QR Code Timeout",
                "data": "600"
            }
        ]

Формат оповещений

Для оповещений о результатах оплат с применением метода WeChat используется типовой формат, описание которого представлено в разделе Оповещения.

В следующем примере оповещение свидетельствует о том, что в рамках проекта 238 была проведена оплата в размере 1,00 EUR.

 {
        "project_id": 238,
        "payment": {
            "id": "TEST_154866061847343331",
            "type": "purchase",
            "status": "success",
            "date": "2019-01-28T08:07:22+0000",
            "method": "wechat",
            "sum": {
                "amount": 100,
                "currency": "EUR"
            },
            "description": "TEST_1548660618473453"
        },
        "operation": {
            "id": 9227000002916,
            "type": "sale",
            "status": "success",
            "date": "2019-01-28T08:07:22+0000",
            "created_date": "2019-01-28T08:06:40+0000",
            "request_id": "67af98801524dfa9c5cddb1a09129",
            "sum_initial": {
                "amount": 100,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 100,
                "currency": "EUR"
            },
            "provider": {
                "id": 1173,
                "payment_id": "423163569",
                "date": "2019-01-28T08:07:22+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "yuuYzrj3kD1cGJrJMo8oJqiyD7GgoTS+mvRA=="
    }

В следующем примере оповещение свидетельствует об отклонённой оплате.

{
        "project_id": 238,
        "payment": {
            "id": "TEST_154996862174000",
            "type": "purchase",
            "status": "decline",
            "date": "2019-02-12T10:56:22+0000",
            "method": "wechat",
            "sum": {
                "amount": 10000,
                "currency": "USD"
            },
            "description": "TEST_154996862174000"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 9172000003183,
            "type": "sale",
            "status": "decline",
            "date": "2019-02-12T10:56:22+0000",
            "created_date": "2019-02-12T10:56:18+0000",
            "request_id": "11d4aabf869cb74c0681927ad7",
            "sum_initial": {
                "amount": 10000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "USD"
            },
            "provider": {
                "id": 1169,
                "payment_id": "",
                "auth_code": ""
            },
            "code": "20105",
            "message": "Insufficient funds on customer account"
        },
        "signature": "ghmnbvc1oVdS/mE0AlVJRrqn7HiBOEIObz2tN5SLw=="
    }
}

Дополнительные материалы

Для организации работы с оплатами через Gate также могут быть полезны следующие материалы:

• Организация взаимодействия — о том, как взаимодействовать с платёжной платформой через Gate.
• Работа с подписью — о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой.
• Модель проведения платежей — о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций.
• Разовая оплата в одну стадию — о том, как проводить разовые оплаты через Gate.
• Информация об операциях — о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций.

Общая информация

Для выполнения возврата через Gate с использованием метода WeChat со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay и принять оповещение о результате. В некоторых случаях, по одному платежу вы можете выполнить только один частичный возврат, далее для совершения дополнительных возвратов по этому платежу вам необходимо обратиться в службу технической поддержки платежной системы. Для уточнения информации обратитесь к курирующему менеджеру ecommpay. Полная схема выполнения возврата выглядит следующим образом.

Информация о форматах запросов и оповещений, используемых для выполнения возвратов методом WeChat через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье Организация взаимодействия.

Формат запросов

При работе с запросами на возврат с применением метода WeChat необходимо учитывать следующее:

1. Для инициирования каждого возврата должен использоваться отдельный POST-запрос к конечной точке /v2/payment/wallet/wechat/refund. Эта точка относится к группе /v2/payment/wallet/{payment_method}/refund.
2. В каждом запросе должны использоваться следующие объекты и параметры:
   • general — объект, содержащий основные идентификационные сведения запроса:
     • project_id — идентификатор проекта, полученный от ecommpay при интеграции;,
     • payment_id — идентификатор платежа, для которого необходимо выполнить возврат;,
     • signature — подпись запроса, составленная после указания всех целевых параметров (подробнее — в разделе Работа с подписью); (подробнее)),
   • payment — объект, содержащий сведения о возврате:
     • description — комментарий к возврату или его описание;,
     • amount — сумма возврата в дробных единицах валюты (является обязательной при частичном возврате);,
   • customer — объект, содержащий сведения о пользователе:
     • ip_address — IP-адрес пользователя, актуальный для инициируемого возврата.
3. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации.

Таким образом, корректный запрос на возврат с применением метода WeChat должен содержать идентификаторы проекта и платежа, описание возврата, IP-адрес пользователя, подпись, а также, при необходимости, сумму возврата.

  "general": {    
    "project_id": 239,    
    "payment_id": "refund_02",   
    "signature": "of8k9xerKSK4SwKJ7KLTZYO56lCv+f1M0Sf/7eg=="
  },  
   "customer": {    
     "ip_address": "192.0.2.0" 
 },  
  "payment": {    
    "amount": 10000,    
    "description": "refund_02"
}

  "general": {    
    "project_id": 239,    
    "payment_id": "refund_02",   
    "signature": "of8k9xerKSK4SwKJ7KLTZYO56lCv+f1M0Sf/7eg=="
  },  
   "customer": {    
     "ip_address": "192.0.2.0" 
 },  
  "payment": {    
    "amount": 10000,    
    "description": "refund_02"
}

Формат оповещений

Для оповещений о результатах возвратов с применением метода WeChat используется типовой формат, описание которого представлено в разделе Оповещения.

В следующем примере оповещение свидетельствует о том, что в рамках проекта 238 был выполнен возврат в размере 100,00 USD.

{
        "project_id": 238,
        "payment": {
            "id": "refund_02",
            "type": "purchase",
            "status": "refunded",
            "date": "2019-02-19T14:25:25+0000",
            "method": "wechat",
            "sum": {
                "amount": 10000,
                "currency": "USD"
            },
            "description": "test_02"
        },
        "account": {
            "number": "2626324568"
        },
        "operation": {
            "id": 14153000003282,
            "type": "refund",
            "status": "success",
            "date": "2019-02-19T14:25:25+0000",
            "created_date": "2019-02-19T14:25:24+0000",
            "request_id": "9d11b2ca618ec3ba0f588af8af3c4fc9f5fa58f174",
            "sum_initial": {
                "amount": 10000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "USD"
            },
            "provider": {
                "id": 413,
                "payment_id": "105887607",
                "date": "2019-02-19T14:25:24+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "of8k9xerKSKpFBRKLTZYO56lCv+f1M0Sf/7eg=="
    }

В следующем примере оповещение свидетельствует об отклонённом возврате.

{
        "project_id": 198,
        "payment": {
            "id": "ECT_TEST_15428009030783",
            "type": "purchase",
            "status": "success",
            "date": "2018-11-23T13:46:39+0000",
            "method": "wechat",
            "sum": {
                "amount": 10000,
                "currency": "EUR"
            },
            "description": "ECT_TEST_1542800903078"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 13792000002073,
            "type": "refund",
            "status": "decline",
            "date": "2018-11-30T09:25:36+0000",
            "created_date": "2018-11-30T09:25:33+0000",
            "request_id": "d848450ce489a81f86522434873a99f534e2c",
            "sum_initial": {
                "amount": 10000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "EUR"
            },
            "provider": {
                "id": 413,
                "payment_id": "",
                "auth_code": ""
            },
            "code": "3283",
            "message": "Refund amount more than init amount"
        },
        "signature": "AO081Lg6GT/+VIR1DAqn57Ypq8MxSMtpOBca0mhZ9ag=="
    }

Дополнительные материалы

Для организации работы с возвратами через Gate также могут быть полезны следующие материалы:

• Организация взаимодействия — о том, как взаимодействовать с платёжной платформой через Gate.
• Работа с подписью — о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой.
• Модель проведения платежей — о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций.
• Возвраты средств после оплат — о том, как выполнять возвраты через Gate.
• Информация об операциях — о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций.