Java / Kotlin

Opinbert Kotlin SDK fyrir greiðslugátt Cost+, í celoti združljiv með Javo. Poenostavlja tok preusmeritve HPP (gostovane greiðslune strani), HMAC podpisovanje koristnih podatkov og staðfesting webhook-ov.

Eiginleikar

Kotlin-prvi, Java-prijazen — data classes, coroutines, null safety; í celoti uporaben iz Jave
kotlinx.serialization — brez odvisnosti od Gson/Jackson; samodejno preslikavanje snake_case/camelCase
HMAC-SHA256 býr tilnje podpisov og staðfesting með konstantnim časom
Razčlenjevanje webhook-ov + staðfesting pantana á osnovi API-ja
Suspend funkcije til neblokirajoči IO gegnum Kotlin coroutines
Vnosljiv HttpClient til enostavno testiranje með lažnimi transporti
Ciljno Java 17+

Kröfur

JDK 17 eða nýrri
Söluaðilareikningur Cost+ — dashboard.costplus.io

Uppsetning

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>

Flýtiræsing (Kotlin)

1. Frumstilltu biðlarann

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

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

2. Ustvarite greiðsla og preusmerite á HPP

val result = nopayn.generatePaymentUrl(
    CreateOrderParams(
        amount = 1295,            // €12.95 og 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 greiðslumátar
println(result.signature)   // HMAC-SHA256 podpis

3. Meðhöndlaðu webhook

// V þittm 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") {
    // Uppfylldu pöntunina
}

Flýtiræsing (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 til podpise delujejo sinhrono
        String sig = client.generateSignature(1295, "EUR", order.getId());
        boolean valid = client.verifySignature(1295, "EUR", order.getId(), sig);
    }
}

API tilvísun

`NoPaynClient(config, httpClient?)`

Parameter	Tip	Obvezno	Privzeto
`config.apiKey`	`String`	Da	—
`config.merchantId`	`String`	Da	—
`config.baseUrl`	`String`	Ne	`https://api.nopayn.co.uk`
`httpClient`	`java.net.http.HttpClient`	Ne	Privzeti odjemalec

`client.createOrder(params): Order` (suspend)

Stofnar pöntun gegnum POST /v1/orders/.

Parameter	Tip	Obvezno	Opis
`amount`	`Int`	Da	Znesek í najmanjši valutni enoti (centi)
`currency`	`String`	Da	Koda ISO 4217 (`EUR`, `GBP`, `USD`, `NOK`, `SEK`)
`merchantOrderId`	`String?`	Ne	Vaša interna referenca pantanir
`description`	`String?`	Ne	Opis pantanir
`returnUrl`	`String?`	Ne	Preusmeritev eftir uspešnem greiðsluu
`failureUrl`	`String?`	Ne	Preusmeritev ob preklicu/poteku/napaki
`webhookUrl`	`String?`	Ne	Asinhrona obvestila o spremembi statusa
`locale`	`String?`	Ne	Jezik HPP (`en-GB`, `de-DE`, `nl-NL` itd.)
`paymentMethods`	`List<String>?`	Ne	Filtriraj metode HPP
`expirationPeriod`	`String?`	Ne	Trajanje ISO 8601 (`PT30M`)

Tiltækir greiðslumátar: credit-card, apple-pay, google-pay, vipps-mobilepay

`client.getOrder(orderId): Order` (suspend)

Sækir upplýsingar pöntunar gegnum GET /v1/orders/{id}/.

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

Gefðu út fulla eða hluta endurgreiðslu gegnum POST /v1/orders/{id}/refunds/.

`client.generatePaymentUrl(params): PaymentUrlResult` (suspend)

Þægileg aðferð, ki ustvari pöntun og vrne:

PaymentUrlResult(
    orderId: String,     // NoPayn UUID pantanir
    orderUrl: String,    // HPP URL
    paymentUrl: String?, // Neposredni greiðsluni URL (prva transakcija)
    signature: String,   // HMAC-SHA256 od amount:currency:orderId
    order: Order,        // Celoten objekt pantanir
)

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

Býr til HMAC-SHA256 šestnajstiški podpis. Kanonično sporočilo er $amount:$currency:$orderId, podpisano með API lykillem.

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

Staðfesting HMAC-SHA256 podpisa með konstantnim časom.

`client.verifyWebhook(rawBody): VerifiedWebhook` (suspend)

Greinir telo webhook-a, nato poklief GET /v1/orders/{id}/ til staðfesting dejanskega statusa.

Sjálfstæð HMAC tól

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);

Villum meðhöndlun

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 pantana

Status	Končni?	Opis
`new`	Ne	Pöntun ustvarjeno
`processing`	Ne	Greiðsla í teku
`completed`	Da	Greiðsla uspešno — dostavite blago
`cancelled`	Da	Greiðsla preklicano með strani viðskiptavinar
`expired`	Da	Plačilna povezava er potekla
`error`	Da	Tehnična napaka

Bestu venjur fyrir webhook-a

Vedno preverite gegnum API-ja — koristni podatki webhook-a vsebujejo aðeins ID pantanir, nikoli statusa. SDK-jev verifyWebhook() to naredi samodejno.
Vrnite HTTP 200 til potrditev prejema. Katerakoli druga koda sproži do 10 ponovnih poskusov (2 minuti narazen).
Implementirajte rezervno poizvedovanje — til pantanir, starejša od 10 minut, ki še niso dosegla končnega statusa, poizvedujte getOrder() kot varnostno mrežo.
Vertu idempotent — isti webhook lahþegar prejmete večkrat.

Prófunarkort

Uporabite te kartice í testnem načinu Cost+ (vefsíðu sandboxa):

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

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

Sýnisforrit

Sýnisforrit á osnovi Docker (Ktor) er vključena í GitHub repozitorij til testiranje celotnega greiðslunega toka.

Aðstoð

Þarftu aðstoð? Hafðu samband við þjónustudeild okkar á support@costplus.io.

On this page