Cost+Docs

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 signature

3. Обработка на уебхука

// 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.apiKeyStringДа—
config.merchantIdStringДа—
config.baseUrlStringНеhttps://api.nopayn.co.uk
httpClientjava.net.http.HttpClientНеКлиент по подразбиране

client.createOrder(params): Order (suspend)

Създава поръчка чрез POST /v1/orders/.

ПараметърТипЗадължителенОписание
amountIntдаСума в ISO 4217 второстепенна единица на валутата (например центове за EUR)
currencyStringДаISO 4217 код (EUR, GBP, USD, NOK, SEK)
merchantOrderIdString?НеВаш вътрешен идентификатор на поръчка
descriptionString?НеОписание на поръчката
returnUrlString?НеПренасочване след успешно плащане
failureUrlString?НеПренасочване при отказ/изтичане/грешка
webhookUrlString?НеАсинхронни известия за промяна на статуса
localeString?НеЕзик на HPP (en-GB, de-DE, nl-NL и др.)
paymentMethodsList<String>?НеФилтриране на HPP методи
expirationPeriodString?Не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ДаТехническа грешка

Добри практики за уебхукове

  1. Винаги проверявайте чрез API — данните от уебхука съдържат само идентификатора на поръчката, никога статуса. verifyWebhook() на SDK-то прави това автоматично.
  2. Връщайте HTTP 200, за да потвърдите получаването. Всеки друг код задейства до 10 повторни опита (през 2 минути).
  3. Въведете резервен polling — за поръчки, по-стари от 10 минути, които не са достигнали финален статус, правете polling с getOrder() като мрежа за безопасност.
  4. Бъдете идемпотентни — може да получите един и същ уебхук многократно.

Тестови карти

Използвайте тези карти в тестов режим на Cost+ (sandbox уебсайт):

КартаНомерБележки
Visa (успех)4111 1111 1111 1111Произволен CVV
Mastercard (успех)5544 3300 0003 7Произволен CVV
Visa (отхвърлена)4111 1111 1111 1105Do Not Honor
Visa (недостатъчни средства)4111 1111 1111 1151Insufficient Funds

Използвайте произволна бъдеща дата на валидност и произволен 3-цифрен CVC.

Демо приложение

Демо приложение, базирано на Docker (Ktor), е включено в GitHub хранилището за тестване на пълния поток на плащане.

Поддръжка

Нуждаете се от помощ? Свържете се с нашия екип за поддръжка на support@costplus.io.

On this page