Cost+Docs

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 HttpClient pre jednoduche testovanie s mock transportmi
  • Cieli na Java 17+

Poziadavky

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 podpis

3. 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?)

ParameterTypPovinnePredvolene
config.apiKeyStringAno--
config.merchantIdStringAno--
config.baseUrlStringNiehttps://api.nopayn.co.uk
httpClientjava.net.http.HttpClientNiePredvoleny klient

client.createOrder(params): Order (suspend)

Vytvori objednavku cez POST /v1/orders/.

ParameterTypPovinnePopis
amountIntánoSuma v menovej jednotke ISO 4217 meny (napríklad centy pre EUR)
currencyStringAnoISO 4217 kod (EUR, GBP, USD, NOK, SEK)
merchantOrderIdString?NieVasa interna referencia objednavky
descriptionString?NiePopis objednavky
returnUrlString?NiePresmerovanie po uspesnej platbe
failureUrlString?NiePresmerovanie pri zruseni/exspiracii/chybe
webhookUrlString?NieAsynchronne notifikacie o zmene stavu
localeString?NieJazyk HPP (en-GB, de-DE, nl-NL, atd.)
paymentMethodsList<String>?NieFilter platobnych metod HPP
expirationPeriodString?NieISO 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

StavKoncovy?Popis
newNieObjednavka vytvorena
processingNiePlatba prebieha
completedAnoPlatba uspesna -- doructe tovar
cancelledAnoPlatba zrusena zakaznikom
expiredAnoPlatobny odkaz vyprsal
errorAnoTechnicka chyba

Osvedcene postupy pre webhooky

  1. Vzdy overujte cez API -- payload webhooku obsahuje len ID objednavky, nikdy nie stav. SDK verifyWebhook() to robi automaticky.
  2. Vracajte HTTP 200 na potvrdenie prijatia. Akykolvek iny kod spusti az 10 opakovanych pokusov (2 minuty od seba).
  3. Implementujte zalohu dotazovanie -- pre objednavky starsie ako 10 minut, ktore nedosiahli konecny stav, dotazujte getOrder() ako bezpecnostnu siet.
  4. Budte idempotentni -- ten isty webhook mozete prijat viackrat.

Testovacie karty

Pouzite tieto karty v testovacom rezime Cost+ (sandbox webova stranka):

KartaCisloPoznamky
Visa (uspech)4111 1111 1111 1111Akekolvek CVV
Mastercard (uspech)5544 3300 0003 7Akekolvek CVV
Visa (zamietnutie)4111 1111 1111 1105Do Not Honor
Visa (nedostatok prostriedkov)4111 1111 1111 1151Insufficient 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.

On this page