DOKU Wallet

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

Схема работы

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

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

* KYC — это процедура, которая позволяет финансовым организациям проверять клиентов, чтобы обезопасить себя от мошенников.

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

Проведение оплат с использованием метода DOKU Wallet выполняется с перенаправлением пользователей к форме DOKU Wallet, проведение выплат — с уведомлением пользователей со стороны веб-сервиса.

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

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

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

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

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

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

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

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

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

1. Должен использоваться базовый минимум параметров — параметры, обязательные для любого платёжного метода:
   • project_id — идентификатор проекта, полученный от ECommPay при интеграции;
   • payment_id — идентификатор платежа уникальный в рамках проекта;
   • payment_currency — валюта платежа в формате ISO-4217 alpha-3;
   • payment_amount — сумма платежа в минорных единицах;
   • customer_id — идентификатор пользователя уникальный в рамках проекта.
2. Дополнительно рекомендуется указывать имя и адрес электронной почты пользователя в параметрах customer_first_name и customer_email. Если параметры отсутствуют в запросе, на Payment Page пользователю отображаются поля для ввода недостающих значений. Подробнее об уточнении параметров — в разделе Дополнение информации о платеже.
3. Для предварительного выбора метода DOKU Wallet необходимо указывать код платёжного метода doku в параметре force_payment_method.
4. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page.
5. После определения всех параметров необходимо составить подпись. Подробнее — в разделе Работа с подписью к данным.

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

EPayWidget.run(
    { payment_id: 'ID_183', 
      payment_amount: 1000000, 
      payment_currency: 'IDR', 
      project_id: 238,  
      customer_id: 'customer1',
      customer_first_name: 'Hasan',
      customer_email: 'Prasetyo@mail.com',
      signature: "hlhydUV+SmGJYhm6G47NknsqVx2TdMZrnJ9V5Ly...=="
    }
)

Детальная информация обо всех указанных параметрах приведена в разделе Параметры открытия платежной формы Payment Page.

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

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

В следующем примере оповещение свидетельствует о том, что в рамках проекта 238 была успешно проведена оплата в размере 1 000,00 IDR с использованием кошелька DOKU Wallet 1189632633.

{
        "project_id": 238,
        "payment": {
            "id": "Doku_eWallet_001",
            "type": "purchase",
            "status": "success",
            "date": "2018-12-14T09:21:58+0000",
            "method": "Doku",
            "sum": {
                "amount": 100000,
                "currency": "IDR"
            },
            "description": ""
        },
        "account": {
            "number": "1189632633"
        },
        "operation": {
            "id": 6085000002263,
            "type": "sale",
            "status": "success",
            "date": "2018-12-14T09:21:58+0000",
            "created_date": "2018-12-14T09:20:39+0000",
            "request_id": "026b9dbadeb438abe796132c1db963c9650424fe-a729ea898
                                    99e9ae460d7a86c9667edc9b11eb994",
            "sum_initial": {
                "amount": 100000,
                "currency": "IDR"
            },
            "sum_converted": {
                "amount": 100000,
                "currency": "IDR"
            },
            "provider": {
                "id": 1162,
                "payment_id": "342205",
                "date": "2018-12-14T09:21:54+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "XFyr/D1zXj84lUZVfpbWZol9JAZLnUZoPJKPXRbOqBUpxxa/hOKm2
                            P8XOqydoyeIi7KdqrcxLFd3GxgPgUzIDg=="
    }

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

{
        "project_id": 238,
        "payment": {
            "id": "ECT_TEST_1544793284604",
            "type": "purchase",
            "status": "decline",
            "date": "2018-12-14T13:23:50+0000",
            "method": "Doku",
            "sum": {
                "amount": 2000000000,
                "currency": "IDR"
            },
            "description": ""
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 19078000002242,
            "type": "sale",
            "status": "decline",
            "date": "2018-12-14T13:23:50+0000",
            "created_date": "2018-12-14T13:20:47+0000",
            "request_id": "b12c7232b016305896e2c73d47956b562e131640-44
                                    4c4b88f5f7468d191c0a8ac67b74dd2bc05ac9",
            "sum_initial": {
                "amount": 2000000000,
                "currency": "IDR"
            },
            "sum_converted": {
                "amount": 2000000000,
                "currency": "IDR"
            },
            "provider": {
                "id": 1162,
                "payment_id": "",
                "auth_code": ""
            },
            "code": "20101",
            "message": "Decline due to amount or frequency limit"
        },
        "signature": "5+82BkJhEn/DG892c1vYILNYttNDkBQJAfC87oDMeySCJ8
                                KQ/CiU02oQvEZUsNbEVDN9uuQTagdL6SYe5iOzSA=="
    }

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

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

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

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

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

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

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

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

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

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

   Рекомендуется использовать следующие объекты и параметры:

   • customer — объект, содержащий сведения о пользователе:
     • first_name — имя пользователя,
     • email — адрес электронной почты;
4. Дополнительно могут использоваться любые другие параметры, указанные в спецификации.

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

{
    "general": {
    "project_id": 125,
    "payment_id": "ID_184",
    "signature": "PJkV8ej\/UG0Di8hTng6JvC7vQsaC6tajQVVLhNN5e7cV+VHq3L
                        wY3T\/pOMeSaRfBaNIipTv+AWoXW\/9MTO8yJA=="
  },
  "customer": {
    "ip_address": "1.1.1.1",
    "first_name": "Riza",
    "email": "riza@testpay.com",
    "id": "123"
    },
  "payment": {
    "amount": 100,
    "currency": "IDR"
  }
}

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

Для перенаправления пользователя от веб-сервиса к форме оплаты DOKU Wallet необходимо:

1. Принять от платёжной платформы оповещение с объектом redirect_data.
2. Сформировать POST-запрос из параметров, переданных в объекте body, в кодировке x-www-form-urlencoded.
3. Осуществить перенаправление на URL, указанный в параметре url.

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

"redirect_data": {
            "method": "POST",
            "body": {
                "MALLID": 4038,
                "CHAINMERCHANT": "NA",
                "AMOUNT": "10000.00",
                "PURCHASEAMOUNT": "10000.00",
                "TRANSIDMERCHANT": 1447000002341,
                "PAYMENTTYPE": "SALE",
                "WORDS": "2e2d93c40d5c82f87b555502492222abcdb8c50f",
                "REQUESTDATETIME": "20181218142352",
                "CURRENCY": "360",
                "PURCHASECURRENCY": "360",
                "SESSIONID": "7d28088c",
                "NAME": "Riza",
                "EMAIL": "riza@testpay.com",
                "BASKET": "Sale,10000.00,1,10000.00",
                "PAYMENTCHANNEL": "41"
            },
            "encrypted": [],
            "url": "https://pay.doku.com/Suite/Receive"
        }

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

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

В следующем примере оповещение свидетельствует о том, что в рамках проекта 238 была успешно проведена оплата в размере 1 000,00 IDR с использованием кошелька DOKU Wallet 1189632633.

{
        "project_id": 238,
        "payment": {
            "id": "Doku_eWallet_001",
            "type": "purchase",
            "status": "success",
            "date": "2018-12-14T09:21:58+0000",
            "method": "Doku",
            "sum": {
                "amount": 100000,
                "currency": "IDR"
            },
            "description": ""
        },
        "account": {
            "number": "1189632633"
        },
        "operation": {
            "id": 6085000002263,
            "type": "sale",
            "status": "success",
            "date": "2018-12-14T09:21:58+0000",
            "created_date": "2018-12-14T09:20:39+0000",
            "request_id": "026b9dbadeb438abe796132c1db963c9650424fe-a729ea898
                                    99e9ae460d7a86c9667edc9b11eb994",
            "sum_initial": {
                "amount": 100000,
                "currency": "IDR"
            },
            "sum_converted": {
                "amount": 100000,
                "currency": "IDR"
            },
            "provider": {
                "id": 1162,
                "payment_id": "342205",
                "date": "2018-12-14T09:21:54+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "XFyr/D1zXj84lUZVfpbWZol9JAZLnUZoPJKPXRbOqBUpxxa/hOKm2
                            P8XOqydoyeIi7KdqrcxLFd3GxgPgUzIDg=="
    }

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

{
        "project_id": 238,
        "payment": {
            "id": "ECT_TEST_1544793284604",
            "type": "purchase",
            "status": "decline",
            "date": "2018-12-14T13:23:50+0000",
            "method": "Doku",
            "sum": {
                "amount": 2000000000,
                "currency": "IDR"
            },
            "description": ""
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 19078000002242,
            "type": "sale",
            "status": "decline",
            "date": "2018-12-14T13:23:50+0000",
            "created_date": "2018-12-14T13:20:47+0000",
            "request_id": "b12c7232b016305896e2c73d47956b562e131640-44
                                    4c4b88f5f7468d191c0a8ac67b74dd2bc05ac9",
            "sum_initial": {
                "amount": 2000000000,
                "currency": "IDR"
            },
            "sum_converted": {
                "amount": 2000000000,
                "currency": "IDR"
            },
            "provider": {
                "id": 1162,
                "payment_id": "",
                "auth_code": ""
            },
            "code": "20101",
            "message": "Decline due to amount or frequency limit"
        },
        "signature": "5+82BkJhEn/DG892c1vYILNYttNDkBQJAfC87oDMeySCJ8
                                KQ/CiU02oQvEZUsNbEVDN9uuQTagdL6SYe5iOzSA=="
    }

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

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

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

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

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

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

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

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

1. Должен использоваться запрос /v2/payment/wallet/doku/payout, отправляемый методом POST. Этот запрос относится к группе запросов для проведения выплат с использованием электронных кошельков /v2/payment/wallet/{payment_method}/payout.
2. В запросе должны использоваться следующие объекты и параметры:
   • general — объект, содержащий основные идентификационные сведения запроса:
     • project_id — идентификатор проекта, полученный от ECommPay при интеграции;
     • payment_id — идентификатор платежа, уникальный в рамках проекта;
     • signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Использование подписи к данным);
   • customer — объект, содержащий сведения о пользователе:
     • id — идентификатор пользователя в веб-сервисе,
     • first_name — имя,
     • last_name — фамилия,
     • ip_address — IP-адрес,
     • phone — телефон,
     • city — город,
     • day_of_birth — дата рождения,
     • country — страна в формате ISO 3166-1 (alpha-2),
     • identify — объект, содержащий сведения о документе, удостоверяющего личность пользователя:
       • doc_number — номер документа,
       • doc_type — тип документа,
       • doc_issue_country — идентификатор страны, выдавшей документ, в формате ISO 3166-1 (alpha-2);
   • account — объект, содержащий сведения о кошельке пользователя:
     • number — номер кошелька;
   • payment — объект, содержащий сведения о платеже:
     • amount — сумма платежа в минорных единицах валюты,
     • currency — валюта платежа в формате ISO-4217 alpha-3,
     • description — описание платежа.
3. Дополнительно могут использоваться любые другие параметры, указанные в спецификации.

В следующем примере приведён корректный запрос на оплату методом DOKU Wallet:

{
    "general": {
    "project_id": 2853,
    "payment_id": "test-002",
    "signature": "M1vT4q9c8hA8xCjEwGFSANwbxHShy2TSOI/4sKFk
                        B+9XAaq7vt3/Jkn+aJmGA4jH6bgBOp8DTf8d/XdoV+vd7Q=="
  },
  "customer": {
    "id": "payoutTest",
    "first_name": "Suharto",
    "last_name": "Yudhoyono",
    "ip_address": "114.124.147.206",
    "phone": "02112345678",
    "city": "Jakarta",
    "day_of_birth": "21-09-1983",
    "country": "ID",
    "identify": {
      "doc_number": "2101086512740000",
      "doc_type": "none",
      "doc_issue_country": "ID"
    }
  },
  "account": {
    "number": "654654654"
  },
  "payment": {
    "amount": 10000,
    "currency": "IDR",
    "description": "PayoutTest.49855500 1538564115"
  }
}

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

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

В следующем примере оповещение свидетельствует о том, что в рамках проекта 580 пользователем 1 проведена выплата в размере 1,00 IDR на кошелёк DOKU Wallet 1579000479.

{
        "project_id": 580,
        "payment": {
            "id": "ApsViaDoku-040-wallet-1",
            "type": "payout",
            "status": "success",
            "date": "2019-05-07T11:38:24+0000",
            "method": "Doku",
            "sum": {
                "amount": 100,
                "currency": "IDR"
            },
            "description": "ApsViaDokuPayoutTest.49855500 1538564115"
        },
        "account": {
            "number": "1579000479"
        },
        "customer": {
            "id": "1",
            "phone": "798454444474"
        },
        "operation": {
            "id": 31771000001833,
            "type": "payout",
            "status": "success",
            "date": "2019-05-07T11:38:24+0000",
            "created_date": "2019-05-07T11:38:14+0000",
            "request_id": "a6ce8cf365af0c33a3d7744bb48b6aac20ecfed
                            8-ea53b2d5ff4ee3dead9dcb45e8780793377c9460",
            "sum_initial": {
                "amount": 100,
                "currency": "IDR"
            },
            "sum_converted": {
                "amount": 100,
                "currency": "IDR"
            },
            "provider": {
                "id": 1162,
                "payment_id": "DK06282314",
                "date": "2019-05-07T18:38:19+0000",
                "auth_code": "",
                "endpoint_id": "04"
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "8xwuyUSnpfu4YVMH1qF8Zk2ILnhu21/oE4d1Ue
                7ZlLVdKkMHkUKH51zo76fAVQAiovMrU3JUTyF8UjZ8qTouKQ=="
    }

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

{
        "project_id": 439,
        "payment": {
            "id": "ApsViaDoku-129",
            "type": "payout",
            "status": "decline",
            "date": "2019-03-29T09:18:18+0000",
            "method": "Doku",
            "sum": {
                "amount": 1100000000,
                "currency": "IDR"
            },
            "description": "123"
        },
        "account": {
            "number": "1322808400"
        },
        "customer": {
            "id": "payoutTest",
            "phone": "79998785643"
        },
        "operation": {
            "id": 3293088074203,
            "type": "payout",
            "status": "decline",
            "date": "2019-03-29T09:18:18+0000",
            "created_date": "2019-03-29T09:18:14+0000",
            "request_id": "d2b43977e0c6d54ecec408173a01207b3779e6bc-80
                              22cae5778fb1935e2c307cfb892f6cf28c07c4",
            "sum_initial": {
                "amount": 1100000000,
                "currency": "IDR"
            },
            "sum_converted": {
                "amount": 1100000000,
                "currency": "IDR"
            },
            "provider": {
                "id": 1274,
                "payment_id": "",
                "auth_code": ""
            },
            "code": "20101",
            "message": "Decline due to amount or frequency limit"
        },
        "signature": "D5SRvrsJaOQMKitsQNJ3hlawe6AJl35T9jfPQG+vrMzAIhYo
                            enSHJiR63hFKyR0UqwTrepQJtfa6uEDwkshnQA=="
    }

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

При тестировании оплат через Gate после того, как щёлкнута кнопка Success или Decline, по умолчанию происходит перенаправление на страницу Payment Page с информацией о результате платежа. Чтобы перенаправление происходило на другую страницу (например, на страницу мерчанта), следует обратиться к специалистам технической поддержки ECommPay support@ecommpay.com.

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

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

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

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

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

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

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

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