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

Обзор

Введение

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

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

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

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

Схема работы

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

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

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

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

	Суммы, VND ¹
	минимум	максимум
Оплаты	*	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 и принять оповещение о результате. Полная схема проведения оплаты выглядит следующим образом.

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

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

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

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

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

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

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

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 2000,
   "payment_currency": "VND",
   "customer_id": "customer1",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

Рис.: Пример достаточного набора данных для запроса на оплату

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 2000,
   "payment_currency": "VND",
   "customer_id": "customer1",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

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

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

В следующем примере оповещение свидетельствует о том, что в рамках проекта 200 была проведена оплата в размере 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": "test3.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": "f8c9775367975429d914c90805",
            "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": "OCa7bOyjNbaxVUvtgS7/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": "test3.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": "3588d3f8dfd3e4867d83e2242eba6e6d148",
            "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": "jqTBt8VV8UhK63525hwW9N14kS3LWfSjCRdrKcaL6Gg=="
    }
}

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Рис.: Пример достаточного набора данных для запроса на оплату

{
    "general": {
        "project_id": 603,
        "payment_id": "test_payment_1",
        "signature": "U585Cm6489ly9cXCKMR6iNdlUtm1EdHHdA3D19Qg=="
    },
    "payment": {
        "amount": 3000,
        "currency": "VND"
    },
    "account": {
        "bank_id": 571
    },
    "customer": {
        "email": "test@example.com",
        "ip_address": "192.0.2.0",
        "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": "f8c9771e349308ffb199d7916c434c90805",
            "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": "OCa7bOyjNbaxVUvtgSxNfvV1a6n3n0QRIvv25Fg=="
    }
}

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

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

 {
        "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": "3588d3f8fd252b3cabf1a2242eba6e6d148",
            "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": "jqTBt8VV8UhK63525hwW14kS3LWfSjCRdrKcaL6Gg=="
    }
}

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

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

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

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

Для анализа информации о платежах и операциях, как в отдельности по методу Vietnamese OTC, так и в совокупности с другими методами, можно использовать:

инструментарий интерфейса Dashboard, с различными реестрами и аналитическими панелями;,
отчёты в формате CSV, выгружаемые (как разово, так и периодически) через раздел Отчёты интерфейса Dashboard;,
данные в формате JSON, получаемые по программным запросам через интерфейс Data API.

С вопросами по анализу информации можно обращаться к разделам документации (Dashboard и Использование Data API) и специалистам ecommpay.