# TrueMoney {#pm_truemoney} **На уровень выше:**[Платежи с помощью QR-кодов](ru_pm_qr.md) ## Обзор {#ru_pm_truemoney_overview} статья о работе с платёжным методом TrueMoney, который позволяет проводить платежи в батах с использованием банковских счетов в Таиланде и для которого в платформе Ecommpay поддерживаются оплаты ### Введение {#section_ql3_5fj_stb .section} TrueMoney — метод, позволяющий проводить платежи батах с использованием банковских счетов в Тайланде. Для этого метода в платёжной платформе Ecommpay поддерживаются оплаты. В этой статье представлена информация о работе с методом TrueMoney: обзорный раздел с общими сведениями и последующие разделы с информацией о действиях, необходимых со стороны мерчанта для решения разных задач. ### Характеристика {#section_tbf_2zk_ggb .section} |Тип платёжного метода|платежи с помощью QR-кодов| |Платёжные инструменты|банковские счета| |Регионы использования|[TH](references/ru/countries/TH.md)| |Валюты платежей|[THB](references/ru/currencies/THB.md)| |Конвертация валют|–| |Разовые оплаты|+| |Повторяемые оплаты|–| |Полные возвраты|–| |Частичные возвраты|–| |Выплаты|\*| |Опротестования|–| |Особенности|–| |Организация и стоимость подключения|по согласованию с курирующим менеджером Ecommpay| ### Схема работы {#section_tsp_gzk_ggb .section} В проведении отдельного платежа с использованием метода TrueMoney задействуются веб-сервис мерчанта, один из интерфейсов и платёжная платформа Ecommpay, а также технические средства сервиса провайдера. ![](images/pm/ru_truemoney_functional.svg) ### Основные операции {#section_rnx_4cl_ggb .section} Для проведения платежей и выполнения операций с использованием метода TrueMoney могут применяться различные интерфейсы платёжной платформы. Так, оплаты могут проводиться через Payment Page, Gate и Dashboard \(с применением платёжных ссылок\). При этом, независимо от используемых интерфейсов, для этого метода характерны следующие свойства и ограничения. ||Суммы, THB¹| |Минимум|Максимум| |--|:----------| |-------|:-------| |Оплаты|100,00|500 000,00| **Прим.:** 1. Более подробную информацию можно уточнять у курирующего менеджера Ecommpay ### Сценарии использования {#section_fgt_sdl_ggb .section} При использовании метода TrueMoney поддерживается проведение оплат с перенаправлением пользователя к сервису провайдера. Пользовательский сценарий оплаты через Payment Page \(в базовом варианте с выбором пользователем метода и перенаправлением с итоговой страницы платёжной формы к веб-сервису\) выглядит следующим образом. ![](images/pm/pp_scenario/ru_pp_customer_scenario_truemoney_1.svg "Переход к оплате") ![](images/pm/pp_scenario/ru_pp_customer_scenario_truemoney_2.svg "Выбор метода") ![](images/pm/pp_scenario/ru_pp_customer_scenario_truemoney_3.svg "Получение инструкции") ![](images/pm/pp_scenario/ru_pp_customer_scenario_truemoney_4.svg "Платёж по инструкции") ![](images/pm/pp_scenario/ru_pp_customer_scenario_truemoney_5.svg "Возвращение к форме") ![](images/pm/pp_scenario/ru_pp_customer_scenario_truemoney_6.svg "Возвращение к веб-сервису") Общие сценарии проведения оплат можно представить следующим образом. ![](images/pm/ru_truemoney_interfaces_pp.svg "Оплата через Payment Page") ![](images/pm/ru_truemoney_interfaces_gate.svg "Оплата через Gate") ## Оплаты через Payment Page {#ru_pm_truemoney_pp_purchase} ### Общая информация {#section_gtg_vxk_m2b .section} Для проведения оплаты через Payment Pageс использованием метода TrueMoney со стороны веб-сервиса необходимо отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay и принять оповещение о результате.Полная схема проведения оплаты выглядит следующим образом. ![](images/pm/ru_truemoney_uml_pp.svg) 1. Пользователь на стороне веб-сервиса инициирует оплату. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на проведение оплаты через Payment Page. 3. Запрос на проведение оплаты поступает в платёжную платформу. 4. В платёжной платформе выполняется приём запроса, с проверкой наличия обязательных параметров и корректной подписи. 5. Осуществляется подготовка Payment Page согласно параметрам проекта и вызова. 6. Пользователю отображается платёжная форма. 7. Пользователь выбирает для оплаты метод TrueMoney. 8. В платёжную платформу передаётся запрос на проведение оплаты с использованием метода TrueMoney. 9. В платёжной платформе выполняются обработка полученного запроса и его отправка в сервис провайдера. 10. В сервисе провайдера выполняется обработка запроса на оплату. 11. От сервиса провайдера к платёжной платформе передаются данные для перенаправления пользователя к сервису провайдера. 12. Данные для перенаправления пользователя передаются к Payment Page. 13. Пользователь перенаправляется к сервису провайдера. 14. Пользователь выполняет необходимые действия для оплаты. 15. В сервисе провайдера выполняется обработка платежа. 16. Информация о результате оплаты отображается пользователю в сервисе провайдера. 17. Пользователь перенаправляется к Payment Page. 18. От сервиса провайдера к платёжной платформе направляется информация о результате оплаты. 19. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты. 20. От платёжной платформы к Payment Page направляется информация о результате оплаты. 21. Информация о результате оплаты отображается пользователю на Payment Page. Информация о форматах запросов и оповещений, используемых для проведения оплат методом TrueMoney через Payment Page, приведена далее в этом разделе; общая информация о работе с Payment Page API — в отдельной статье [Организация взаимодействия](ru_pp_interaction_organisation.md#). ### Формат запросов {#section_p5j_fgl_ggb .section} При формировании запросов на открытие платёжной формы с применением метода TrueMoney необходимо учитывать следующее: 1. Должен использоваться базовый минимум параметров, обязательный для любого платежа: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `payment_currency` — код валюты платежа в формате ISO-4217 alpha-3; - `payment_amount` — сумма платежа в дробных единицах валюты; - `customer_id` — идентификатор пользователя в рамках проекта. 2. Валютой платежа может быть только [THB](references/ru/currencies/THB.md). 3. Для предварительного выбора метода TrueMoney необходимо указывать код платёжного метода в параметре force\_payment\_method — `true-money`. 4. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page. Детальная информация обо всех параметрах приведена в разделе [Спецификация Payment Page API](ru_PP_Parameters.md). 5. После определения всех параметров необходимо составить подпись \([подробнее](ru_platform_signature.md#)\). Таким образом, корректный запрос на открытие платёжной формы с применением метода TrueMoney должен содержать идентификатор проекта, базовые сведения о платеже \(идентификатор, сумму и код валюты\), идентификатор пользователя и подпись. ```language-json { "project_id": 120, "payment_id": "580", "payment_amount": 10000, "payment_currency": "THB", "customer_id": "customer1", "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" } ``` ```language-json { "project_id": 120, "payment_id": "580", "payment_amount": 10000, "payment_currency": "THB", "customer_id": "customer1", "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg==" } ``` ### Формат оповещений {#section_dpx_2hl_ggb .section} Для оповещений о результатах оплат с применением метода TrueMoney используется типовой формат, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md#). В следующем примере оповещение свидетельствует о том, что в рамках проекта `12345` была проведена оплата в размере `100,00 THB`. ```language-json { "customer": { "id": "customer1" }, "project_id": 12345, "payment": { "id": "payment1234", "type": "purchase", "status": "success", "date": "2021-10-12T08:16:05+0000", "method": "true-money", "sum": { "amount": 10000, "currency": "THB" }, "description": "" }, "operation": { "id": 5054705010079872, "type": "sale", "status": "success", "date": "2021-10-12T08:16:05+0000", "created_date": "2021-10-12T08:14:01+0000", "request_id": "a41fcbe99835e5fbc69770344bce...cc2f804083379379c2da5-05054706", "sum_initial": { "amount": 10000, "currency": "THB" }, "sum_converted": { "amount": 10000, "currency": "THB" }, "code": "0", "message": "Success", "provider": { "id": 6641, "payment_id": "2021101203031281", "auth_code": "" } }, "signature": "EIrbFLdIqieeX/Oi2Xl/3xADlmidzSRqKsFz7VX5s...wKVXTkpC2CNA==" } ``` В следующем примере оповещение свидетельствует об отклонённой оплате. ```language-json { "customer": { "id": "1" }, "project_id": 67890, "payment": { "id": "payment5678", "type": "purchase", "status": "decline", "date": "2021-10-13T08:10:17+0000", "method": "true-money", "sum": { "amount": 10000, "currency": "THB" }, "description": "TEST_PAYMENT_812515" }, "operation": { "id": 5000375010078322, "type": "sale", "status": "decline", "date": "2021-10-13T08:10:17+0000", "created_date": "2021-10-12T08:10:11+0000", "request_id": "6d2129131a347e8107b6bc2e3249f13...a483c36017-05000376", "sum_initial": { "amount": 10000, "currency": "THB" }, "sum_converted": { "amount": 10000, "currency": "THB" }, "code": "20000", "message": "General decline", "provider": { "id": 6641, "payment_id": "", "auth_code": "" } }, "signature": "bRj3VHm1qT1/RRrWrqW9LwxM5C9bTpoTx7Ip...emz2GxIdEyAeC4oA8w==" } ``` ### Дополнительные материалы {#section_xpz_thl_ggb .section} Для организации работы с оплатами через Payment Page также могут быть полезны следующие материалы: - [Организация взаимодействия](ru_pp_interaction_organisation.md#)— о том, как организовать взаимодействие веб-сервиса с платёжной платформой через Payment Page. - [Работа с подписью к данным](ru_platform_signature.md#)— о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой. - [Проведение платежей](ru_platform_payment_model.md)— о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций. - [Проведение оплат](ru_pp_purchase.md)— о том, как проводить разовые оплаты через Payment Page. - [Работа с информацией об операциях](ru_platform_payment_info_codes.md)— о служебных кодах, которые используются в платёжной платформе, чтобы фиксировать информацию о выполнении операций. ## Оплаты через Gate {#ru_pm_truemoney_gate_purchase} ### Общая информация {#section_lsx_3jl_ggb .section} Для проведения оплаты через Gate с использованием метода TrueMoney со стороны веб-сервиса необходимо: 1. Отправить запрос, содержащий требуемые параметры и подпись, на рабочий URL Ecommpay. 2. Принять промежуточное оповещение от платёжной платформы и осуществить перенаправление пользователя к сервису TrueMoney. 3. Принять итоговое оповещение от платёжной платформы. Полная схема проведения оплаты выглядит следующим образом. ![](images/pm/ru_truemoney_uml_gate.svg) 1. Пользователь на стороне веб-сервиса инициирует оплату с использованием метода TrueMoney. 2. От веб-сервиса на заданный URL Ecommpay передаётся запрос на проведение оплаты через Gate. 3. Запрос на проведение оплаты поступает в платёжную платформу Ecommpay. 4. В платёжной платформе выполняется приём запроса с проверкой наличия обязательных параметров и корректной подписи. 5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности \([подробнее](ru_gate_interaction_organisation.md#)\). 6. В платёжной платформе выполняются дальнейшая обработка запроса \(с проверкой согласованности параметров\) и его отправка в сервис провайдера. 7. В сервисе провайдера выполняется обработка запроса на оплату. 8. От сервиса провайдера к платёжной платформе передаются данные для перенаправления пользователя к сервису провайдера. 9. От платёжной платформы к веб-сервису направляется оповещение с данными для перенаправления пользователя к сервису провайдера. 10. Пользователь перенаправляется к сервису провайдера. 11. Пользователь выполняет необходимые действия для оплаты. 12. В сервисе провайдера выполняется обработка платежа. 13. Пользователю отображается информация о результате оплаты. 14. Пользователь перенаправляется к веб-сервису. 15. От сервиса провайдера к платёжной платформе направляется информация о результате оплаты. 16. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты. 17. На стороне веб-сервиса обеспечивается информирование пользователя о результате оплаты. Информация о форматах запросов и оповещений, используемых для проведения оплат методом TrueMoney через Gate, приведена далее в этом разделе; общая информация о работе с Gate API — в отдельной статье [Организация взаимодействия](ru_gate_interaction_organisation.md#). ### Формат запросов {#section_osx_3jl_ggb .section} При работе с запросами на оплаты с применением метода TrueMoney необходимо учитывать следующее: 1. Для инициирования каждой оплаты должен использоваться отдельный POST-запрос к конечной точке `/v2/payment/wallet/true-money/sale`. Эта точка относится к группе [/v2/payment/wallet/\{payment\_method\}/sale](https://api-developers.ecommpay.com/api-specification/wallet/post-v2-payment-wallet-payment-method-sale). 2. В каждом запросе должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта; - `signature` — подпись запроса, составленная после указания всех целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md#)\); - `payment` — объект, содержащий сведения о платеже: - `amount` — сумма платежа в дробных единицах валюты; - `currency` — код валюты платежав формате ISO-4217 alpha-3; - `customer` — объект, содержащий сведения о пользователе: - `id` — идентификатор пользователя, уникальный в рамках проекта; - `ip_address` — IP-адрес пользователя, актуальный для инициируемого платежа; - `return_url` — объект, содержащий URL для перенаправления пользователя после оплаты: - `success` — URL для перенаправления пользователя после проведённой оплаты; - `decline` — URL для перенаправления пользователя после отклонённой оплаты. 3. Валютой платежа может быть только [THB](references/ru/currencies/THB.md). 4. Дополнительно могут использоваться любые другие параметры из числа указанных в спецификации. Таким образом, корректный запрос на оплату с применением метода TrueMoney должен содержать идентификатор проекта, базовые сведения о платеже \(идентификатор, сумму и код валюты\), идентификатор и IP-адрес пользователя, URL для перенаправления, а также подпись. ```language-json { "general": { "project_id": 210, "payment_id": "test_payment", "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA==" }, "payment": { "amount": 10000, "currency": "THB" }, "customer": { "id": "customer123", "ip_address": "192.0.2.0" }, "return_url":{ "success" : "http://example.com", "decline" : "http://anotherexample.com" } } ``` ```language-json { "general": { "project_id": 210, "payment_id": "test_payment", "signature": "PJkV8ej\/UG0Di8hTng6JvipTv+AWoXW\/9MTO8yJA==" }, "payment": { "amount": 10000, "currency": "THB" }, "customer": { "id": "customer123", "ip_address": "192.0.2.0" }, "return_url":{ "success" : "http://example.com", "decline" : "http://anotherexample.com" } } ``` ### Формат промежуточных оповещений для перенаправления пользователей {#section_x23_cpg_vgb .section} Для перенаправления пользователей от веб-сервиса мерчанта к сервису TrueMoney при проведении каждого платежа с использованием метода TrueMoney необходимо принять промежуточное оповещение от платёжной платформы и использовать информацию из него, включённую в объект `redirect_data`. Формат таких оповещений является типовым \([подробнее](ru_platform_callbacks.md#)\), при этом в состав объекта `redirect_data` включаются следующие объекты и параметры: - `body` — объект с данными для отправки в теле запроса; - `method` — параметр с указанием HTTP-метода отправки запроса\(`GET` или `POST`\); - `url` — параметр со ссылкой для перенаправления. ```language-json "redirect_data": { "body": { "Data": "4dg65h72G63k68g61J6eK74I49h44i3dj41H454J4dK42I2eh46i54j", "Remarks": "", "EncryptText": "8F4AC9ED17D1579A7DE5121B16A45B4F" }, "method": "POST", "url": "https://www.example.com/pay" } ``` ### Формат оповещений {#section_wsx_3jl_ggb .section} Для оповещений о результатах оплат с применением метода TrueMoney используется типовой формат, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md#). В следующем примере оповещение свидетельствует о том, что в рамках проекта `12345` была проведена оплата в размере `100,00 THB`. ```language-json { "customer": { "id": "customer1" }, "project_id": 12345, "payment": { "id": "payment1234", "type": "purchase", "status": "success", "date": "2021-10-12T08:16:05+0000", "method": "true-money", "sum": { "amount": 10000, "currency": "THB" }, "description": "" }, "operation": { "id": 5054705010079872, "type": "sale", "status": "success", "date": "2021-10-12T08:16:05+0000", "created_date": "2021-10-12T08:14:01+0000", "request_id": "a41fcbe99835e5fbc69770344bce...cc2f804083379379c2da5-05054706", "sum_initial": { "amount": 10000, "currency": "THB" }, "sum_converted": { "amount": 10000, "currency": "THB" }, "code": "0", "message": "Success", "provider": { "id": 6641, "payment_id": "2021101203031281", "auth_code": "" } }, "signature": "EIrbFLdIqieeX/Oi2Xl/3xADlmidzSRqKsFz7VX5s...wKVXTkpC2CNA==" } ``` В следующем примере оповещение свидетельствует об отклонённой оплате. ```language-json { "customer": { "id": "1" }, "project_id": 67890, "payment": { "id": "payment5678", "type": "purchase", "status": "decline", "date": "2021-10-13T08:10:17+0000", "method": "true-money", "sum": { "amount": 10000, "currency": "THB" }, "description": "" }, "operation": { "id": 5000375010078322, "type": "sale", "status": "decline", "date": "2021-10-13T08:10:17+0000", "created_date": "2021-10-12T08:10:11+0000", "request_id": "6d2129131a347e8107b6bc2e3249f13...a483c36017-05000376", "sum_initial": { "amount": 10000, "currency": "THB" }, "sum_converted": { "amount": 10000, "currency": "THB" }, "code": "20000", "message": "General decline", "provider": { "id": 6641, "payment_id": "", "auth_code": "" } }, "signature": "bRj3VHm1qT1/RRrWrqW9LwxM5C9bTpoTx7Ip...emz2GxIdEyAeC4oA8w==" } ``` ### Дополнительные материалы {#section_xsx_3jl_ggb .section} Для организации работы с оплатами через Gate также могут быть полезны следующие материалы: - [Организация взаимодействия](ru_gate_interaction_organisation.md#)— о том, как взаимодействовать с платёжной платформой через Gate. - [Работа с подписью к данным](ru_platform_signature.md#)— о порядке создания и проверки подписи в программных запросах и оповещениях при взаимодействии с платёжной платформой. - [Проведение платежей](ru_platform_payment_model.md)— о типах, схемах проведения и возможных статусах поддерживаемых платежей и операций. - [Разовая оплата в одну стадию](ru_platform_sms_model.md)— о том, как проводить разовые оплаты через Gate. - [Работа с информацией об операциях](ru_platform_payment_info_codes.md)— о служебных кодах, используемых в платёжной платформе для фиксации информации о выполнении операций. ## Анализ результатов проведения платежей {#ru_pm_truemoney_dash_analysis} Как и при работе с другими платёжными методами, которые предоставляет Ecommpay, при использовании метода TrueMoney доступны разные способы анализа информации о платежах и операциях с применением этого метода — как в отдельности, так и в совокупности с другими методами. Всю необходимую информацию можно получать и анализировать средствами Dashboard , в том числе с помощью аналитических панелей в разделе **Аналитика**. Также можно выгружать необходимую информацию для последующего анализа с помощью специализированных аналитических средств сторонних разработчиков: - Dashboard позволяет выгружать данные в формате CSV с помощью инструментов в разделе **Отчёты**. При этом можно выполнять разовые и периодические выгрузки информации на локальный компьютер. - [Data API](ru_dbl_api_protocol.md) позволяет получать информацию в формате JSON и отправлять ее на заданный URL — для этого применяются запросы к конечной точке [/operations/get](https://api-data.ecommpay.com/operations/post-operations-get). С любыми вопросами о возможностях анализа результатов можно обращаться в службу технической поддержки Ecommpay.