Java / Kotlin

Ametlik Kotlin SDK Cost+ makselüüsi jaoks, täielikult ühilduv Java-ga. Lihtsustab HPP (hostitud makselehe) ümbersuunamise voogu, HMAC andmete allkirjastamist ja veebihaagi kontrollimist.

Funktsioonid

Kotlin-esmane, Java-sõbralik — andmeklassid, korutiinid, null-turvalisus; täielikult kasutatav Java-st
kotlinx.serialization — ei sõltu Gsonist/Jacksonist; automaatne snake_case/camelCase vastendamine
HMAC-SHA256 allkirja genereerimine ja konstantse aja kontrollimine
Veebihaagi parsimine + API-põhine tellimuse kontrollimine
Suspend-funktsioonid mitteblokeerivaks IO-ks Kotlini korutiinide kaudu
Süstitav HttpClient lihtsaks testimiseks mock-transpordiga
Sihtplatvorm Java 17+

Nõuded

JDK 17 või uuem
Cost+ kaupmehe konto — dashboard.costplus.io

Paigaldamine

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>

Kiirstart (Kotlin)

1. Kliendi initsialiseerimine

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

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

2. Makse loomine ja HPP-le suunamine

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. Veebihaagi käsitlemine

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

Kiirstart (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 viide

`NoPaynClient(config, httpClient?)`

Parameeter	Tüüp	Kohustuslik	Vaikeväärtus
`config.apiKey`	`String`	Jah	—
`config.merchantId`	`String`	Jah	—
`config.baseUrl`	`String`	Ei	`https://api.nopayn.co.uk`
`httpClient`	`java.net.http.HttpClient`	Ei	Vaikeklient

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

Loob tellimuse päringuga POST /v1/orders/.

Parameeter	Tüüp	Kohustuslik	Kirjeldus
`amount`	`Int`	Jah	Summa väikseimas valuutaühikus (sendid)
`currency`	`String`	Jah	ISO 4217 kood (`EUR`, `GBP`, `USD`, `NOK`, `SEK`)
`merchantOrderId`	`String?`	Ei	Teie sisemine tellimuse viide
`description`	`String?`	Ei	Tellimuse kirjeldus
`returnUrl`	`String?`	Ei	Ümbersuunamine pärast edukat makset
`failureUrl`	`String?`	Ei	Ümbersuunamine tühistamise/aegumise/vea korral
`webhookUrl`	`String?`	Ei	Asünkroonsed olekumuutuse teavitused
`locale`	`String?`	Ei	HPP keel (`en-GB`, `de-DE`, `nl-NL` jne)
`paymentMethods`	`List<String>?`	Ei	HPP meetodite filtreerimine
`expirationPeriod`	`String?`	Ei	ISO 8601 kestvus (`PT30M`)

Saadaolevad makseviisid: credit-card, apple-pay, google-pay, vipps-mobilepay

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

Pärib tellimuse üksikasjad päringuga GET /v1/orders/{id}/.

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

Teeb täieliku või osalise tagasimakse päringuga POST /v1/orders/{id}/refunds/.

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

Abimeetod, mis loob tellimuse ja tagastab:

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`

Genereerib HMAC-SHA256 hex allkirja. Kanoniline sõnum on $amount:$currency:$orderId, allkirjastatud API võtmega.

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

Konstantse aja HMAC-SHA256 allkirja kontrollimine.

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

Parsib veebihaagi keha, seejärel kutsub GET /v1/orders/{id}/, et kontrollida tegelikku olekut.

Eraldiseisvad HMAC utiliidid

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)

Java-st:

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

Veakäsitlus

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
}

Tellimuse olekud

Olek	Lõplik?	Kirjeldus
`new`	Ei	Tellimus loodud
`processing`	Ei	Makse pooleli
`completed`	Jah	Makse edukas — tarnige kaup
`cancelled`	Jah	Makse tühistatud kliendi poolt
`expired`	Jah	Makselink aegunud
`error`	Jah	Tehniline tõrge

Veebihaagi parimad tavad

Kontrollige alati API kaudu — veebihaagi andmed sisaldavad ainult tellimuse ID-d, mitte kunagi olekut. SDK verifyWebhook() teeb seda automaatselt.
Tagastage HTTP 200 kättesaamise kinnitamiseks. Iga muu kood käivitab kuni 10 korduskatset (2 minuti vahega).
Rakendage varuküsitleja — tellimuste jaoks, mis on vanemad kui 10 minutit ja pole jõudnud lõppolekusse, küsitlege getOrder() turvavõrguna.
Olge idempotentne — võite sama veebihaagi saada mitu korda.

Testkaardid

Kasutage neid kaarte Cost+ testrežiimis (liivakasti veebileht):

Kaart	Number	Märkused
Visa (edukas)	`4111 1111 1111 1111`	Suvaline CVV
Mastercard (edukas)	`5544 3300 0003 7`	Suvaline CVV
Visa (keeldutud)	`4111 1111 1111 1105`	Do Not Honor
Visa (ebapiisav saldo)	`4111 1111 1111 1151`	Insufficient Funds

Kasutage suvalist tulevast aegumiskuupäeva ja suvalist 3-kohalist CVC-d.

Demorakendus

Dockeri-põhine demorakendus (Ktor) on kaasas GitHub hoidlas täieliku maksevoo testimiseks.

Tugi

Vajate abi? Võtke ühendust meie tugimeeskonnaga aadressil support@costplus.io.

On this page