Cost+Docs

Java / Kotlin

Uradni Kotlin/Java SDK za plačilni prehod Cost+

Uradni Kotlin SDK za plačilni prehod Cost+, v celoti združljiv z Javo. Poenostavlja tok preusmeritve HPP (gostovane plačilne strani), HMAC podpisovanje koristnih podatkov in preverjanje webhook-ov.

Lastnosti

  • Kotlin-prvi, Java-prijazen — data classes, coroutines, null safety; v celoti uporaben iz Jave
  • kotlinx.serialization — brez odvisnosti od Gson/Jackson; samodejno preslikavanje snake_case/camelCase
  • HMAC-SHA256 generiranje podpisov in preverjanje s konstantnim časom
  • Razčlenjevanje webhook-ov + preverjanje naročil na osnovi API-ja
  • Suspend funkcije za neblokirajoči IO prek Kotlin coroutines
  • Vnosljiv HttpClient za enostavno testiranje z lažnimi transporti
  • Ciljno Java 17+

Zahteve

Namestitev

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>

Hitri začetek (Kotlin)

1. Inicializirajte odjemalca

import io.nopayn.*
import kotlinx.coroutines.runBlocking

fun main() = runBlocking {
    val nopayn = NoPaynClient(
        NoPaynConfig(
            apiKey = "your-api-key",
            merchantId = "your-project",
        )
    )
}

2. Ustvarite plačilo in preusmerite na 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)  // Neposredni URL plačilne metode
println(result.signature)   // HMAC-SHA256 podpis

3. Obdelajte webhook

// V vašem HTTP obdelovalcu (Ktor, Spring itd.)
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") {
    // Izpolnite naročilo
}

Hitri začetek (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());

        // Pripomočki za podpise delujejo sinhrono
        String sig = client.generateSignature(1295, "EUR", order.getId());
        boolean valid = client.verifySignature(1295, "EUR", order.getId(), sig);
    }
}

API referenca

NoPaynClient(config, httpClient?)

ParameterTipObveznoPrivzeto
config.apiKeyStringDa—
config.merchantIdStringDa—
config.baseUrlStringNehttps://api.nopayn.co.uk
httpClientjava.net.http.HttpClientNePrivzeti odjemalec

client.createOrder(params): Order (suspend)

Ustvari naročilo prek POST /v1/orders/.

ParameterTipObveznoOpis
amountIntjaZnesek v manjši enoti ISO 4217 valute (na primer centi za EUR)
currencyStringDaKoda ISO 4217 (EUR, GBP, USD, NOK, SEK)
merchantOrderIdString?NeVaša interna referenca naročila
descriptionString?NeOpis naročila
returnUrlString?NePreusmeritev po uspešnem plačilu
failureUrlString?NePreusmeritev ob preklicu/poteku/napaki
webhookUrlString?NeAsinhrona obvestila o spremembi statusa
localeString?NeJezik HPP (en-GB, de-DE, nl-NL itd.)
paymentMethodsList<String>?NeFiltriraj metode HPP
expirationPeriodString?NeTrajanje ISO 8601 (PT30M)

Razpoložljive plačilne metode: credit-card, apple-pay, google-pay, vipps-mobilepay

client.getOrder(orderId): Order (suspend)

Pridobi podrobnosti naročila prek GET /v1/orders/{id}/.

client.createRefund(orderId, amount, description?): Refund (suspend)

Izda celotno ali delno vračilo prek POST /v1/orders/{id}/refunds/.

client.generatePaymentUrl(params): PaymentUrlResult (suspend)

Priročna metoda, ki ustvari naročilo in vrne:

PaymentUrlResult(
    orderId: String,     // NoPayn UUID naročila
    orderUrl: String,    // HPP URL
    paymentUrl: String?, // Neposredni plačilni URL (prva transakcija)
    signature: String,   // HMAC-SHA256 od amount:currency:orderId
    order: Order,        // Celoten objekt naročila
)

client.generateSignature(amount, currency, orderId): String

Generira HMAC-SHA256 šestnajstiški podpis. Kanonično sporočilo je $amount:$currency:$orderId, podpisano z API ključem.

client.verifySignature(amount, currency, orderId, signature): Boolean

Preverjanje HMAC-SHA256 podpisa s konstantnim časom.

client.verifyWebhook(rawBody): VerifiedWebhook (suspend)

Razčleni telo webhook-a, nato pokliče GET /v1/orders/{id}/ za preverjanje dejanskega statusa.

Samostojne HMAC pripomočke

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)

Iz Jave:

String sig = NoPaynSignature.generate("your-api-key", 1295, "EUR", "order-uuid");
boolean ok = NoPaynSignature.verify("your-api-key", 1295, "EUR", "order-uuid", sig);

Obravnava napak

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
}

Statusi naročil

StatusKončni?Opis
newNeNaročilo ustvarjeno
processingNePlačilo v teku
completedDaPlačilo uspešno — dostavite blago
cancelledDaPlačilo preklicano s strani stranke
expiredDaPlačilna povezava je potekla
errorDaTehnična napaka

Najboljše prakse za webhook-e

  1. Vedno preverite prek API-ja — koristni podatki webhook-a vsebujejo samo ID naročila, nikoli statusa. SDK-jev verifyWebhook() to naredi samodejno.
  2. Vrnite HTTP 200 za potrditev prejema. Katerakoli druga koda sproži do 10 ponovnih poskusov (2 minuti narazen).
  3. Implementirajte rezervno poizvedovanje — za naročila, starejša od 10 minut, ki še niso dosegla končnega statusa, poizvedujte getOrder() kot varnostno mrežo.
  4. Bodite idempotentni — isti webhook lahko prejmete večkrat.

Testne kartice

Uporabite te kartice v testnem načinu Cost+ (spletno mesto peskovnika):

KarticaŠtevilkaOpombe
Visa (uspeh)4111 1111 1111 1111Katerikoli CVV
Mastercard (uspeh)5544 3300 0003 7Katerikoli CVV
Visa (zavrnjena)4111 1111 1111 1105Zavrnitev
Visa (nezadostna sredstva)4111 1111 1111 1151Nezadostna sredstva

Uporabite katerikoli prihodnji datum veljavnosti in katerokoli 3-mestno CVC kodo.

Predstavitvena aplikacija

Predstavitvena aplikacija na osnovi Docker (Ktor) je vključena v GitHub repozitorij za testiranje celotnega plačilnega toka.

Podpora

Potrebujete pomoč? Obrnite se na našo ekipo za podporo na support@costplus.io.

On this page