Vietnamese OTC (оплата наличными)

Обзор

Vietnamese OTC — платёжный метод для оплат наличными в магазине. Пользователь заказывает товары и услуги онлайн и завершает платёж самостоятельно по чеку или номеру заказа в ближайшем почтовом отделении. Почтовые отделения, которые поддерживают этот платёжный метод, включают Viettelpost и Vietnam post, что делает его удобным способом оплаты для многих вьетнамских пользователей. Оплаты осуществляются через Payment Page и Gate.

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

Тип платёжного метода	платежи через точки оплаты
Платёжные инструменты	наличные
Регионы использования	VN
Валюты платежей	VND
Конвертация валют	–
Оплаты	+
Выплаты	–
Оплаты по сохранённым данным	–
Полные возвраты	–
Частичные возвраты	–
Опротестования	–
Особенности	–
Организация и стоимость подключения	По согласованию с курирующим менеджером ecommpay

Схема работы

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

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

	Интерфейсы				Суммы, VND
	Payment Page	CMS Plug-ins	Gate	Dashboard	минимум	максимум
Оплаты	+	–	+	–	*	20 000 000 000

* Viettel Post — 10 000 VND и Vietnam Post — 20 000 VND.

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

При проведении оплат с использованием метода Vietnamese OTC пользователь совершает оплату наличными в выбранном отделении Viettel Post или Vietnam Post.

Рис.: Оплата через Payment Page

Рис.: Оплата через Gate

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

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

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

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

Рис.: Проведение оплаты через Payment Page

Пользователь на стороне веб-сервиса инициирует оплату.
От веб-сервиса на заданный URL ecommpay передаётся запрос на проведение оплаты через Payment Page.
Запрос на проведение оплаты поступает в платёжную платформу.
Выполняется начальная обработка запроса, в рамках которой обеспечивается проверка наличия обязательных параметров и корректной подписи.
Осуществляется генерация Payment Page согласно настройкам проекта и параметрам вызова.
Пользователю отображается сгенерированная платёжная форма.
Пользователь выбирает для оплаты платёжный метод Vietnam convenience store.
Пользователю отображается список доступных сервисов.
Пользователь выбирает отделение для оплаты (Viettel Post или Vietnam Post).
Запрос на проведение оплаты через Vietnamese OTC поступает в платёжную платформу.
Выполняются дальнейшая обработка запроса и его отправка в сервис Vietnamese OTC.
На стороне Vietnamese OTC выполняется обработка запроса на оплату.
От сервиса Vietnamese OTC к платёжной платформе передаются данные для отображения инструкции по оплате.
От платёжной платформы к Payment Page передаются данные для отображения инструкции по оплате.
Пользователю отображается инструкция для оплаты на Payment Page.
Пользователь выполняет необходимые действия для оплаты.
На стороне сервиса Vietnamese OTC выполняется обработка платежа.
Пользователю приходит письмо по электронной почте с результатом оплаты.
От сервиса Vietnamese OTC к платёжной платформе направляется результат оплаты.
От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
От платёжной платформы к Payment Page направляется результат проведения оплаты.
Результат оплаты отображается пользователю на Payment Page.

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

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

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

Должен использоваться базовый минимум параметров — параметры, обязательные для любого платёжного метода:
- project_id — идентификатор проекта, полученный от ecommpay при интеграции;
- payment_id — идентификатор платежа, уникальный в рамках проекта;
- payment_currency — валюта платежа в формате ISO-4217 alpha-3;
- payment_amount — сумма платежа, без дробной части;
- customer_id — идентификатор пользователя уникальный в рамках проекта.
Валютой платежа может быть только VND.
Для предварительного выбора метода Vietnamese OTC необходимо указывать код платёжного метода в параметре force_payment_method — vietnam-cash.
Дополнительно можно настроить язык письма (английский или вьетнамский) с результатом оплаты. По умолчанию используется вьетнамский язык. Для изменения на английский необходимо передать в параметре customer.language код en.
Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page. Детальная информация обо всех параметрах приведена в разделе Параметры вызова платёжной формы.
После определения всех параметров необходимо составить подпись. Подробную информацию см. в Работа с подписью к данным.

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

EPayWidget.run(
    { payment_id: 'X03936', 
      payment_amount: 2000, 
      payment_currency: 'VND', 
      project_id: 100, 
      customer_id: 'customer1',
      signature: "pu654sjhddKHAVNU0FYldJrxh4yo+52Kt8KU+Y1Y4HASCQ9vySO\/RLC
                                  vhtT4DqtVUkDJrOcZzUCwX6R\/ekpZhkIQg=="
    }
)

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

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

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

Рис.: Пример оповещения о проведенной оплате

 {
        "project_id": 200,
        "payment": {
            "id": "ECT_TEST_15623",
            "type": "purchase",
            "status": "success",
            "date": "2019-07-01T08:47:06+0000",
            "method": "Cash Vietnam",
            "sum": {
                "amount": 20000,
                "currency": "VND"
            },
            "description": "nganluongtest3.2"
        },
        "customer": {
            "id": "1",
            "phone": "0914695523"
        },
        "operation": {
            "id": 34299000003322,
            "type": "sale",
            "status": "success",
            "date": "2019-07-01T08:47:06+0000",
            "created_date": "2019-07-01T08:16:21+0000",
            "request_id": "f8c9775367975429d914c019591e349308ffb199d7916c434c90805",
            "sum_initial": {
                "amount": 20000,
                "currency": "VND"
            },
            "sum_converted": {
                "amount": 20000,
                "currency": "VND"
            },
            "provider": {
                "id": 1284,
                "payment_id": "56368817",
                "auth_code": "",
                "endpoint_id": "VIETTELPOST"
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "OCa7bOyjNbaxVUvtgSxNfvVlQI5gWNY4k7WIB0AyGpxD
                     sdGFknCiLwqopvPs8GZprj7/4c1a6n3n0QRIvv25Fg=="
    }
}

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

Рис.: Пример оповещения об отказе в проведении оплаты

 {
        "project_id": 200,
        "payment": {
            "id": "ECT_TEST_15619",
            "type": "purchase",
            "status": "decline",
            "date": "2019-07-01T07:40:36+0000",
            "method": "Cash Vietnam",
            "sum": {
                "amount": 2000,
                "currency": "VND"
            },
            "description": "nganluongtest3.2"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 39901000003337,
            "type": "sale",
            "status": "decline",
            "date": "2019-07-01T07:40:36+0000",
            "created_date": "2019-07-01T07:40:33+0000",
            "request_id": "3588d3f8fd252b3cabf1af779dfd3e4867d83e2242eba6e6d148",
            "sum_initial": {
                "amount": 2000,
                "currency": "VND"
            },
            "sum_converted": {
                "amount": 2000,
                "currency": "VND"
            },
            "provider": {
                "id": 1284,
                "payment_id": "",
                "auth_code": ""
            },
            "code": "20602",
            "message": "Time-out"
        },
        "signature": "jqTBt8VV8UhK63525hwW9dspYAqUJGLq6GwqIXuvLTmU3Mo
                            DrxZk6/lYm8cPuF/4N14kS3LWfSjCRdrKcaL6Gg=="
    }
}

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

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

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

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

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

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

Полная схема проведения оплаты представлена далее.

Рис.: Проведение оплаты через Gate

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

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

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

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

Должен использоваться запрос /v2/payment/cash/vietnam/sale, отправляемый методом POST. Этот запрос относится к группе запросов для оплаты наличными: /v2/payment/cash/{payment_method}/sale.
В запросе должны использоваться следующие объекты и параметры:
- general — основные сведения:
  - project_id — идентификатор проекта,
  - payment_id — идентификатор платежа,
  - signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Использование подписи к данным);
- customer — сведения о пользователе:
  - id — идентификатор, уникальный в рамках проекта,
  - email — адрес электронной почты,
  - ip_address — используемый IP-адрес;
- account — сведения об отделении:
  - bank_id — идентификатор отделения (Viettel post — 571, Vietnam Post — 572);
- payment — сведения о платеже:
  - amount — сумма,
  - currency — валюта платежа в формате ISO-4217 alpha-3.
Валютой платежа может быть только VND.
Дополнительно можно настроить язык письма (английский или вьетнамский) с результатом оплаты. По умолчанию используется вьетнамский язык. Для изменения на английский необходимо передать в параметре customer.language код en.
Дополнительно могут использоваться все параметры, указанные в спецификации.

Таким образом, корректный запрос на оплату с применением метода Vietnamese OTC должен содержать идентификаторы проекта и платежа, подпись, адрес электронной почты и IP-адрес пользователя, идентификатор отделения, а также валюту и сумму платежа:

Рис.: Пример запроса на оплату

{
    "general": {
        "project_id": 603,
        "payment_id": "test_payment_1",
        "signature": "U585Cm6489ly9cXCKIVBNV0mFr4XiCruECSyQEbT1hSXJ70zu
                             H4s05cFDqLks8ZJMR6iNdlUtm1EdHHdA3D19Qg=="
    },
    "payment": {
        "amount": 3000,
        "currency": "VND"
    },
    "account": {
        "bank_id": 571
    },
    "customer": {
        "email": "test@gmail.com",
        "ip_address": "248.121.176.220",
        "id": "customer123"
    }
}

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

Для завершения оплаты необходимо отобразить пользователям инструкцию. Информация для отображения инструкции содержится в оповещении от платёжной платформы в объекте provider_extra_fields, поэтому прежде чем отобразить инструкцию, надо принять и обработать такое оповещение.

Данные, передаваемые платежной платформой в объекте provider_extra_fields:

support_message — HTML-код с инструкцией,
cashin_id — номер платежной инструкции.

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


"provider_extra_fields": {
            "support_message": ""<b>HƯỚNG DẪN THANH TOÁN TIỀN MẶT TẠI QUẦY VNPOST</b><br/>\n<b>Bước 1:
            Ghi nhớ \"mã giao dịch\" và \"tổng số tiền thanh toán\".</b><br/>\nBạn hãy ghi nhớ thông
            tin dưới đây trước khi ra quầy giao dịch của <b>VNPOST</b><br/>\n- Mã giao dịch: 
            <b>16701876</b><br/>\n- Số tiền thanh toán: <b>1000 VND</b><br/> \n- Nội dung thanh
            toán: <b> Thanh toán cho phiếu thu 16701876</b><br/>\n<b>Bước 2:  Nộp tiền mặt tại 
            quầy giao dịch VNPOST</b><br/>\nBạn báo với nhân viên thu ngân, sử dụng dịch vụ 
            <b>VNPOST - Thu hộ NGANLUONG</b>. Sau đó khai báo Mã giao dịch, xác nhận khoản tiền 
            cần thanh toán, thực hiện nộp đủ số tiền trên cho nhân viên thu ngân.\nNgay khi nhân
            viên thu ngân xác thực thanh toán thành công, giao dịch trên hệ thống Ngân Lượng của 
            bạn sẽ chuyển trạng thái thành công và thông báo cho người nhận.<br/>\n<b></b>",
            "cashin_id": "16701876"
        }

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

Рис.: Пример оповещения о проведенной оплате

 {
        "project_id": 200,
        "payment": {
            "id": "ECT_TEST_15623",
            "type": "purchase",
            "status": "success",
            "date": "2019-07-01T08:47:06+0000",
            "method": "Cash Vietnam",
            "sum": {
                "amount": 20000,
                "currency": "VND"
            },
            "description": "nganluongtest3.2"
        },
        "customer": {
            "id": "1",
            "phone": "0914695523"
        },
        "operation": {
            "id": 34299000003322,
            "type": "sale",
            "status": "success",
            "date": "2019-07-01T08:47:06+0000",
            "created_date": "2019-07-01T08:16:21+0000",
            "request_id": "f8c9775367975429d914c019591e349308ffb199d7916c434c90805",
            "sum_initial": {
                "amount": 20000,
                "currency": "VND"
            },
            "sum_converted": {
                "amount": 20000,
                "currency": "VND"
            },
            "provider": {
                "id": 1284,
                "payment_id": "56368817",
                "auth_code": "",
                "endpoint_id": "VIETTELPOST"
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "OCa7bOyjNbaxVUvtgSxNfvVlQI5gWNY4k7WIB0AyGpxD
                     sdGFknCiLwqopvPs8GZprj7/4c1a6n3n0QRIvv25Fg=="
    }
}

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

Рис.: Пример оповещения об отказе в проведении оплаты

 {
        "project_id": 200,
        "payment": {
            "id": "ECT_TEST_15619",
            "type": "purchase",
            "status": "decline",
            "date": "2019-07-01T07:40:36+0000",
            "method": "Cash Vietnam",
            "sum": {
                "amount": 2000,
                "currency": "VND"
            },
            "description": "nganluongtest3.2"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 39901000003337,
            "type": "sale",
            "status": "decline",
            "date": "2019-07-01T07:40:36+0000",
            "created_date": "2019-07-01T07:40:33+0000",
            "request_id": "3588d3f8fd252b3cabf1af779dfd3e4867d83e2242eba6e6d148",
            "sum_initial": {
                "amount": 2000,
                "currency": "VND"
            },
            "sum_converted": {
                "amount": 2000,
                "currency": "VND"
            },
            "provider": {
                "id": 1284,
                "payment_id": "",
                "auth_code": ""
            },
            "code": "20602",
            "message": "Time-out"
        },
        "signature": "jqTBt8VV8UhK63525hwW9dspYAqUJGLq6GwqIXuvLTmU3Mo
                            DrxZk6/lYm8cPuF/4N14kS3LWfSjCRdrKcaL6Gg=="
    }
}

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

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

Анализ результатов проведения платежей

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

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

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

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

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