SDK для Android

Возможности

SDK для Android позволяет проводить платежи с использованием платежных карт, а также альтернативных платежных методов. Для платежей с использованием карт доступны проведение разовых и повторяемых оплат, проверка действительности карт (подробнее).

Также поддерживается проведение платежей с использованием методов, информация о которых представлена в разделе Платежные методы. По вопросам, связанным с подключением этих платежных методов, следует обращаться к курирующему менеджеру PSPHost.

Состав

SDK для Android содержит файл с библиотеками psphostSDK.aar и примеры работы на языках программирования Java и Kotlin.

Схема работы

Проведение платежей с использованием SDK для Android выполняется следующим образом:

1. В клиентской части мобильного приложения формируется объект с необходимыми параметрами для проведения платежа.
2. В серверной части мобильного приложения вычисляется подпись на основании параметров платежа.
3. В клиентской части формируется итоговый запрос на проведение платежа и с помощью библиотеки отправляется в платежную платформу PSPHost.
4. В платежной платформе выполняется обработка платежа.
5. От платежной платформы к клиентской части отправляется результат выполнения платежа.
6. От платежной платформы на заданный URL отправляется оповещение.

Подключение и использование

Для использования SDK для Android необходимо:

1. Решить организационные вопросы, касающиеся взаимодействия с PSPHost:
   • Если у компании нет идентификатора и ключа для взаимодействия с PSPHost — отправить заявку на подключение.
   • Если у компании есть идентификатор и ключ для взаимодействия с PSPHost — сообщить специалистам технической поддержки о намерении интеграции с использованием SDK для Android и согласовать с ними порядок тестирования и запуска.
2. Выполнить подготовительные технические работы:
   1. Обеспечить подписывание данных на стороне серверной части мобильного приложения.
   2. Скачать и подключить SDK для Android.
   3. Доработать клиентскую часть мобильного приложения для инициирования платежей необходимых типов и обработки результатов этих платежей.
3. Протестировать и запустить в работу обновленное приложение.
   1. Для тестирования следует использовать тестовый идентификатор проекта и данные тестовых карт, предоставленные специалистами технической поддержки PSPHost.
   2. Для перевода в рабочий режим следует изменить тестовое значение идентификатора проекта на рабочее значение, полученное от PSPHost.

При возникновении вопросов о работе с SDK для Android следует обращаться в службу технической поддержки PSPHost support@psphost.com.

Интерфейс платежной формы

Подключение библиотек к проекту

Вызов в Java

Для вызова платежной формы необходимо выполнить следующие действия:

1. Создать объект PSPHOSTPaymentInfo. Этот объект должен содержать обязательные параметры для открытия платежной формы:
   • projectID — идентификатор проекта, полученный от PSPHost при интеграции;
   • paymentID — идентификатор платежа, уникальный в рамках проекта;
   • paymentAmount — сумма платежа в дробных единицах валюты без десятичной точки и пробелов;
   • paymentCurrency — валюта платежа в формате ISO-4217 alpha-3.

   Пример объекта PSPHOSTPaymentInfo, который содержит только обязательные параметры:

   PSPHOSTPaymentInfo paymentInfo = new PSPHOSTPaymentInfo(
                  115, // идентификатор проекта, полученный от PSPHost при интеграции
                  "internal_payment_id_1", // идентификатор платежа, уникальный в рамках проекта
                  1999, // сумма платежа в дробных единицах валюты
                  "USD" // валюта платежа в формате ISO-4217 alpha-3
                  );

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

   • recurrentInfo — объект с информацией о повторяемой оплате (подробнее).
   • paymentDescription — описание платежа (данный параметр доступен не только мерчанту, но и пользователю; если параметр paymentDescription передан в запросе, он отображается в платежной форме в диалоговом окне с информацией о платеже; если параметр не передан в запросе, пользователю он не виден).
   • customerID — идентификатор пользователя, уникальный в рамках проекта.
   • regionCode — код страны пользователя в формате ISO 3166 alpha-2.
   • ActionType — тип действия. Допустимые значения: Sale (по умолчанию), Auth, Verify и Tokenize.
   • token — токен карты.
   • forcePaymentMethod — идентификатор платежного метода, который следует открыть в платежной форме. Если этот параметр задан, то страница выбора метода не отображается и пользователю не предоставляется возможность выбрать платежный метод. Список идентификаторов платежных методов приведен в разделе Коды поддерживаемых платежных методов на Payment Page.
   • hideSavedWallets — параметр, позволяющий управлять отображением сохраненных ранее платежных инструментов и при необходимости скрывать сохраненные платежные инструменты в платежной форме. Возможные значения:
     • true — сохраненные ранее платежные инструменты скрыты, они не отображаются при открытии платежной формы.
     • false — сохраненные ранее платежные инструменты отображаются при открытии платежной формы.
   • PSPHOSTScreenDisplayMode — объект, позволяющий управлять отображением финальной страницы оплаты и при необходимости скрывать ее. В объекте возможно передавать следующие параметры:
     • hide_success_final_page — финальная страница с сообщением о совершенном платеже не отображается в платежной форме,
     • hide_decline_final_page — финальная страница с сообщением об отклоненном платеже не отображается в платежной форме.

     Пример передачи в запросе параметров hide_success_final_page и hide_decline_final_page:

     // Init PSPHOSTPaymentInfo
      
     paymentInfo.addPsphostScreenDisplayMode("hide_success_final_page")
                .addPsphostScreenDisplayMode("hide_decline_final_page");

   Пример объекта PSPHOSTPaymentInfo, который содержит необязательные параметры (описание платежа, идентификатор и страну пользователя):

   PSPHOSTPaymentInfo paymentInfo = new PSPHOSTPaymentInfo(
                     115, // идентификатор проекта, полученный от PSPHost при интеграции
                     "internal_payment_id_1", // идентификатор платежа, уникальный в рамках проекта
                     1999, // сумма платежа в дробных единицах валюты
                     "USD" // валюта платежа в формате ISO-4217 alpha-3
                     "T-shirt with dog print", // описание платежа
                     "10", // идентификатор пользователя, уникальный в рамках проекта
                     "US" // код страны в формате ISO 3166 alpha-2
                      );

2. Получить строку для подписывания указанных параметров.

   paymentInfo.getParamsForSignature();

3. Передать сгенерированную строку в серверную часть приложения.
4. Сгенерировать подпись на стороне серверной части приложения и передать ее в клиентскую часть.
5. Добавить подпись в объект paymentInfo.

   paymentInfo.setSignature(signature);

6. Вызвать платежную форму.

   startActivityForResult(PSPHOSTActivity.buildIntent(this,
                       paymentInfo),
                       PAY_ACTIVITY_REQUEST);

Вызов в Kotlin

Для вызова платежной формы необходимо выполнить следующие действия:

1. Создать объект PSPHOSTPaymentInfo. Этот объект должен содержать обязательные параметры для открытия платежной формы:
   • projectID — идентификатор проекта, полученный от PSPHost при интеграции;
   • paymentID — идентификатор платежа, уникальный в рамках проекта;
   • paymentAmount — сумма платежа в дробных единицах валюты без десятичной точки и пробелов;
   • paymentCurrency — валюта платежа в формате ISO-4217 alpha-3.

   Пример объекта PSPHOSTPaymentInfo, который содержит только обязательные параметры:

   val paymentInfo = PSPHOSTPaymentInfo(
                       115, // идентификатор проекта, полученный от PSPHost при интеграции
                       "internal_payment_id", // идентификатор платежа, уникальный в рамках проекта
                       1999, // сумма платежа в дробных единицах валюты
                       "USD") // валюта платежа в формате ISO-4217 alpha-3

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

   • recurrentInfo — объект с информацией о повторяемой оплате (подробнее).
   • paymentDescription — описание платежа (данный параметр доступен не только мерчанту, но и пользователю; если параметр paymentDescription передан в запросе, он отображается в платежной форме в диалоговом окне с информацией о платеже; если параметр не передан в запросе, пользователю он не виден).
   • customerID — идентификатор пользователя, уникальный в рамках проекта.
   • regionCode — код страны пользователя в формате ISO 3166 alpha-2.
   • ActionType — тип действия. Допустимые значения: Sale (по умолчанию), Auth, Verify и Tokenize.
   • token — токен карты.
   • forcePaymentMethod — идентификатор платежного метода, который следует открыть в платежной форме. Если этот параметр задан, то страница выбора метода не отображается и пользователю не предоставляется возможность выбрать платежный метод. Список идентификаторов платежных методов приведен в разделе Коды поддерживаемых платежных методов на Payment Page.
   • hideSavedWallets — параметр, позволяющий управлять отображением сохраненных ранее платежных инструментов и при необходимости скрывать сохраненные платежные инструменты в платежной форме. Возможные значения:
     • true — сохраненные ранее платежные инструменты скрыты, они не отображаются при открытии платежной формы.
     • false — сохраненные ранее платежные инструменты отображаются при открытии платежной формы.
   • PSPHOSTScreenDisplayMode — объект, позволяющий управлять отображением финальной страницы оплаты и при необходимости скрывать ее. В объекте возможно передавать следующие параметры:
     • hide_success_final_page — финальная страница с сообщением о совершенном платеже не отображается в платежной форме,
     • hide_decline_final_page — финальная страница с сообщением об отклоненном платеже не отображается в платежной форме.

     Пример передачи в запросе параметров hide_success_final_page и hide_decline_final_page:

     // Init PSPHOSTPaymentInfo
      
     paymentInfo.addPsphostScreenDisplayMode("hide_success_final_page")
                .addPsphostScreenDisplayMode("hide_decline_final_page");

   Пример объекта PSPHOSTPaymentInfo, который содержит необязательные параметры (описание платежа, идентификатор и страну пользователя):

   val paymentInfo = PSPHOSTPaymentInfo(
                      115, // идентификатор проекта, полученный от PSPHost при интеграции
                      "internal_payment_id", // идентификатор платежа, уникальный в рамках проекта
                      1999, // сумма платежа в дробных единицах валюты
                      "USD", // валюта платежа в формате ISO-4217 alpha-3
                      "T-shirt with dog print", // описание платежа
                      "10", // идентификатор пользователя, уникальный в рамках проекта
                      "US")  // код страны в формате ISO 3166 alpha-2

2. Получить строку для подписывания указанных параметров.

   paymentInfo.getParamsForSignature();

3. Передать сгенерированную строку в серверную часть приложения.
4. Сгенерировать подпись на стороне серверной части приложения и передать ее в клиентскую часть.
5. Добавить подпись в объект paymentInfo.

   paymentInfo.signature = signature

6. Вызвать платежную форму.

   startActivityForResult(
                       PSPHOSTActivity.buildIntent(this,
                       paymentInfo),
                       PAY_ACTIVITY_REQUEST)

Обзор

При работе с SDK для Android поддерживается использование оповещений, отправляемых платежной платформой PSPHost напрямую к веб-сервису мерчанта, и оповещений, передаваемых вначале от платежной формы к SDK для Android, а затем — от SDK для Android к мобильному приложению мерчанта. В первом случае набор параметров, передаваемых в оповещении, может отличаться в зависимости от установленных настроек (подробнее: Как выглядит оповещение в PSPHost). Во втором случае передается строго определенный набор параметров — данные о статусе, типе и идентификаторе платежа, дате проведения платежа, используемом платежном методе, сумме и валюте платежа:

{
    "payment": {
        "status": "success",
        "type": "purchase",
        "id": "12345",
        "date": "2020-09-11T14:49:18+0000",
        "method": "card",
        "sum": 1000,
        "currency": "USD"
         }
}

Далее представлена информация об этих оповещениях.

Оповещения платежной платформы

При проведении платежа платежная платформа отправляет оповещения на указанный URL. Этот URL необходимо сообщить службе технической поддержки PSPHost. Подробная информация об оповещениях представлена в разделе Оповещения (callbacks) в Payment Page.

Оповещения SDK для Android

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

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

1. Создать приемник широковещательных сообщений — объект BroadcastReceiver.
2. При поступлении в BroadcastReceiver широковещательных сообщениях от SDK для Android, с помощью ключа PSPHOSTCallbackType.PSPHOST_CALLBACK_PAYMENT_RESULT.getValue() получать из объекта Intent информацию о платеже. Ключ представляет собой константу, предоставляемую PSPHOSTActivity.

Далее представлены примеры реализации BroadcastReceiver для получения информации о результате проведения платежа.

class YourClass {   
    private BroadcastReceiver mReceiver = new BroadcastReceiver() {
        @Override
        public void onReceive(Context context, Intent intent) {
            PSPHOSTPaymentData paymentData = intent.getParcelableExtra(PSPHOSTCallbackType.PSPHOST_CALLBACK_PAYMENT_RESULT.getValue());
        }
    };
}

class YourClass {  
    private val mReceiver: BroadcastReceiver = object : BroadcastReceiver() {
        override fun onReceive(context: Context, intent: Intent) {
            val paymentData: PSPHOSTPaymentData = intent.getParcelableExtra(PSPHOSTCallbackType.PSPHOST_CALLBACK_PAYMENT_RESULT.value)
        }
    }
}

Оплата с использованием сохраненных данных

Пользователь может сохранить реквизиты карты при совершении оплаты. Тогда при проведении последующих платежей пользователю достаточно лишь выбрать карту из списка сохраненных и ввести значение CVV.

Для обеспечения возможности сохранения данных карты и проведения оплаты по сохраненным данным пользователя в объект PSPHOSTPaymentInfo необходимо добавить параметр customerID, который позволяет привязать список карт к определенному пользователю на стороне платежной платформы. При проведении данного типа платежей SDK для Android отправляет запрос в платежную платформу на получение списка сохраненных карт пользователя и при наличии таковых выводит их на платежной форме. Если пользователь исключает карту из списка сохраненных, то SDK для Android отправляет запрос в платежную платформу на удаление данных из списка сохраненных платежных инструментов.

Оплата с использованием токенов

SDK для Android предоставляет возможность проводить платежи по токену карты. В этом случае на стороне серверной части приложения необходимо обеспечить хранение данных карты пользователя и ее токена. Если заданный токен соответствует карте пользователя, то при проведении оплаты пользователю отображается форма оплаты с предварительно выбранной картой и заполненными данными этой карты, кроме CVV.

При использовании токена для проведения оплат параметр token должен быть включен в список параметров для подписывания.

Для оплаты по токену необходимо задать токен в объекте paymentInfo:

paymentInfo.setToken(token);

Автоматическая генерация токена

Автоматическая генерация токена происходит при проведении первой успешной оплаты по карте, а также при успешной блокировке средств. Сгенерированный токен и время его создания возвращаются в оповещении о проведении платежа.

"account": {
            "number": "546942******3838",
            "token": "7e12077a71faf915bc4bda60f059854c7df4a46e7573057e52ece0801245666b",
            "type": "mastercard",
            "card_holder": "JOHN SMITH",
            "id": 7279487,
            "expiry_month": "11",
            "expiry_year": "2021"
        },

Генерация токена по запросу

paymentInfo.setAction(PSPHOSTPaymentInfo.ActionType.Tokenize);

paymentInfo.setAction(PSPHOSTPaymentInfo.ActionType.Tokenize)

Сгенерированный токен и время его создания возвращаются в оповещении о генерации токена.

Базовый вариант оплаты

По умолчанию в SDK для Android настроено проведение разовых одностадийных оплат (тип действия Sale). Для проведения данного типа оплат можно использовать приведенные примеры и дополнительно ничего не настраивать.

Разовая двухстадийная оплата

Подробная информация о проведении оплат с предварительной блокировкой представлена в разделе Блокировка средств.

Повторяемая оплата

SDK для Android поддерживает проведение повторяемых оплат. Такие оплаты бывают трех типов: OneClick, автооплаты и регулярные оплаты. Подробнее о повторяемых оплатах — в разделе Общая информация.

Проверка действительности карты

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

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

paymentInfo.setAction(PSPHOSTPaymentInfo.ActionType.Verify);

paymentInfo.setAction(PSPHOSTPaymentInfo.ActionType.Verify)