Java / Kotlin
Официално Kotlin/Java SDK за разплащателния шлюз Cost+
Официално Kotlin SDK за разплащателния шлюз Cost+, напълно съвместимо с Java. Опростява потока за пренасочване към HPP (хоствана страница за плащане), HMAC подписването на данни и верификацията на уебхукове.
Характеристики
- Kotlin-first, Java-friendly — data classes, coroutines, null safety; напълно използваемо от Java
- kotlinx.serialization — без зависимост от Gson/Jackson; автоматично съответствие snake_case/camelCase
- HMAC-SHA256 генериране на подписи и верификация с постоянно време
- Анализиране на уебхукове + верификация на поръчки, базирана на API
- Suspend функции за неблокиращ IO чрез Kotlin coroutines
- Инжектируем
HttpClientза лесно тестване с мок транспорти - Целева платформа Java 17+
Изисквания
- JDK 17 или по-нова версия
- Търговски акаунт в Cost+ — dashboard.costplus.io
Инсталация
Gradle (Kotlin DSL)
dependencies {
implementation("io.nopayn:nopayn-sdk:1.0.0")
}Gradle (Groovy)
dependencies {
implementation 'io.nopayn:nopayn-sdk:1.0.0'
}Maven
<dependency>
<groupId>io.nopayn</groupId>
<artifactId>nopayn-sdk</artifactId>
<version>1.0.0</version>
</dependency>Бързо начало (Kotlin)
1. Инициализиране на клиента
import io.nopayn.*
import kotlinx.coroutines.runBlocking
fun main() = runBlocking {
val nopayn = NoPaynClient(
NoPaynConfig(
apiKey = "your-api-key",
merchantId = "your-project",
)
)
}2. Създаване на плащане и пренасочване към HPP
val result = nopayn.generatePaymentUrl(
CreateOrderParams(
amount = 1295, // €12.95 in cents
currency = "EUR",
merchantOrderId = "ORDER-001",
description = "Premium Widget",
returnUrl = "https://shop.example.com/success",
failureUrl = "https://shop.example.com/failure",
webhookUrl = "https://shop.example.com/webhook",
locale = "en-GB",
expirationPeriod = "PT30M",
)
)
println(result.orderUrl) // HPP URL
println(result.paymentUrl) // Direct payment method URL
println(result.signature) // HMAC-SHA256 signature3. Обработка на уебхука
// In your HTTP handler (Ktor, Spring, etc.)
val rawBody: String = request.body()
val verified = nopayn.verifyWebhook(rawBody)
println(verified.order.status) // "completed", "cancelled", etc.
println(verified.isFinal) // true when the order won't change
if (verified.order.status == "completed") {
// Fulfil the order
}Бързо начало (Java)
import io.nopayn.*;
import kotlinx.coroutines.BuildersKt;
import kotlinx.coroutines.Dispatchers;
public class Example {
public static void main(String[] args) throws Exception {
NoPaynClient client = new NoPaynClient(
new NoPaynConfig("your-api-key", "your-project", "https://api.nopayn.co.uk")
);
Order order = BuildersKt.runBlocking(
Dispatchers.getIO(),
(scope, continuation) -> client.createOrder(
new CreateOrderParams(
1295, "EUR", "ORDER-001", "Premium Widget",
"https://shop.example.com/success",
"https://shop.example.com/failure",
"https://shop.example.com/webhook",
"en-GB", null, "PT30M"
),
continuation
)
);
System.out.println("Order ID: " + order.getId());
System.out.println("Order URL: " + order.getOrderUrl());
// Signature utilities work synchronously
String sig = client.generateSignature(1295, "EUR", order.getId());
boolean valid = client.verifySignature(1295, "EUR", order.getId(), sig);
}
}API справочник
NoPaynClient(config, httpClient?)
| Параметър | Тип | Задължителен | По подразбиране |
|---|---|---|---|
config.apiKey | String | Да | — |
config.merchantId | String | Да | — |
config.baseUrl | String | Не | https://api.nopayn.co.uk |
httpClient | java.net.http.HttpClient | Не | Клиент по подразбиране |
client.createOrder(params): Order (suspend)
Създава поръчка чрез POST /v1/orders/.
| Параметър | Тип | Задължителен | Описание |
|---|---|---|---|
amount | Int | да | Сума в ISO 4217 второстепенна единица на валутата (например центове за EUR) |
currency | String | Да | ISO 4217 код (EUR, GBP, USD, NOK, SEK) |
merchantOrderId | String? | Не | Ваш вътрешен идентификатор на поръчка |
description | String? | Не | Описание на поръчката |
returnUrl | String? | Не | Пренасочване след успешно плащане |
failureUrl | String? | Не | Пренасочване при отказ/изтичане/грешка |
webhookUrl | String? | Не | Асинхронни известия за промяна на статуса |
locale | String? | Не | Език на HPP (en-GB, de-DE, nl-NL и др.) |
paymentMethods | List<String>? | Не | Филтриране на HPP методи |
expirationPeriod | String? | Не | ISO 8601 продължителност (PT30M) |
Налични методи на плащане: credit-card, apple-pay, google-pay, vipps-mobilepay
client.getOrder(orderId): Order (suspend)
Извлича детайли на поръчка чрез GET /v1/orders/{id}/.
client.createRefund(orderId, amount, description?): Refund (suspend)
Издава пълно или частично възстановяване чрез POST /v1/orders/{id}/refunds/.
client.generatePaymentUrl(params): PaymentUrlResult (suspend)
Удобен метод, който създава поръчка и връща:
PaymentUrlResult(
orderId: String, // NoPayn order UUID
orderUrl: String, // HPP URL
paymentUrl: String?, // Direct payment URL (first transaction)
signature: String, // HMAC-SHA256 of amount:currency:orderId
order: Order, // Full order object
)client.generateSignature(amount, currency, orderId): String
Генерира HMAC-SHA256 шестнадесетичен подпис. Каноничното съобщение е $amount:$currency:$orderId, подписано с API ключа.
client.verifySignature(amount, currency, orderId, signature): Boolean
Верификация с постоянно време на HMAC-SHA256 подпис.
client.verifyWebhook(rawBody): VerifiedWebhook (suspend)
Анализира тялото на уебхука, след което извиква GET /v1/orders/{id}/, за да провери действителния статус.
Самостоятелни HMAC помощни функции
import io.nopayn.NoPaynSignature
val sig = NoPaynSignature.generate("your-api-key", 1295, "EUR", "order-uuid")
val ok = NoPaynSignature.verify("your-api-key", 1295, "EUR", "order-uuid", sig)От Java:
String sig = NoPaynSignature.generate("your-api-key", 1295, "EUR", "order-uuid");
boolean ok = NoPaynSignature.verify("your-api-key", 1295, "EUR", "order-uuid", sig);Обработка на грешки
import io.nopayn.*
try {
nopayn.createOrder(CreateOrderParams(amount = 100, currency = "EUR"))
} catch (e: ApiException) {
println(e.statusCode) // 401, 400, etc.
println(e.errorBody) // Raw API error response
} catch (e: NoPaynException) {
println(e.message) // Network or parsing error
}Статуси на поръчки
| Статус | Финален? | Описание |
|---|---|---|
new | Не | Поръчката е създадена |
processing | Не | Плащането е в ход |
completed | Да | Плащането е успешно — доставете стоката |
cancelled | Да | Плащането е отменено от клиента |
expired | Да | Линкът за плащане е изтекъл |
error | Да | Техническа грешка |
Добри практики за уебхукове
- Винаги проверявайте чрез API — данните от уебхука съдържат само идентификатора на поръчката, никога статуса.
verifyWebhook()на SDK-то прави това автоматично. - Връщайте HTTP 200, за да потвърдите получаването. Всеки друг код задейства до 10 повторни опита (през 2 минути).
- Въведете резервен polling — за поръчки, по-стари от 10 минути, които не са достигнали финален статус, правете polling с
getOrder()като мрежа за безопасност. - Бъдете идемпотентни — може да получите един и същ уебхук многократно.
Тестови карти
Използвайте тези карти в тестов режим на Cost+ (sandbox уебсайт):
| Карта | Номер | Бележки |
|---|---|---|
| Visa (успех) | 4111 1111 1111 1111 | Произволен CVV |
| Mastercard (успех) | 5544 3300 0003 7 | Произволен CVV |
| Visa (отхвърлена) | 4111 1111 1111 1105 | Do Not Honor |
| Visa (недостатъчни средства) | 4111 1111 1111 1151 | Insufficient Funds |
Използвайте произволна бъдеща дата на валидност и произволен 3-цифрен CVC.
Демо приложение
Демо приложение, базирано на Docker (Ktor), е включено в GitHub хранилището за тестване на пълния поток на плащане.
Поддръжка
Нуждаете се от помощ? Свържете се с нашия екип за поддръжка на support@costplus.io.