Java SDK для интеграции с API СБП

Link to English version

Содержание

Документация
Подключение
Использование
Регистрация QR-кода
Получение данных по зарегистрированному ранее QR-коду
Получение информации по платежу
Оформление возврата по платежу
Получение информации по возврату
Создание заказа
Получение данных по заказу
Оформление возврата по заказу
Получение статуса возврата заказа
Отмена заказа
Привязка NFC-метки
Обработка уведомлений
Шпаргалка

Документация

API: https://e-commerce.raiffeisen.ru/api/doc/sbp.html

Подключение

Требования:

Java 11+
Apache Maven

Для подключения SDK требуется:

Создать в корне проекта каталог с названием "dependencies".
Поместить в созданный каталог файл .jar и pom.xml по ссылке.
pom.xml своего проекта поместить следующее:

    <properties>
        <maven.compiler.source>11</maven.compiler.source>
        <maven.compiler.target>11</maven.compiler.target>
    </properties>

    <dependencies>
        <dependency>
            <groupId>raiffeisen</groupId>
            <artifactId>sbp-sdk-java</artifactId>
            <version>1.0.8</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-install-plugin</artifactId>
                <version>2.5.2</version>
                <configuration>
                    <groupId>raiffeisen</groupId>
                    <artifactId>sbp-sdk-java</artifactId>
                    <version>1.0.8</version>
                    <packaging>jar</packaging>
                    <file>dependencies/sbp-sdk-java-1.0.8.jar</file>
                    <generatePom>false</generatePom>
                    <pomFile>dependencies/pom.xml</pomFile>
                </configuration>
                <executions>
                    <execution>
                        <id>install-jar-lib</id>
                        <goals>
                            <goal>install-file</goal>
                        </goals>
                        <phase>validate</phase>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>

Выполнить команды в maven:
- validate(mvn validate)
- install(mvn install)

Использование

Для использования SDK необходимо создать объект класса SbpClient, указав в конструкторе URL, на который будут отправляться запросы (SbpClient.PRODUCTION_URL или SbpClient.TEST_URL), id мерчанта в системе СБП и секретный ключ для авторизации. Этот клиент используется для всех взаимодействий с API.

Все запросы осуществляются классом SbpClient. Посмотреть возвращаемые значения можно по ссылке.

Клиент может вернуть следующие типы исключений:

IOException - ошибка сетевого взаимодействия
SbpException - логическая ошибка при попытке обработать запрос
ContractViolationException - ошибка в обработке ответа от сервера

import raiffeisen.sbp.sdk.client.SbpClient;
import raiffeisen.sbp.sdk.exception.ContractViolationException;
import raiffeisen.sbp.sdk.exception.SbpException;
import raiffeisen.sbp.sdk.model.in.QRUrl;
import raiffeisen.sbp.sdk.model.out.QR;
import raiffeisen.sbp.sdk.model.out.QRDynamic;
import raiffeisen.sbp.sdk.util.QRUtil;

import java.io.IOException;
import java.math.BigDecimal;

public class AppExample {
   public static void main(String[] args) {
       String secretKey = "..."; // change this to your secretKey
       String sbpMerchantId = "..."; // change this to your sbpMerchantId
       SbpClient client = new SbpClient(SbpClient.TEST_URL, sbpMerchantId, secretKey);
       try {
           String order = QRUtil.generateOrderNumber();
           // save order in a database;
           QR qrCode = new QRDynamic(order, new BigDecimal(100));
           qrCode.setAccount("40700000000000000000");
           qrCode.setAdditionalInfo("Доп информация");
           qrCode.setPaymentDetails("Назначение платежа");
           qrCode.setQrExpirationDate(ZonedDateTime.now().plusDays(1));
           QRUrl response = client.registerQR(qrCode);
           response.getQrId();
           response.getOrUrl();
           response.getPayload();
       }
       catch (IOException networkException) {
           networkException.getMessage();
       }
       catch (SbpException sbpException) {
           sbpException.getCode(); // Error id
           sbpException.getMessage();
       }
       catch (ContractViolationException contractException) {
           contractException.getHttpCode();
           contractException.getMessage();
       }
   }
}

Регистрация QR-кода

Для регистрации кода необходимо создать экземпляр класса QRStatic, QRDynamic или QRVariable. Для разных типов QR-кодов обязательные параметры отличаются.

Обязательные параметры:

номер заказа в системе партнера order(String)
(QRDynamic) сумма в рублях amount(BigDecimal)

Опциональные параметры могут быть заполнены с помощью set методов.

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

String order = QRUtil.generateOrderNumber();

// save order in a database;

QRDynamic qrCode = new QRDynamic(order, new BigDecimal(100));
qrCode.setAccount("40700000000000000000");
qrCode.setAdditionalInfo("Доп информация");
qrCode.setPaymentDetails("Назначение платежа");
qrCode.setQrExpirationDate("2023-07-22T09:14:38.107227+03:00");

QRUrl response = client.registerQR(qrCode);

// place your code here

Ответ:

{
  "qrId": "AD100004BAL7227F9BNP6KNE007J9B3K",
  "payload": "https://qr.nspk.ru/AD100004BAL7227F9BNP6KNE007J9B3K?type=02&bank=100000000007&sum=1&cur=RUB&crc=AB75",
  "qrUrl": "https://e-commerce.raiffeisen.ru/api/sbp/v1/qr/AD100004BAL7227F9BNP6KNE007J9B3K/image"
}

Пример с минимальными данными:

String order = QRUtil.generateOrderNumber(); // UUID_v4

// save order in a database;

// QRStatic qrStatic = new QRStatic(order);
//
// or
//
// QRDynamic qrDynamic = new QRDynamic(order, new BigDecimal(100));

Также существует возможность заполнить необязательный параметр qrExpirationDate с помощью сдвига относительно даты создания. Для этого в поле qrExpirationDate следует указать строку вида "+<число1><буква1>".

'M' - месяц
'd' - день
'H' - час
'm' - минута
's' - секунда

Пример:

String order = QRUtil.generateOrderNumber(); // UUID_v4

// save order in a database;

QRStatic qrStatic = new QRStatic(order);
qrStatic.setQrExpirationDate("+5m"); // + 5 minutes

QRDynamic qrDynamic = new QRDynamic(order, new BigDecimal(100));
qrDynamic.setQrExpirationDate("+1d5m"); // + 1 day 5 minutes

Получение данных по зарегистрированному ранее QR-коду

Необходимо создать объект класса QRId, передав в конструкторе идентификатор QR-кода, и вызвать метод getQRInfo(QRId):

String qrIdString = "...";

QRId id = new QRId(qrIdString);

QRUrl response = client.getQRInfo(id);

// place your code here

Ответ

{
  "qrId": "AD100004BAL7227F9BNP6KNE007J9B3K",
  "payload": "https://qr.nspk.ru/AD100004BAL7227F9BNP6KNE007J9B3K?type=02&bank=100000000007&sum=1&cur=RUB&crc=AB75",
  "qrUrl": "https://e-commerce.raiffeisen.ru/api/sbp/v1/qr/AD100004BAL7227F9BNP6KNE007J9B3K/image"
}

Получение информации по платежу

Необходимо создать объект класса QRId, передав в конструкторе идентификатор QR-кода, и вызвать метод getPaymentInfo(QRId):

String qrIdString = "...";

QRId id = new QRId(qrIdString);

PaymentInfo response = client.getPaymentInfo(id);

// place your code here

Ответ:

{
  "additionalInfo": "Доп информация",
  "amount": 12399,
  "createDate": "2020-01-31T09:14:38.107227+03:00",
  "currency": "RUB",
  "merchantId": 123,
  "order": "282a60f8-dd75-4286-bde0-af321dd081b3",
  "paymentStatus": "NO_INFO",
  "qrId": "AD100051KNSNR64I98CRUJUASC9M72QT",
  "sbpMerchantId": "MA0000000553",
  "transactionDate": "2019-07-11T17:45:13.109227+03:00",
  "transactionId": 23
}

Оформление возврата по платежу

Для возврата средств необходимо создать объект класса RefundInfo, заполнив необходимые поля, и вызвать метод refundPayment(RefundInfo). Подробности об обязательных полях в документации.

Обязательные параметры:

сумма возврата в рублях amount(BigDecimal)
идентификатор заказа платежа в Райффайзенбанке, используется для возвратов по динамическому QR order(String)
уникальный идентификатор запроса на возвратrefundId(String)

BigDecimal moneyAmount = new BigDecimal(150);
String orderInfo = "...";
String refundId = "...";
long transactionId = ...;

RefundInfo refundInfo = new RefundInfo(moneyAmount, orderInfo, refundId);

RefundStatus response = client.refundPayment(refundInfo);

// place your code here

Ответ:

{
  "amount": 150,
  "refundStatus": "IN_PROGRESS"
}

Получение информации по возврату

Для выполнения данного запроса необходимо указать уникальный идентификатор запроса на возврат refundId при вызове метода getRefundInfo(refundId):

String refundIdString = "...";
RefundId refundId = new RefundId(refundIdString);

RefundStatus response = client.getRefundInfo(refundId);

// place your code here

Ответ:

{
  "amount": 150,
  "refundStatus": "IN_PROGRESS"
}

Создание заказа

Для создания заказа необходимо создать экземпляр класса Order

Обязательные параметры:

Сумма в рублях amount

Опциональные параметры могут быть заполнены с помощью set методов.

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

Order order = Order.builder().amount(BigDecimal.ZERO).build();
OrderInfo response = TestUtils.CLIENT.createOrder(order);

'M' - месяц
'd' - день
'H' - час
'm' - минута
's' - секунда

Пример:

Order order = Order.builder().amount(BigDecimal.ZERO).expirationDate("+5m").build(); // + 5 minutes

Order order = Order.builder().amount(BigDecimal.ZERO).expirationDate("+1d5m").build(); // + 1 day 5 minutes

Также существует возможность заполнить необязательный параметр qr: Для этого нужно создать экземпляр класса OrderQr

OrderQr:

id (required, Параметр должен быть заполнен идентификатором QR, который был получен в ответе на запрос регистрации QR-кода)
additionalInfo
paymentDetails

Пример:

QRVariable qrVariable = new QRVariable();
QRUrl qr = TestUtils.CLIENT.registerQR(qrVariable);
OrderQr orderQr = new OrderQr(qr.getQrId());

Order order = Order.builder().amount(new BigDecimal(314)).qr(orderQr).build();
OrderInfo response = TestUtils.CLIENT.createOrder(order);

Также существует возможность заполнить необязательный параметр id: Это уникальный идентификатор заказа. Рекомендуется использовать формат, не допускающий возможность перебора, например, UUID v4 Если параметр не передан, то идентификатор присвоится заказу автоматически

Пример:

Order order = Order.builder().amount(new BigDecimal(314)).id("QUAaOlCRU0Bdub8J4TeEpddUacwZmCIv221208").build();

Также существует возможность заполнить необязательный параметр comment: Комментарий к заказу

Пример:

Order order = Order.builder().amount(new BigDecimal(314)).comment("Комментарий к заказу")).build();

Получение данных по заказу

Необходимо создать объект класса OrderId, передав в конструкторе идентификатор заказа, и вызвать метод getOrderInfo(OrderId):

String orderIdString = "...";

orderId = new OrderId(orderIdString);

OrderInfo response = client.getOrderInfo(orderId);

// place your code here

Ответ

{
  "id": "c5b3fd07-c66b-4f11-a8a2-1cc5d319f9e3",
  "amount": 1000.1,
  "comment": "Шоколадный торт",
  "extra": {
    "apiClient": "sbp-sdk-client",
    "apiClientVersion": "1.0.5"
  },
  "status": {
    "value": "NEW",
    "date": "2021-12-24T11:15:22.000Z"
  },
  "expirationDate": "2022-01-24T11:15:22.000Z",
  "qr": {
    "id": "AD100004BAL7227F9BNP6KNE007J9B3K",
    "additionalInfo": "Доп. информация",
    "paymentDetails": "Назначение платежа"
  }
}

Отмена заказа

Необходимо создать объект класса OrderId, передав в конструкторе идентификатор заказа, и вызвать метод orderCancellation(OrderId):

String orderIdString = "...";

orderId = new OrderId(orderIdString);

OrderInfo response = client.orderCancellation(orderId);

// place your code here

Оформление возврата по заказу

Необходимо создать объект класса OrderRefund, передав в конструкторе уникальный id заказа, уникальный id запроса на возврат, сумму возврата в рублях.
Вызвать метод orderRefund(OrderRefund)

BigDecimal moneyAmount = new BigDecimal(150);
String orderIdString = "...";
String refundIdString ="...";
OrderRefund orderRefund = new OrderRefund(orderIdString, refundIdString, moneyAmount);
orderRefund.setPaymentDetails("payment details");

RefundStatus response = client.orderRefund(orderRefund);

// place your code here

Ответ:

{
  "amount": 150,
  "refundStatus": "IN_PROGRESS"
}

Получение статуса возврата заказа

Необходимо Вызвать метод orderRefundStatus передав в параметры уникальный id заказа и уникальный id запроса на возвратorderRefundStatus(orderId, refundId)

String orderIdString = "...";
String refundIdString ="...";

RefundStatus response = client.orderRefundStatus(orderIdString, refundIdString);

// place your code here

Ответ:

{
  "amount": 150,
  "refundStatus": "IN_PROGRESS"
}

Привязка NFC-метки

Необходимо Вызвать метод createNfcLink передав в параметры класс NFC createNfcLink(NFC)

NFC:

qrID - обязательный параметр
account
redirectUrl

String qrId = "...";

NFC nfc = new NFC(qrId);

nfc.setRedirectUrl("string");
nfc.setAccount("string");

NFCInfo response = client.createNfcLink(NFC);

// place your code here

Ответ:

{
"qrId": "string",
"qrStatus": "INACTIVE",
"qrExpirationDate": "string",
"payload": "string",
"qrUrl": "string",
"subscriptionId": "string"
}

Обработка уведомлений

Для хранения и использования уведомлений существует класс PaymentNotification, экземпляр которого можно получить с помощью статического метода SbpUtil.parseJson(String).

Для проверки подлинности уведомления существуют перегруженные статические методы SbpUtil.checkNotificationSignature. Примеры использования:

String jsonString = "...";
String apiSignature = "...";
String secretKey = "...";

boolean success = SbpUtil.checkNotificationSignature(jsonString, apiSignature, secretKey);

PaymentNotification notification = SbpUtil.parseJson(jsonString);
String apiSignature = "...";
String secretKey = "...";

boolean success = SbpUtil.checkNotificationSignature(notification, apiSignature, secretKey);

BigDecimal amount = ...;
String sbpMerchantId = "...";
String order = "...";
String paymentStatus = "...";
String transactionDate = "...";

String apiSignature = "...";
String secretKey = "...";

boolean success = SbpUtil.checkNotificationSignature(amount, 
                 	sbpMerchantId, 
                 	order,
                 	paymentStatus,
                 	transactionDate,
                 	apiSignature,
                 	secretKey);

Шпаргалка

Тип запроса	Вызываемый метод	Принимаемый класс	Возвращаемый класс
Регистрация QR-кода	`registerQR`	`QR`	`QRUrl`
Получение данных по зарегистрированному ранее QR-коду	`getQRInfo`	`QRId`	`QRUrl`
Получение информации по платежу	`getPaymentInfo`	`QRId`	`PaymentInfo`
Оформление возврата по платежу	`refundPayment`	`RefundInfo`	`RefundStatus`
Получение информации по возврату	`getRefundInfo`	`RefundId`	`RefundStatus`

Raiffeisen-DGTL/sbp-sdk-java

Java SDK для интеграции с API СБП

Содержание

Документация

Подключение

Использование

Регистрация QR-кода

Получение данных по зарегистрированному ранее QR-коду

Получение информации по платежу

Оформление возврата по платежу

Получение информации по возврату

Создание заказа

Получение данных по заказу

Отмена заказа

Оформление возврата по заказу

Получение статуса возврата заказа

Привязка NFC-метки

Обработка уведомлений

Шпаргалка