CUP QuickPay

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

Для оплаты через Payment Page с использованием метода CUP QuickPay со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay и принять оповещение о результате оплаты. При этом метод CUP QuickPay можно делать предварительно выбранным (подробнее — в разделе Предварительный выбор платёжных методов). Полная схема проведения оплаты представлена далее.

Информация о формате запросов и параметрах вызова Payment Page при работе с методом CUP QuickPay, а также о формате оповещений о результатах оплат приведена далее. Общая информация о работе с API — в разделе Описание Payment Page API.

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

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

1. Должен использоваться базовый минимум параметров — параметры, обязательные для любого платёжного метода:
   • project_id — идентификатор проекта, полученный от ecommpay при интеграции;
   • payment_id — идентификатор платежа, уникальный в рамках проекта;
   • payment_amount — сумма платежа в дробных единицах валюты;
   • payment_currency — валюта платежа в формате ISO-4217 alpha-3;
   • customer_id — идентификатор пользователя в рамках проекта.
2. Дополнительно должен использоваться параметр language_code — код языка Payment Page в формате ISO 639-1 alpha-2; необходимо указать код zh.
3. Дополнительно должен использоваться параметр payment_description — описание или комментарий к платежу.
4. Для предварительного выбора метода CUP QuickPay необходимо указывать в параметре force_payment_method код платёжного метода — cup-quick.
5. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page.
6. После указания целевых параметров необходимо составлять подпись (подробнее — в разделе Работа с подписью к данным).

Таким образом, корректный запрос на открытие платёжной формы с применением метода CUP QuickPay должен содержать идентификатор, валюту и сумму платежа, идентификатор проекта и пользователя, код языка и подпись:

EPayWidget.run(
    { payment_id: 'TEST_154', 
      payment_amount: 1000, 
      payment_currency: 'CNY', 
      project_id: 581, 
      language_code: 'zh',  
      customer_id: 'customer121',
      payment_description: 'TEST_1557900746307',
      signature: "kq970XaXE0Ig0s%2B4%2BM2gtmkytwe3%2BP1pzXw%2BNPTTG...=="
    }
)

Детальная информация обо всех указанных параметрах приведена в разделе Параметры вызова платёжной формы.

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

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

В следующем примере оповещение свидетельствует о том, что в рамках проекта 580 была успешно проведена оплата в размере 10,00 CNY.

 {
        "project_id": 580,
        "payment": {
            "id": "TEST_15532590003171111",
            "type": "purchase",
            "status": "success",
            "date": "2019-03-25T03:56:01+0000",
            "method": "quick",
            "sum": {
                "amount": 1000,
                "currency": "CNY"
            },
            "description": "TEST_15532590003171111"
        },
        "operation": {
            "id": 24101000000751,
            "type": "sale",
            "status": "success",
            "date": "2019-03-25T03:56:01+0000",
            "created_date": "2019-03-25T03:54:57+0000",
            "request_id": "gh72ef7c07157e6bde92072a52",
            "sum_initial": {
                "amount": 1000,
                "currency": "CNY"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "CNY"
            },
            "provider": {
                "id": 1198,
                "payment_id": "190325115517201000",
                "date": "2019-03-25T11:55:55+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "j8704ugh4Kt7E+IezTbe96ecupSki6DbyC5e/89/YW6/
                      BbF+Qh8zcud6s/u4C4qA6W58E6LDftzWjKLfwTeG5bQ=="
    }

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

 {
        "project_id": 580,
        "payment": {
            "id": "TEST_155325900031711",
            "type": "purchase",
            "status": "decline",
            "date": "2019-03-22T14:51:20+0000",
            "method": "quick",
            "sum": {
                "amount": 1000,
                "currency": "CNY"
            },
            "description": "TEST_155325900031711"
        },
        "operation": {
            "id": 21449000000697,
            "type": "sale",
            "status": "decline",
            "date": "2019-03-22T14:51:20+0000",
            "created_date": "2019-03-22T12:50:43+0000",
            "request_id": "01c9b7a9152b6991b6d22e8c46bedaec5",
            "sum_initial": {
                "amount": 1000,
                "currency": "CNY"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "CNY"
            },
            "provider": {
                "id": 1198,
                "payment_id": "190322205110731000",
                "date": "2019-03-22T21:52:19+0000",
                "auth_code": ""
            },
            "code": "20105",
            "message": "Insufficient funds on customer account"
        },
        "signature": "PFsxBI4v59YN917MCq0vcgiTAjSKo/nGtv7U2+xskpamu1drPF...=="
    }

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

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

• Организация взаимодействия
• Работа с подписью к данным
• Модель проведения платежей
• Информация о выполнении операций

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

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

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

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

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

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

1. Должен использоваться запрос, отправляемый методом POST на /v2/payment/cup/quick/sale.
2. В запросе должны использоваться следующие объекты и параметры:
   • general — объект, содержащий основные идентификационные сведения запроса:
     • project_id — идентификатор проекта, полученный от ecommpay при интеграции;
     • payment_id — идентификатор платежа, уникальный в рамках проекта;
     • signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Использование подписи к данным);
   • customer — объект, содержащий сведения о пользователе:
     • id — идентификатор, уникальный в рамках проекта,
     • ip_address — IP-адрес,
     • first_name — имя, написанное только на китайском языке,
     • last_name — фамилия, написанное только на китайском языке,
     • phone — номер телефона без знака +,
     • email — адрес электронной почты,
     • zip — почтовый индекс,
     • country — страна в формате ISO 3166-1 alpha-2,
     • city — город на китайском,
     • street — адрес на китайском;
   • payment — объект, содержащий сведения о платеже:
     • amount — сумма платежа в дробных единицах валюты,
     • currency — валюта платежа в формате ISO-4217 alpha-3,
     • description — описание или комментарий к платежу;
   • return_url — объект, содержащий URL для возврата пользователя с сайта банка в проект мерчанта после совершения оплаты:
     • success — URL возврата в случае проведенного патежа.
3. Дополнительно могут использоваться все параметры, указанные в спецификации.

Таким образом, корректный запрос на оплату с применением метода CUP QuickPay должен общие данные о запросе,платеже, и пользователе:

{
  "general": {
    "project_id": 200,
    "payment_id": "ECT_TEST_1559134591371-pz-3",
    "signature": "pK1YN6fd7yajGSWAzsbYeJo5nvotVBtOijOzgFvAU5Cc8PB...=="
  },
  "customer": {
    "ip_address": "183.57.40.238",
    "first_name": "伍",
    "last_name": "倩文",
    "phone": "13632264147",
    "email": "2524243674@email.com",
    "street":"street",
    "city": "city",
    "zip": "123045607",
    "country": "CH",
    "id": "123"
    }
  },
  "payment": {
    "amount": 1000,
    "currency": "CNY",    
    "description": "payment"
  },
  "return_url: {
    "success": "http://example.com"
  }
}

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

Для перенаправления пользователя от веб-сервиса на сайт сервиса CUP QuickPay необходимо принять оповещение от платёжной платформы, содержащее ссылку для перенаправления в параметре redirect_data.url и данные для отправки в теле запроса redirect_data.body, и использовать эти параметры при открытии HTML-страницы сайта методом, указанным в redirect_data.method. Данные в теле запроса redirect_data.body могут отличаться в зависимости от провайдера, обрабатывающего платёж.

Далее приведён фрагмент оповещения, содержащего URL для перенаправления.

 "redirect_data": {
            "method": "GET",
            "body": {
                "deviceType": "WEB",
                "amountFee": "10.00",
                "sign": "****************",
                "cardType": "D",
                "merchantTradeId": "21449000000697",
                "userName": "",
                "version": "1.0",
                "paymentCard": "",
                "issuingBank": "UNIONPAY",
                "payType": "NC",
                "merchantId": "4245",
                "payIp": "185.123.193.224",
                "signType": "RSA",
                "notifyUrl": "https://site.com/cup/callback",
                "inputCharset": "UTF-8",
                "currency": "CNY",
                "goodsTitle": "ECT_TEST_155325900031711",
                "returnUrl": "https://site.com/gogkjotvmr3hi96gdnd8i1s3",
                "subIssuingBank": ""
            },
            "encrypted": [],
            "url": "http://payment.qixiqiang.com/payment/v3/unionpayIntGate.html"
        }

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

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

В следующем примере оповещение свидетельствует о том, что в рамках проекта 580 была успешно проведена оплата в размере 10,00 CNY.

 {
        "project_id": 580,
        "payment": {
            "id": "ECT_TEST_15532590003171111",
            "type": "purchase",
            "status": "success",
            "date": "2019-03-25T03:56:01+0000",
            "method": "quick",
            "sum": {
                "amount": 1000,
                "currency": "CNY"
            },
            "description": "ECT_TEST_15532590003171111"
        },
        "operation": {
            "id": 24101000000751,
            "type": "sale",
            "status": "success",
            "date": "2019-03-25T03:56:01+0000",
            "created_date": "2019-03-25T03:54:57+0000",
            "request_id": "gh72ef7c07157e6bde92072a52",
            "sum_initial": {
                "amount": 1000,
                "currency": "CNY"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "CNY"
            },
            "provider": {
                "id": 1198,
                "payment_id": "190325115517201000",
                "date": "2019-03-25T11:55:55+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "j8704ugh4Kt7E+IezTbe96ecupSki6DbyC5e/89/YW6/
                      BbF+Qh8zcud6s/u4C4qA6W58E6LDftzWjKLfwTeG5bQ=="
    }

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

 {
        "project_id": 580,
        "payment": {
            "id": "ECT_TEST_155325900031711",
            "type": "purchase",
            "status": "decline",
            "date": "2019-03-22T14:51:20+0000",
            "method": "quick",
            "sum": {
                "amount": 1000,
                "currency": "CNY"
            },
            "description": "ECT_TEST_155325900031711"
        },
        "operation": {
            "id": 21449000000697,
            "type": "sale",
            "status": "decline",
            "date": "2019-03-22T14:51:20+0000",
            "created_date": "2019-03-22T12:50:43+0000",
            "request_id": "01c9b7a9152b6991b6d22e8c46bedaec5",
            "sum_initial": {
                "amount": 1000,
                "currency": "CNY"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "CNY"
            },
            "provider": {
                "id": 1198,
                "payment_id": "190322205110731000",
                "date": "2019-03-22T21:52:19+0000",
                "auth_code": ""
            },
            "code": "20105",
            "message": "Insufficient funds on customer account"
        },
        "signature": "PFsxBI4v59YN917MCq0vcgiTAjSKo/nGtv7U2+xskpamu1drPF0os
                                        pdxsTZYSqLVCfqqy9HAK19IgF6cxCKctg=="
    }

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

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

• Организация взаимодействия
• Работа с подписью к данным
• Модель проведения платежей
• Информация об операциях

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

Для выплаты через Gate с использованием метода CUP QuickPay со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL ecommpay и принять оповещение о результате выплаты. Полная схема проведения выплаты представлена далее.

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

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

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

1. Должен использоваться запрос, отправляемый методом POST на /v2/payment/chinaunionpay/payout.
2. В запросе должны использоваться следующие объекты и параметры:
   • general — объект, содержащий основные идентификационные сведения запроса:
     • project_id — идентификатор проекта, полученный от ecommpay при интеграции;
     • payment_id — идентификатор платежа, уникальный в рамках проекта;
     • signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Использование подписи к данным);
   • customer — объект, содержащий сведения о пользователе:
     • id — идентификатор,
     • ip_address — IP-адрес,
     • email — адрес электронной почты,
     • phone — номер телефона без знака +,
     • state — провинция на китайском,
     • city — город на китайском,
     • country — страна (значение параметра всегда CN),
     • zip — почтовый индекс,
     • street — адрес на китайском,
     • first_name — имя на китайском,
     • last_name — фамилия на китайском;
   • payment — объект, содержащий сведения о платеже:
     • amount — сумма платежа в дробных единицах валюты,
     • currency — валюта платежа в формате ISO-4217 alpha-3;
     • description — описание платежа;
   • card — объект, содержащий сведения о банковской карте или счёте пользователя:
     • pan — номер банковской карты (для некоторых провайдеров требуется указать номер банковского счёта пользователя, подробности следует уточнять у курирующего менеджера ecommpay);
   • account — объект, содержащий сведения о банковском счёте пользователя:
     • city — город из адреса банка,
     • bank_id — идентификатор банка (информация о названиях банков и соответствующих им идентификаторах представлена в пункте Поддержка со стороны банков),
     • region_id — идентификатор региона банка (информация о названиях банков и соответствующих им идентификаторах представлена в пункте Регионы проведения выплат),
     • branch — филиал (аббревиатура).
3. Дополнительно для повышения проходимости можно использовать параметр customer.identify.doc_number — номер документа, подтверждающего личность.
4. Дополнительно могут использоваться все параметры, указанные в спецификации.

Таким образом, корректный запрос на выплату с применением метода CUP QuickPay должен содержать общие данные о запросе, данные о платеже, пользователе, счёте и номер карты:

{
    "general": {
        "project_id": 255,
        "payment_id": "TEST_15392667771145",
        "signature": "Uhka8CiYAlDlc2wRq60vlSmTTCb0Zp0KYV4NF0...=="
    },
    "customer": {
        "id": "127",
        "ip_address": "185.123.193.224",
        "email": "qwe@qw.qw",
        "state": "state",
        "city": "city",
        "country": "CN",
        "phone": "phone",
        "zip": "zip",
        "street": "street",
        "first_name": "伍",
        "last_name": "倩文",
        "identify": {
            "doc_number": "23512361283"
    },
    "payment": {
        "amount": 501,
        "currency": "CNY"
    }, 
    "card": {
        "pan": "621661******6793"
   },  
    "account": {
        "bank_id": "123",
        "branch": "qwert",
        "city": "City",
        "region_id": "region_id"
    }
}

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

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

В следующем примере оповещение свидетельствует о том, что в рамках проекта 200 для пользователя 1 была успешно проведена выплата в размере 485,60 CNY.

{
        "project_id": 200,
        "payment": {
            "id": "ECT_TEST_1563863519243_test2-gate-4",
            "type": "payout",
            "status": "success",
            "date": "2019-08-28T08:44:51+0000",
            "method": "ChinaUnionPay",
            "sum": {
                "amount": 48560,
                "currency": "CNY"
            },
            "description": "ECT_TEST_1563863519243"
        },
        "account": {
            "number": "621799******3840"
        },
        "customer": {
            "id": "1",
            "phone": "89102345678"
        },
        "operation": {
            "id": 45343000001495,
            "type": "payout",
            "status": "success",
            "date": "2019-08-28T08:44:51+0000",
            "created_date": "2019-08-28T08:42:08+0000",
            "request_id": "c21daec7a134",
            "sum_initial": {
                "amount": 48560,
                "currency": "CNY"
            },
            "sum_converted": {
                "amount": 48560,
                "currency": "CNY"
            },
            "provider": {
                "id": 1321,
                "payment_id": "10019082821621938",
                "date": "2019-08-28T16:42:12+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "aW/oS/l7RTlKabsqCZXs1zile11EIX8mkM3+gJfwddjvtszeiMXcU7...=="
    }

В следующем примере выплата была отклонена по причине того, что аккаунт пользователя больше не доступен.

{
        "project_id": 200,
        "payment": {
            "id": "ECT_TEST_122127637126536125",
            "type": "payout",
            "status": "decline",
            "date": "2019-03-22T14:02:44+0000",
            "method": "cup-card",
            "sum": {
                "amount": 48560,
                "currency": "CNY"
            },
            "description": ""
        },
        "account": {
            "number": "621661******6993"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 32988000000665,
            "type": "payout",
            "status": "decline",
            "date": "2019-03-22T14:02:44+0000",
            "created_date": "2019-03-22T14:02:12+0000",
            "request_id": "b78ffab13002d994a6a572410b943ed110",
            "sum_initial": {
                "amount": 48560,
                "currency": "CNY"
            },
            "sum_converted": {
                "amount": 48560,
                "currency": "CNY"
            },
            "provider": {
                "id": 1191,
                "payment_id": "6UBPgonfNE4kjjPB6HoV5pjTdBo34Lni",
                "date": "2019-03-22T14:02:43+0000",
                "auth_code": ""
            },
            "code": "20106",
            "message": "Customer account is no longer available"
         },
        "signature": "rP/FoxRIdBJtMLKP5KAndJwmJHWQ3HXsDCpcbmaaqqk
                    8w26a2toW057NtmDcT+Rgenr2hxTMYit9JUmQkYdtVg=="
    }

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

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

• Организация взаимодействия
• Работа с подписью к данным
• Модель проведения платежей
• Информация об операциях

Как и при работе с другими платёжными методами, которые предоставляет ecommpay, при использовании метода CUP QuickPay доступны разные способы анализа информации о платежах и операциях с применением этого метода — как в отдельности, так и в совокупности с другими методами.

Всю необходимую информацию можно получать и анализировать средствами Dashboard, в том числе с помощью аналитических панелей на вкладке Analytics.

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

• Dashboard позволяет выгружать данные в форматах CSV и XLS с помощью инструментов на вкладке Платежи. При этом можно выполнять разовые выгрузки информации на локальный компьютер и задействовать периодическую выгрузку и отправку информации на заданные адреса электронной почты.
• Data API позволяет получать информацию в формате JSON и отправлять ее на заданный URL — для этого применяются запросы /operations/get.

С любыми вопросами о возможностях анализа можно обращаться в службу технической поддержки ecommpay.