Java / Kotlin

Virallinen Kotlin SDK Cost+-maksuportille, täysin yhteensopiva Javan kanssa. Yksinkertaistaa HPP (isännöidyn maksusivun) uudelleenohjausta, HMAC-allekirjoitusta ja webhook-vahvistusta.

Ominaisuudet

Kotlin-ensisijainen, Java-ystävällinen — dataluokat, korutiinit, null-turvallisuus; täysin käytettävissä Javasta
kotlinx.serialization — ei Gson/Jackson-riippuvuutta; automaattinen snake_case/camelCase-muunnos
HMAC-SHA256-allekirjoituksen luonti ja vakioaikainen vahvistus
Webhook-jäsennys + API-pohjainen tilauksen vahvistus
Suspend-funktiot estämättömään IO:hon Kotlin-korutiinien kautta
Injektoitava HttpClient helppoa testausta varten mock-transporteilla
Kohdistaa Java 17+:aan

Vaatimukset

JDK 17 tai uudempi
Cost+-kauppiastili — dashboard.costplus.io

Asennus

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>

Pikaopas (Kotlin)

1. Alusta asiakas

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

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

2. Luo maksu ja ohjaa HPP:hen

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. Käsittele webhook

// 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
}

Pikaopas (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-viite

`NoPaynClient(config, httpClient?)`

Parametri	Tyyppi	Pakollinen	Oletus
`config.apiKey`	`String`	Kyllä	—
`config.merchantId`	`String`	Kyllä	—
`config.baseUrl`	`String`	Ei	`https://api.nopayn.co.uk`
`httpClient`	`java.net.http.HttpClient`	Ei	Oletusasiakas

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

Luo tilauksen kutsulla POST /v1/orders/.

Parametri	Tyyppi	Pakollinen	Kuvaus
`amount`	`Int`	Kyllä	Summa pienimmässä valuuttayksikössä (senteissä)
`currency`	`String`	Kyllä	ISO 4217 -koodi (`EUR`, `GBP`, `USD`, `NOK`, `SEK`)
`merchantOrderId`	`String?`	Ei	Oma sisäinen tilausviitteesi
`description`	`String?`	Ei	Tilauksen kuvaus
`returnUrl`	`String?`	Ei	Uudelleenohjaus onnistuneen maksun jälkeen
`failureUrl`	`String?`	Ei	Uudelleenohjaus peruutuksen/vanhenemisen/virheen yhteydessä
`webhookUrl`	`String?`	Ei	Asynkroniset tilanmuutosilmoitukset
`locale`	`String?`	Ei	HPP:n kieli (`en-GB`, `de-DE`, `nl-NL` jne.)
`paymentMethods`	`List<String>?`	Ei	Suodata HPP:n maksutapoja
`expirationPeriod`	`String?`	Ei	ISO 8601 -kesto (`PT30M`)

Käytettävissä olevat maksutavat: credit-card, apple-pay, google-pay, vipps-mobilepay

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

Hakee tilauksen tiedot kutsulla GET /v1/orders/{id}/.

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

Tekee täyden tai osittaisen palautuksen kutsulla POST /v1/orders/{id}/refunds/.

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

Apumetodi, joka luo tilauksen ja palauttaa:

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`

Luo HMAC-SHA256 hex-allekirjoituksen. Kanoninen viesti on $amount:$currency:$orderId, allekirjoitettu API-avaimella.

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

Vakioaikainen HMAC-SHA256-allekirjoituksen vahvistus.

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

Jäsentää webhook-rungon ja kutsuu sitten GET /v1/orders/{id}/ varmistaakseen todellisen tilan.

Erilliset HMAC-apufunktiot

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)

Javasta:

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

Virheenkäsittely

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
}

Tilausten tilat

Tila	Lopullinen?	Kuvaus
`new`	Ei	Tilaus luotu
`processing`	Ei	Maksu käynnissä
`completed`	Kyllä	Maksu onnistui — toimita tavarat
`cancelled`	Kyllä	Asiakas peruutti maksun
`expired`	Kyllä	Maksulinkki vanheni
`error`	Kyllä	Tekninen virhe

Webhook-parhaat käytännöt

Vahvista aina API:n kautta — webhook-data sisältää vain tilauksen tunnisteen, ei koskaan tilaa. SDK:n verifyWebhook() tekee tämän automaattisesti.
Palauta HTTP 200 kuittauksena. Mikä tahansa muu koodi käynnistää enintään 10 uudelleenyritystä (2 minuutin välein).
Toteuta varapolleri — yli 10 minuuttia vanhoille tilauksille, jotka eivät ole saavuttaneet lopullista tilaa, pollaa getOrder() turvavarana.
Ole idempotentti — saatat vastaanottaa saman webhookin useita kertoja.

Testikortit

Käytä näitä kortteja Cost+:n testitilassa (sandbox-verkkosivusto):

Kortti	Numero	Huomautukset
Visa (onnistunut)	`4111 1111 1111 1111`	Mikä tahansa CVV
Mastercard (onnistunut)	`5544 3300 0003 7`	Mikä tahansa CVV
Visa (hylätty)	`4111 1111 1111 1105`	Do Not Honor
Visa (riittämätön kate)	`4111 1111 1111 1151`	Insufficient Funds

Käytä mitä tahansa tulevaa voimassaolopäivää ja mitä tahansa 3-numeroista CVC:tä.

Demosovellus

Docker-pohjainen demosovellus (Ktor) sisältyy GitHub-tietovarastoon täyden maksukulun testaamiseksi.

Tuki

Tarvitsetko apua? Ota yhteyttä tukitiimiimme osoitteessa support@costplus.io.

On this page