Indonesian Virtual Accounts

Обзор

Indonesian Virtual Accounts — это самый популярный индонезийский альтернативный платёжный метод. При использовании этого метода пользователь переводит средства на виртуальный банковский счёт с помощью банкомата, мобильного приложения или сайта банка. Виртуальный счёт, номер которого состоит из 16 цифр, создаётся для каждого пользователя при оплате и используется для дифференциации платежей. ecommpay создаёт виртуальные счёта в межбанковской сети, каждый из которых уникален и используется только для одного платежа. Средства, полученные при помощи платежей, проведённых с использованием разных виртуальных счетов, объединяются на одном счёте мерчанта.

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

  • банкомат,
  • мобильное приложение банка,
  • сайт банка.

Большая часть (80 %) платежей в Индонезии проводятся с использованием виртуальных счетов. ecommpay предоставляет проведение платежей с использованием виртуальных счетов при участии крупных банков, работающих в Индонезии — Mandiri, Permata, Danamon, CIMB.

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

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

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

Схема работы

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



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

Интерфейсы Суммы, IDR Время **
Payment Page CMS Plug-ins Gate Dashboard Минимум Максимум базовое предельное
Оплаты + + * * 48 часов

* Информацию об ограничениях сумм необходимо уточнять у курирующего менеджера ecommpay.

** Базовое и предельное время определяются следующим образом:

  • Базовое время — среднее расчётное время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Это время, определяемое для условий штатной работы всех технических средств и каналов связи, а также типичных действий со стороны пользователя (там, где они необходимы). Базовое время рекомендуется использовать для реагирования на отсутствие оповещений о результате платежа и выполнения опроса состояния платежа.
  • Предельное время — максимально допустимое время проведения платежа от момента его инициирования на стороне платёжной платформы до момента отправки инициатору оповещения о результате. Если платёж не был проведён или отклонён за это время, он автоматически переводится в статус decline. Для индивидуальной настройки предельного времени следует обращаться к специалистам технической поддержки ecommpay.

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

Проведение оплат с использованием метода Indonesian Virtual Accounts выполняется с перенаправлением пользователей на сайт провайдера.

Поддержка со стороны банков

Проведение оплат с применением метода Indonesian Virtual Accounts осуществляется через банки, поддерживающие работу с этим методом. Банкам соответствуют свои идентификаторы, которые используются при инициировании платежей через Gate, а также при вызове Payment Page для отображения страницы с выбором метода оплаты.

Далее в таблицах в ознакомительных целях представлена информация об этих банках, которую следует уточнять у курирующего менеджера ecommpay или по запросам /v2/info/banks/{payment_method}/{operationType}/list, отправляемым методом POST через Gate API: /v2/info/banks/indonesia-va/sale/list для уточнения списка банков.

Запрос должен содержать идентификаторы проекта и платежа, подпись, валюту и сумму платежа, как указано в примере. Важно передавать реальные данные о платеже, но в случае если платёж еще не сформирован, для идентификатора платежа в запросе можно указать случайное значение.

Рис.: Пример запроса списка банков

{
  "general": {
    "project_id": 200,
    "payment_id": "ORDER_155860015",
    "signature": "K6jllym+PtObocZtr345st...=="
  },
  "payment": {
    "amount": 1000000,
    "currency": "IDR"
  }
}
Табл. 1. Список банков
Банк ID
Bank Sahabat Sampoerna VA 4391
Permata Virtual Account 433
Mandiri Virtual Account 434
Maybank Virtual Account 2831
BNI Virtual Account 2931
BRI Virtual Account 499
Sinarmas Virtual Account 562

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

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

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

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

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



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

  1. Пользователь на стороне веб-сервиса инициирует оплату.
  2. От веб-сервиса на заданный URL ecommpay передаётся запрос на проведение оплаты через Payment Page.
  3. Запрос на проведение оплаты поступает в платёжную платформу.
  4. Выполняется начальная обработка запроса, в рамках которой обеспечивается проверка наличия обязательных параметров и корректной подписи.
  5. Осуществляется формирование Payment Page согласно настройкам проекта и параметрам вызова.
  6. Пользователю отображается сформированная платёжная форма.
  7. Пользователь выбирает один из банков, поддерживающих работу с платёжным методом Indonesian Virtual Accounts.
  8. Запрос на проведение оплаты поступает в платёжную платформу.
  9. Выполняются дальнейшая обработка запроса и его отправка в сервис провайдера.
  10. На стороне провайдера выполняется обработка запроса на оплату.
  11. От сервиса провайдера к платёжной платформе передаются данные для перенаправления пользователя на сайт провайдера.
  12. Данные для перенаправления пользователя на сайт провайдера передаются к Payment Page.
  13. Пользователь перенаправляется на сайт провайдера, где ему отображается 16-значный код для оплаты и платёжная инструкция.
  14. Согласно инструкции, пользователь вводит код на сайте банка либо с использованием банкомата или мобильного приложения банка, и подтверждает оплату.
  15. На стороне провайдера выполняется обработка платежа.
  16. От сервиса провайдера к платёжной платформе направляется уведомление о результате оплаты.
  17. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
  18. От платёжной платформы к Payment Page направляется результат проведения оплаты.
  19. Информация о результате оплаты отображается пользователю на Payment Page.

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

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

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

  1. Должен использоваться базовый минимум параметров — параметры, обязательные для любого платёжного метода:
    • project_id — идентификатор проекта, полученный от ecommpay при интеграции;
    • payment_id — идентификатор платежа, уникальный в рамках проекта.
    • payment_currency — валюта платежа в формате ISO-4217 alpha-3.
    • payment_amount — сумма платежа в минорных единицах валюты. В запросах на оплаты с указанием валюты IDR необходимо округлять суммы до целых чисел. Если в запросе указывается иная валюта, то сумма платежа конвертируется на стороне ecommpay в эквивалентную сумму в валюте IDR и также округляется до целых чисел. При этом округление выполняется в большую сторону (например, если в результате конвертации получается сумма 200 000,05 IDR, то такая сумма округляется до 200 001,00 IDR).
    • customer_id — идентификатор пользователя, уникальный в рамках проекта.
  2. При использовании платёжного метода Indonesian Virtual Accounts можно настраивать отображение страницы Payment Page с выбором метода оплаты.

    По умолчанию банки, поддерживающие проведение оплат методом Indonesian Virtual Accounts, объединены в группу и отображаются одной кнопкой Online Indonesian VA Banks, поэтому выбор банка осуществляется в два этапа. Сначала выбирается метод Indonesian Virtual Accounts среди прочих, а затем на следующей странице с перечнем банков выбирается конкретный банк. Существует несколько вариантов отображения страницы Payment Page с выбором метода оплаты:

    • Отображение поддерживаемых банков одной кнопкой Online Indonesian VA Banks среди прочих методов.
    • Отображение каждого поддерживаемого банка отдельной кнопкой. Для этого необходимо передавать параметр split_banks со значением true в строке payment_methods_options.
      payment_methods_options={"indonesia_va": {"split_banks": true}}
      
    • Отображение только поддерживаемых банков одной кнопкой Online Indonesian VA Banks. Для этого используется предварительный выбор метода Indonesian Virtual Accounts. Необходимо передавать код платежного метода indonesia-va в параметре force_payment_method. Пользователю открывается страница с выбором банков.
    • Отображение кнопок конкретных банков (одного или нескольких). В списке методов может присутствовать метод Indonesian Virtual Accounts. Для этого используется предварительный выбор метода Indonesian Virtual Accounts, но с указанием конкретного банка. Для этого необходимо передавать код платежного метода indonesia-va в параметре force_payment_method и идентификатор банка banks_id в параметре payment_methods_options. Для отображения нескольких банков необходимо перечислять идентификаторы этих банков через запятую c пробелом.
      payment_methods_options={"indonesia_va": {"split_banks": true, "banks_id": [2831, 2931]}}

      Далее представлен пример запроса на открытие Payment Page с предварительно выбранным банком.

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

      EPayWidget.run(
          { payment_id: 'X03936', 
            payment_amount: 20000000, 
            payment_currency: 'IDR', 
            project_id: 120,
            customer_id: '1',
            force_payment_method: 'indonesia-va',
            payment_methods_options={"indonesia_va": {"banks_id": [2931]}},
            signature: "kUi2x9dKHAVNU0FY...vySO\/RLCvhtT4DqtVUkDJrOcZzUCwX6R\/ekpZhkIQg=="
          }
      )
  3. Дополнительно могут использоваться любые другие параметры из числа доступных для работы с Payment Page. Детальная информация обо всех параметрах приведена в разделе Параметры вызова платёжной формы.
  4. После определения всех параметров необходимо составить подпись. Подробнее — в разделе Работа с подписью к данным.

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

    { payment_id: 'X03936', 
      payment_amount: 20000000, 
      payment_currency: 'IDR', 
      project_id: 123,
      customer_id: 'customer1',
      signature: "kUi2x9dKHAVNU0FYldJrxh4yo+52Kt8KURLCvhtT4DqtOcZzUCwX6R\/ekpZhkIQg=="
    }

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

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

В следующем примере оповещение свидетельствует о том, что в рамках проекта 200 была успешно проведена оплата в размере 200 000,00 IDR на виртуальный счёт 8856113600001045.

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

 {
        "project_id": 200,
        "payment": {
            "id": "9770802",
            "type": "purchase",
            "status": "success",
            "date": "2020-02-22T22:44:46+0000",
            "method": "indonesia-va",
            "sum": {
                "amount": 20000000,
                "currency": "IDR"
            },
            "description": "test"
        },
        "account": {
            "number": "8856113600001045"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 52084000029401,
            "type": "sale",
            "status": "success",
            "date": "2020-02-22T22:44:46+0000",
            "created_date": "2020-02-22T17:30:42+0000",
            "request_id": "59b48b4c2d0a2b6a-00052085",
            "sum_initial": {
                "amount": 20000000,
                "currency": "IDR"
            },
            "sum_converted": {
                "amount": 20000000,
                "currency": "IDR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 1164,
                "payment_id": "644206",
                "auth_code": "",
                "date": "2020-02-22T22:44:45+0000"
            }
        },
        "signature": "Hekd6+86S592dGuYCHNLADZ8LaBC5/JSKObUxTvkUuCZL4phAiFQA=="
    }

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

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

{
        "project_id": 200,
        "payment": {
            "id": "9770802",
            "type": "purchase",
            "status": "decline",
            "date": "2020-02-22T22:44:46+0000",
            "method": "indonesia-va",
            "sum": {
                "amount": 1000,
                "currency": "IDR"
            },
            "description": "test"
        },
        "account": {
            "number": "8856113600001046"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 52084000029401,
            "type": "sale",
            "status": "decline",
            "date": "2020-02-22T22:44:46+0000",
            "created_date": "2020-02-22T17:30:42+0000",
            "request_id": "59b48b4c2d0a2b6a-00052085",
            "sum_initial": {
                "amount": 1000,
                "currency": "IDR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "IDR"
            },
            "code": "20101",
            "message": "Decline due to amount or frequency limit",
        },
        "signature": "Hekd6+86S592dGuYCHNLADZ8LaBC5/JSKObUxTvkUuCZL4phAiFQA=="
    }

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

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

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

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

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

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

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

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



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

  1. Пользователь на стороне веб-сервиса инициирует оплату методом Indonesian Virtual Accounts.
  2. От веб-сервиса на заданный URL ecommpay передаётся запрос на проведение оплаты через Gate.
  3. Запрос на проведение оплаты поступает в платёжную платформу.
  4. Выполняется начальная обработка запроса, в рамках которой обеспечивается проверка наличия обязательных параметров и корректной подписи.
  5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности. Подробнее см. в разделе Формат ответа.
  6. В платёжной платформе выполняются дальнейшая обработка запроса и его отправка в сервис провайдера.
  7. На стороне провайдера выполняется обработка запроса на оплату.
  8. От сервиса провайдера к платёжной платформе передаются данные для перенаправления пользователя на сайт провайдера.
  9. От платёжной платформы к веб-сервису направляется оповещение с данными для перенаправления пользователя на сайт провайдера.
  10. Пользователь перенаправляется на сайт провайдера, где ему отображается 16-значный код для оплаты и платёжная инструкция.
  11. Согласно инструкции, пользователь вводит код на сайте банка либо с использованием банкомата или мобильного приложения банка, и подтверждает оплату.
  12. На стороне провайдера выполняется обработка платежа.
  13. От сервиса провайдера к платёжной платформе направляется уведомление о результате оплаты.
  14. От платёжной платформы к веб-сервису направляется оповещение о результате оплаты.
  15. От веб-сервиса пользователю направляется информация о результате оплаты.

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

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

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

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

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

{
    "general": {
      "project_id": 2990,
      "payment_id": payment_id,
      "signature": "PJkV8ej\/UG0Di8hTng6JvC7vQsaC6tajQVVfBaNIipTv+AWoXW\/9MTO8yJA=="
    },
    "payment": {
      "amount": 35000000,
      "currency": "IDR"
      },
    "customer": {
      "id": "12345",
      "ip_address": "1.1.1.1"
    },
    "account":{
      "bank_id": 2961
    }
 }

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

Для перенаправления пользователей от веб-сервиса на страницу с инструкцией по оплате необходимо:

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

Далее приведён фрагмент оповещения, содержащего данные для перенаправления пользователя:

    "redirect_data": {
        "body": {},
        "method": "POST",
        "url": "http://example.test//payment"
    }

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

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

В следующем примере оповещение свидетельствует о том, что в рамках проекта 200 была успешно проведена оплата в размере 200 000,00 IDR на виртуальный счёт 8856113600001045.

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

 {
        "project_id": 200,
        "payment": {
            "id": "9770802",
            "type": "purchase",
            "status": "success",
            "date": "2020-02-22T22:44:46+0000",
            "method": "indonesia-va",
            "sum": {
                "amount": 20000000,
                "currency": "IDR"
            },
            "description": "test"
        },
        "account": {
            "number": "8856113600001045"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 52084000029401,
            "type": "sale",
            "status": "success",
            "date": "2020-02-22T22:44:46+0000",
            "created_date": "2020-02-22T17:30:42+0000",
            "request_id": "59b48b4c2d0a2b6a-00052085",
            "sum_initial": {
                "amount": 20000000,
                "currency": "IDR"
            },
            "sum_converted": {
                "amount": 20000000,
                "currency": "IDR"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 1164,
                "payment_id": "644206",
                "auth_code": "",
                "date": "2020-02-22T22:44:45+0000"
            }
        },
        "signature": "Hekd6+86S592dGuYCHNLADZ8LaBC5/JSKObUxTvkUuCZL4phAiFQA=="
    }

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

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

{
        "project_id": 200,
        "payment": {
            "id": "9770802",
            "type": "purchase",
            "status": "decline",
            "date": "2020-02-22T22:44:46+0000",
            "method": "indonesia-va",
            "sum": {
                "amount": 1000,
                "currency": "IDR"
            },
            "description": "test"
        },
        "account": {
            "number": "8856113600001046"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 52084000029401,
            "type": "sale",
            "status": "decline",
            "date": "2020-02-22T22:44:46+0000",
            "created_date": "2020-02-22T17:30:42+0000",
            "request_id": "59b48b4c2d0a2b6a-00052085",
            "sum_initial": {
                "amount": 1000,
                "currency": "IDR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "IDR"
            },
            "code": "20101",
            "message": "Decline due to amount or frequency limit",
        },
        "signature": "Hekd6+86S592dGuYCHNLADZ8LaBC5/JSKObUxTvkUuCZL4phAiFQA=="
    }

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

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

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

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

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

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

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

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