Java / Kotlin
Oficialne Kotlin/Java SDK pre platobnu branu Cost+
Oficialne Kotlin SDK pre platobnu branu Cost+, plne interoperabilne s Javou. Zjednodusuje proces presmerovania HPP (Hosted Payment Page), HMAC podpisovanie payloadov a overovanie webhookov.
Funkcie
- Kotlin-first, Java-friendly -- data classes, korutiny, null safety; plne pouzitelne z Javy
- kotlinx.serialization -- ziadna Gson/Jackson zavislost; automaticke mapovanie snake_case/camelCase
- HMAC-SHA256 generovanie podpisov a overovanie v konstantnom case
- Parsovanie webhookov + overovanie objednavok na zaklade API
- Suspend funkcie pre neblokujuce IO cez Kotlin korutiny
- Injektovatelny
HttpClientpre jednoduche testovanie s mock transportmi - Cieli na Java 17+
Poziadavky
- JDK 17 alebo novsi
- Ucet obchodnika Cost+ -- dashboard.costplus.io
Instalacia
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>Rychly start (Kotlin)
1. Inicializacia klienta
import io.nopayn.*
import kotlinx.coroutines.runBlocking
fun main() = runBlocking {
val nopayn = NoPaynClient(
NoPaynConfig(
apiKey = "your-api-key",
merchantId = "your-project",
)
)
}2. Vytvorenie platby a presmerovanie na HPP
val result = nopayn.generatePaymentUrl(
CreateOrderParams(
amount = 1295, // €12,95 v centoch
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) // Priama platobna URL
println(result.signature) // HMAC-SHA256 podpis3. Spracovanie webhooku
// Vo vasom HTTP handleri (Ktor, Spring, atd.)
val rawBody: String = request.body()
val verified = nopayn.verifyWebhook(rawBody)
println(verified.order.status) // "completed", "cancelled", atd.
println(verified.isFinal) // true, ked sa objednavka uz nezmeni
if (verified.order.status == "completed") {
// Vybavte objednavku
}Rychly start (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());
// Nastroje na podpisy funguju synchronne
String sig = client.generateSignature(1295, "EUR", order.getId());
boolean valid = client.verifySignature(1295, "EUR", order.getId(), sig);
}
}API referencia
NoPaynClient(config, httpClient?)
| Parameter | Typ | Povinne | Predvolene |
|---|---|---|---|
config.apiKey | String | Ano | -- |
config.merchantId | String | Ano | -- |
config.baseUrl | String | Nie | https://api.nopayn.co.uk |
httpClient | java.net.http.HttpClient | Nie | Predvoleny klient |
client.createOrder(params): Order (suspend)
Vytvori objednavku cez POST /v1/orders/.
| Parameter | Typ | Povinne | Popis |
|---|---|---|---|
amount | Int | áno | Suma v menovej jednotke ISO 4217 meny (napríklad centy pre EUR) |
currency | String | Ano | ISO 4217 kod (EUR, GBP, USD, NOK, SEK) |
merchantOrderId | String? | Nie | Vasa interna referencia objednavky |
description | String? | Nie | Popis objednavky |
returnUrl | String? | Nie | Presmerovanie po uspesnej platbe |
failureUrl | String? | Nie | Presmerovanie pri zruseni/exspiracii/chybe |
webhookUrl | String? | Nie | Asynchronne notifikacie o zmene stavu |
locale | String? | Nie | Jazyk HPP (en-GB, de-DE, nl-NL, atd.) |
paymentMethods | List<String>? | Nie | Filter platobnych metod HPP |
expirationPeriod | String? | Nie | ISO 8601 trvanie (PT30M) |
Dostupne platobne metody: credit-card, apple-pay, google-pay, vipps-mobilepay
client.getOrder(orderId): Order (suspend)
Ziskanie podrobnosti objednavky cez GET /v1/orders/{id}/.
client.createRefund(orderId, amount, description?): Refund (suspend)
Vydanie uplneho alebo ciastocneho vratenia cez POST /v1/orders/{id}/refunds/.
client.generatePaymentUrl(params): PaymentUrlResult (suspend)
Pomocna metoda, ktora vytvori objednavku a vrati:
PaymentUrlResult(
orderId: String, // NoPayn UUID objednavky
orderUrl: String, // HPP URL
paymentUrl: String?, // Priama platobna URL (prva transakcia)
signature: String, // HMAC-SHA256 z amount:currency:orderId
order: Order, // Uplny objekt objednavky
)client.generateSignature(amount, currency, orderId): String
Generuje HMAC-SHA256 hex podpis. Kanonicka sprava je $amount:$currency:$orderId, podpisana API klucom.
client.verifySignature(amount, currency, orderId, signature): Boolean
Overovanie HMAC-SHA256 podpisu v konstantnom case.
client.verifyWebhook(rawBody): VerifiedWebhook (suspend)
Parsuje telo webhooku, potom vola GET /v1/orders/{id}/ na overenie skutocneho stavu.
Samostatne HMAC nastroje
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)Z Javy:
String sig = NoPaynSignature.generate("your-api-key", 1295, "EUR", "order-uuid");
boolean ok = NoPaynSignature.verify("your-api-key", 1295, "EUR", "order-uuid", sig);Spracovanie chyb
import io.nopayn.*
try {
nopayn.createOrder(CreateOrderParams(amount = 100, currency = "EUR"))
} catch (e: ApiException) {
println(e.statusCode) // 401, 400, atd.
println(e.errorBody) // Surova API chybova odpoved
} catch (e: NoPaynException) {
println(e.message) // Sietova alebo parsovania chyba
}Stavy objednavok
| Stav | Koncovy? | Popis |
|---|---|---|
new | Nie | Objednavka vytvorena |
processing | Nie | Platba prebieha |
completed | Ano | Platba uspesna -- doructe tovar |
cancelled | Ano | Platba zrusena zakaznikom |
expired | Ano | Platobny odkaz vyprsal |
error | Ano | Technicka chyba |
Osvedcene postupy pre webhooky
- Vzdy overujte cez API -- payload webhooku obsahuje len ID objednavky, nikdy nie stav. SDK
verifyWebhook()to robi automaticky. - Vracajte HTTP 200 na potvrdenie prijatia. Akykolvek iny kod spusti az 10 opakovanych pokusov (2 minuty od seba).
- Implementujte zalohu dotazovanie -- pre objednavky starsie ako 10 minut, ktore nedosiahli konecny stav, dotazujte
getOrder()ako bezpecnostnu siet. - Budte idempotentni -- ten isty webhook mozete prijat viackrat.
Testovacie karty
Pouzite tieto karty v testovacom rezime Cost+ (sandbox webova stranka):
| Karta | Cislo | Poznamky |
|---|---|---|
| Visa (uspech) | 4111 1111 1111 1111 | Akekolvek CVV |
| Mastercard (uspech) | 5544 3300 0003 7 | Akekolvek CVV |
| Visa (zamietnutie) | 4111 1111 1111 1105 | Do Not Honor |
| Visa (nedostatok prostriedkov) | 4111 1111 1111 1151 | Insufficient Funds |
Pouzite akykolvek buduci datum exspiracie a akykolvek 3-ciselny CVC.
Demo aplikacia
Demo aplikacia na baze Dockeru (Ktor) je zahrnuta v GitHub repozitari na testovanie uplneho platobneho procesu.
Podpora
Potrebujete pomoc? Kontaktujte nas tym podpory na support@costplus.io.