CUP Banks

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

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

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

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

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

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;
   • payment_description — описание платежа.
3. Для предварительного выбора метода CUP Banks необходимо указывать в параметре force_payment_method код платёжного метода — cup-bank.
4. Валютой платежа может быть только CNY.
5. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page.
6. После указания целевых параметров необходимо составлять подпись (подробнее — в разделе Работа с подписью к данным).

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

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

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

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

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

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

 {
        "project_id": 200,
        "payment": {
            "id": "ECT_TEST_15528942647389318",
            "type": "purchase",
            "status": "success",
            "date": "2019-03-19T15:22:05+0000",
            "method": "cup-bank",
            "sum": {
                "amount": 10000,
                "currency": "CNY"
            },
            "description": "ECT_TEST_1552894260335"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 24276000000595,
            "type": "sale",
            "status": "success",
            "date": "2019-03-19T15:22:05+0000",
            "created_date": "2019-03-19T15:18:11+0000",
            "request_id": "6cb000fda4402cabff6b7a4c7f9f301eec3d8d52",
            "sum_initial": {
                "amount": 10000,
                "currency": "CNY"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "CNY"
            },
            "provider": {
                "id": 1129,
                "payment_id": "4RrI6DNXLhRWZuMKnOd4MqFd9yPDw4Yk",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "H9j5S+t+jKeVs717ET765vHJKIISkNb4YdkIemQDjTMKlH
                          eskFU6OjIlIzvgnJCFhJxiKNLstiVoAUrWbDAHSQ=="
    }

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

 {
        "project_id": 580,
        "payment": {
            "id": "cup-bank-012",
            "type": "purchase",
            "status": "decline",
            "date": "2019-03-27T10:58:25+0000",
            "method": "cup-bank",
            "sum": {
                "amount": 1002,
                "currency": "CNY"
            },
            "description": "cup-bank-test-payout"
        },
        "account": {
            "number": "6217003760136456530"
        },
        "customer": {
            "id": "金艳"
        },
        "operation": {
            "id": 30960000000814,
            "type": "sale",
            "status": "decline",
            "date": "2019-03-27T10:58:26+0000",
            "created_date": "2019-03-27T10:58:23+0000",
            "request_id": "65a09bb143bc051a9fa326155ac509768",
            "sum_initial": {
                "amount": 1002,
                "currency": "CNY"
            },
            "sum_converted": {
                "amount": 1002,
                "currency": "CNY"
            },
            "provider": {
                "id": 1180,
                "payment_id": "",
                "auth_code": ""
            },
            "code": "20105",
            "message": "Insufficient funds on customer account"
        },
        "signature": "Hn53oZbiN1/yTQXuMuLih+ojsQrkpFqByvwXz1q2WEIiw
                       VO2K8h7uqYpyKJDayaAjnFGm1PFkqCA+E/nVQ1Hcg=="
    }

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

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

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

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

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

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

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

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

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

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

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

{
    "general": {
    "project_id": 200,
    "payment_id": "ECT_TEST_1559106834731-9",
    "signature": "yzWwFC70Exu6K5UhylPzyh8/QORz6HjULx87emy3AybWK4U1
                         wVJCU8bja04/+m7BBpkx3NoL5/n76ZPxLd0BQA=="
  },
  "customer": {
    "ip_address": "111.254.255.479",
    "first_name": "Maru",
    "last_name": "Maru",
    "street":"street",
    "city": "city",
    "zip": "123045607",
    "country": "CH",
    "phone": "120450780",
    "email": "test@email.com",
    "id": "123"
    }
  },
  "payment": {
    "amount": 1000,
    "currency": "CNY", 
    "description": "test payment"
  },
  "return_url":{
      "success" : "http://success.com"
  }
}

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

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

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

"redirect_data": {
            "method": "GET",
            "body": {
            merchantId: "0004",
            version: "v1",
            inputCharset: "UTF-8",
            merchantTradeId: "dslkjfhslkhfssdusk.jnk.s",
            currency: "CNY",
            payType: "EC",
            issuingBank: "UNIONPAY",
            amountFee: "502",
            deviceType: "WEB",
            goodsTitle: "结算款项",
            returnUrl: "https://www.funtopay.com/hefu/return/",
            notifyUrl: "https://www.funtopay.com/hefu/notify/",
            signType: "RSA",
            sign: "TZUmn8bhp7BO93V06JxJCaf5xi+Sne0eVfVOCt1mi6+YAdnY/IfbEBHC2yPXTRRGmquaKSE3uuiL6AfnOm
            dTtjJznRCw3Wo5jjfSwE0GkG+D25XlC712Et33l0TH+Gcf4QRiba6xOVlvPKpK0OK/svObtPpPr0o/q+8zTX+El6w="
        },
            "encrypted": [],
            "url": "http://payment.qixiqiang.com/payment/v3/unionpayIntGate.html"
        }

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

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

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

 {
        "project_id": 200,
        "payment": {
            "id": "ECT_TEST_15528942647389318",
            "type": "purchase",
            "status": "success",
            "date": "2019-03-19T15:22:05+0000",
            "method": "cup-bank",
            "sum": {
                "amount": 10000,
                "currency": "CNY"
            },
            "description": "ECT_TEST_1552894260335"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 24276000000595,
            "type": "sale",
            "status": "success",
            "date": "2019-03-19T15:22:05+0000",
            "created_date": "2019-03-19T15:18:11+0000",
            "request_id": "6cb000fda4402cabff6b7a4c7f9f301eec3",
            "sum_initial": {
                "amount": 10000,
                "currency": "CNY"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "CNY"
            },
            "provider": {
                "id": 1129,
                "payment_id": "4RrI6DNXLhRWZuMKnOd4MqFd9yPDw4Yk",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "H9j5S+t+jKeVs717ET765vHJKIISkNb4YdkIemQDj
                     TMKlHeskFU6OjIlIzvgnJCFhJxiKNLstiVoAUrWbDAHSQ=="
    }

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

 {
        "project_id": 580,
        "payment": {
            "id": "cup-bank-012",
            "type": "purchase",
            "status": "decline",
            "date": "2019-03-27T10:58:25+0000",
            "method": "cup-bank",
            "sum": {
                "amount": 1002,
                "currency": "CNY"
            },
            "description": "cup-bank-test-payout"
        },
        "account": {
            "number": "6217003760136456530"
        },
        "customer": {
            "id": "金艳"
        },
        "operation": {
            "id": 30960000000814,
            "type": "payout",
            "status": "decline",
            "date": "2019-03-27T10:58:26+0000",
            "created_date": "2019-03-27T10:58:23+0000",
            "request_id": "65a09bb143bc051a9fa326155ac5097",
            "sum_initial": {
                "amount": 1002,
                "currency": "CNY"
            },
            "sum_converted": {
                "amount": 1002,
                "currency": "CNY"
            },
            "provider": {
                "id": 1180,
                "payment_id": "",
                "auth_code": ""
            },
            "code": "20105",
            "message": "Insufficient funds on customer account"
        },
        "signature": "Hn53oZbiN1/yTQXuMuLih+ojsQrkpFqByvwXz1q2W
                     EIiwVO2K8h7uqYpyKJDayaAjnFGm1PFkqCA+E/nVQ1Hcg=="
    }

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

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

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

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

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

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

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

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

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. Валютой платежа может быть только CNY.
5. Дополнительно могут использоваться все параметры, указанные в спецификации.

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

{
    "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 Banks используется стандартный формат, описание которого представлено в разделе Оповещения.

В следующем примере оповещение свидетельствует о том, что в рамках проекта 200 для пользователя 1 была успешно проведена выплата в размере 215,00 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": 21500,
                "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": 21500,
                "currency": "CNY"
            },
            "sum_converted": {
                "amount": 21500,
                "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_12897456238746287",
            "type": "payout",
            "status": "decline",
            "date": "2019-03-25T12:46:51+0000",
            "method": "cup-bank",
            "sum": {
                "amount": 10000,
                "currency": "CNY"
            },
            "description": ""
        },
        "account": {
            "number": "621661******6993"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 35102000000612,
            "type": "payout",
            "status": "decline",
            "date": "2019-03-25T12:46:51+0000",
            "created_date": "2019-03-20T11:45:09+0000",
            "request_id": "c44aae5ae361b649a6225994e626d6cd",
            "sum_initial": {
                "amount": 10000,
                "currency": "CNY"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "CNY"
            },
            "provider": {
                "id": 1129,
                "payment_id": "NqIy87k9SLcDRmkPa1JfM6cQZ53M",
                "date": "2019-03-25T12:46:49+0000",
                "auth_code": ""
            },
            "code": "20106",
            "message": "Customer account is no longer available"
        },
        "signature": "bSqa2y0QnfV6xc1WdSNiNPKZkj100QeSVqtVDRmJaPP...=="
    }

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

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

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

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

Для метода CUP Banks доступно тестирование оплат через Payment Page и Gate, а также выплат через Gate.

Тестирование может выполняться в рамках тестового проекта, и для подключения и отключения этой функциональности необходимо обращаться к специалистам технической поддержки ecommpay support@ecommpay.com.

При проведении тестовых платежей следует учитывать, что в запросах должен указываться идентификатор тестового проекта, а интерфейсы эмулятора платёжных форм Payment Page и CUP Banks могут отличаться от рабочих.

Статусы тестовых платежей

При тестировании оплат их итоговые статусы определяются исходя из сумм, указанных в запросах:

• decline — при указании суммы 40000 или 40400,
• success — при указании любой другой суммы.

При тестировании выплат их итоговые статусы определяются исходя из сумм, указанных в запросах:

• decline — при указании суммы 40000 или 40400,
• success — при указании любой другой суммы.

Оплаты через Payment Page

Для проведения тестовой оплаты через Payment Page необходимо:

1. Отправить в платёжную платформу корректный тестовый запрос на открытие Payment Page.
2. Если в запросе не был указан метод cup-bank — выбрать метод CUP Banks на странице эмулятора.
3. Указать необходимые данные в полях ввода.
4. Щёлкнуть кнопку Success или Decline (в зависимости от запрашиваемой суммы).
5. Принять оповещение с информацией о результате оплаты.

Подробная информация о проведении оплат с использованием метода CUP Banks через Payment Page представлена в пункте Оплаты через Payment Page.

Оплаты через Gate

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

1. Отправить в платёжную платформу корректный тестовый запрос на оплату.
2. Принять оповещение с данными для перенаправления.
3. Перейти по полученному URL и щёлкнуть кнопку Success или Decline (в зависимости от запрашиваемой суммы) — на странице эмулятора.
4. Принять оповещение с информацией о результате оплаты.

Подробная информация о проведении оплат с использованием метода CUP Banks через Gate представлена в пункте Оплаты через Gate.

Выплаты через Gate

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

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

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

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

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

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