MoMo Wallet

Введение

MoMo Wallet — метод, позволяющий проводить платежи донгах с использованием электронных кошельков во Вьетнаме. MoMo это электронный кошелёк во Вьетнаме с долей рынка 70% и около пятью миллионами активных пользователей. Учётная запись MoMo Wallet создаётся с привязкой к номеру мобильного телефона пользователя. Пополнение счёта MoMo Wallet возможно с использованием банковского перевода или платёжной карты, а также наличными в магазинах MoMo на территории Вьетнама. Для этого метода в платёжной платформе ecommpay поддерживаются оплаты.

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

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

Схема работы

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

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

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

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

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

Проведение оплат с использованием метода MoMo Wallet выполняется с перенаправлением пользователей к сервису провайдера.

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

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

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

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

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

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

1. Должен использоваться базовый минимум параметров, обязательный для любого платежа:
   • project_id — идентификатор проекта, полученный от ecommpay при интеграции;
   • payment_id — идентификатор платежа, уникальный в рамках проекта;
   • payment_currency — код валюты платежа в формате ISO-4217 alpha-3;
   • payment_amount — сумма платежа (без выделения дробной части, поскольку при работе с валютой VND дробные единицы не используются);
   • customer_id — идентификатор пользователя в рамках проекта.
2. Должен использоваться базовый минимум параметров: project_id, payment_id, payment_currency, payment_amount, customer_id.
3. Также необходимо указывать имя, фамилию и адрес электронной почты пользователя в параметрах customer_first_name, customer_last_name и customer_email.
4. Для предварительного выбора метода MoMo Wallet необходимо указывать код платёжного метода в параметре force_payment_method — momopay.
5. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page. Детальная информация обо всех параметрах приведена в разделе Параметры вызова платёжной формы.
6. После определения всех параметров необходимо составить подпись (подробнее).

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

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "VND",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "customer_email": "johndoe@example.com",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "VND",
   "customer_id": "customer1",
   "customer_first_name": "John",
   "customer_last_name": "Doe",
   "customer_email": "johndoe@example.com",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

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

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

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

{
        "project_id": 1926,
        "payment": {
            "id": "1053",
            "type": "purchase",
            "status": "success",
            "date": "2021-03-12T08:34:25+0000",
            "method": "momopay",
            "sum": {
                "amount": 110000,
                "currency": "VND"
            },
            "description": ""
        },
        "operation": {
            "id": 18,
            "type": "sale",
            "status": "success",
            "date": "2021-03-12T08:34:25+0000",
            "created_date": "2021-03-12T08:34:12+0000",
            "request_id": "48be0494d37ab7106325f4eb16597a0d0-00000001",
            "sum_initial": {
                "amount": 110000,
                "currency": "VND"
            },
            "sum_converted": {
                "amount": 110000,
                "currency": "VND"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 2892,
                "payment_id": "1615538057957",
                "auth_code": ""
            }
        },
        "signature": "KMCoAR2yCd70I8VoAVT3NSF98zwoMfcDx2zwLixVsMW/Cvonik4A=="
    }

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

{
        "project_id": 1926,
        "payment": {
            "id": "XPAY_1054",
            "type": "purchase",
            "status": "decline",
            "date": "2021-03-12T08:38:57+0000",
            "method": "momopay",
            "sum": {
                "amount": 110000,
                "currency": "VND"
            },
            "description": ""
        },
        "operation": {
            "id": 19,
            "type": "sale",
            "status": "decline",
            "date": "2021-03-12T08:38:57+0000",
            "created_date": "2021-03-12T08:38:48+0000",
            "request_id": "8df6a94820540aa079d3c4643f2fa329a9ec78a-00000001",
            "sum_initial": {
                "amount": 110000,
                "currency": "VND"
            },
            "sum_converted": {
                "amount": 110000,
                "currency": "VND"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 2892,
                "payment_id": "1615538332499",
                "auth_code": ""
            }
        },
        "signature": "u1YtNglF6H64ZWDiW+8D6K56/WmDUT6AySz0PF0wQvBMhuTsWrODsc32g=="
    }

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

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

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

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

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

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

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

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

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

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

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

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

{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "amount": 1000,
    "currency": "VND"
  },
  "customer": {
    "id": "customer123",
    "ip_address": "192.0.2.0",
    "first_name": "John",
    "last_name": "Doe",
    "email": "johndoe@example.com"
  },
  "return_url": {
    "success": "https://example.com/success",
    "decline": "https://example.com/decline",
    "return": "https://example.com/return"
  }
}

{
  "general": {
    "project_id": 210,
    "payment_id": "test_payment",
    "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA=="
  },
  "payment": {
    "amount": 1000,
    "currency": "VND"
  },
  "customer": {
    "id": "customer123",
    "ip_address": "192.0.2.0",
    "first_name": "John",
    "last_name": "Doe",
    "email": "johndoe@example.com"
  },
  "return_url": {
    "success": "https://example.com/success",
    "decline": "https://example.com/decline",
    "return": "https://example.com/return"
  }
}

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

Для перенаправления пользователей от веб-сервиса мерчанта к сервису MoMo Wallet при проведении каждого платежа с использованием метода MoMo Wallet необходимо принять промежуточное оповещение от платёжной платформы и использовать информацию из него, включённую в объект redirect_data. Формат таких оповещений является типовым (подробнее), при этом в состав объекта redirect_data включаются следующие объекты и параметры:

• body — объект с данными для отправки в теле запроса;
• method — параметр с указанием HTTP-метода отправки запроса (GET или POST);
• url — параметр со ссылкой для перенаправления.

"redirect_data": {
        "body": {
            "Data": "4dg65h72G63k68g61J6eK74I49h44i3dj41H43g50h30G30k30g33J26K43I75h73i74j49H44g3dh6dG65k72g63J68K61I6eh74i5fj31H30g26h43G75k73g74J49K50I3dh26i43j75H72g72
h3dG54k48g42J26K41I6dh6fi75j6eH74g3dh34G36k35g2eJ35K32I26h52i65j66H49g44h3dG34k30g30J30K30I30h30i30j31H30g26h54G72k61g6eJ73K54I69h6di65j3dH32g30h32G30k2dg30J34K2dI31h35i
20j31H33g3ah32G36k3ag34J33K26I52h65i74j75H72g6eh55G52k4cg3dJ68K74I74h70i3aj2fH2fg70h70G2ek74g65J72K6dI69h6ei61j6cH2eg74h65G73k74g2fJ70K72I6fh63i65j73H73g2fh63G6fk6dg70J6
cK65I74h65i2dj72H65g64h69G72k65g63J74K2fI30h66i35j62H64g36h61G30k63g75J68K73I31h37i69j34H32g6dh34G76k37g72J37K39I66h36i2fj31H30g35h65G39k63g36J61K66I38h39i66j63H33g62h64
G26k52g65J71K75I65h73i74j55H52g4ch3dG68k74g74J70K73I3ah2fi2fj65H36g61h30G31k65g63J39K2eI6eh67i72j6fH6bg2eh69G6fk2fg63J61K6cI6ch62i61j63H6bg2fh78G70k61g79J2fK26I42h61i6ej
6bH43g6fh64G65k3dg54J4dK42I2eh46i54j",
            "Remarks": "",
            "EncryptText": "8F4AC9ED17D1579A7DE5121B16A45B4F"
        },
        "method": "POST",
        "url": "http://test.com/a/payment"
    }

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

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

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

{
        "project_id": 1926,
        "payment": {
            "id": "1053",
            "type": "purchase",
            "status": "success",
            "date": "2021-03-12T08:34:25+0000",
            "method": "momopay",
            "sum": {
                "amount": 110000,
                "currency": "VND"
            },
            "description": ""
        },
        "operation": {
            "id": 18,
            "type": "sale",
            "status": "success",
            "date": "2021-03-12T08:34:25+0000",
            "created_date": "2021-03-12T08:34:12+0000",
            "request_id": "48be0494d37ab7106325f4eb16597a0d0-00000001",
            "sum_initial": {
                "amount": 110000,
                "currency": "VND"
            },
            "sum_converted": {
                "amount": 110000,
                "currency": "VND"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 2892,
                "payment_id": "1615538057957",
                "auth_code": ""
            }
        },
        "signature": "KMCoAR2yCd70I8VoAVT3NSF98zwoMfcDx2zwLixVsMW/Cvonik4A=="
    }

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

{
        "project_id": 1926,
        "payment": {
            "id": "XPAY_1054",
            "type": "purchase",
            "status": "decline",
            "date": "2021-03-12T08:38:57+0000",
            "method": "momopay",
            "sum": {
                "amount": 110000,
                "currency": "VND"
            },
            "description": ""
        },
        "operation": {
            "id": 19,
            "type": "sale",
            "status": "decline",
            "date": "2021-03-12T08:38:57+0000",
            "created_date": "2021-03-12T08:38:48+0000",
            "request_id": "8df6a94820540aa079d3c4643f2fa329a9ec78a-00000001",
            "sum_initial": {
                "amount": 110000,
                "currency": "VND"
            },
            "sum_converted": {
                "amount": 110000,
                "currency": "VND"
            },
            "code": "20000",
            "message": "General decline",
            "provider": {
                "id": 2892,
                "payment_id": "1615538332499",
                "auth_code": ""
            }
        },
        "signature": "u1YtNglF6H64ZWDiW+8D6K56/WmDUT6AySz0PF0wQvBMhuTsWrODsc32g=="
    }

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

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

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

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

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

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

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

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