Java / Kotlin

Oficiālais Kotlin SDK Cost+ maksājumu vārtejai, pilnībā savietojams ar Java. Vienkāršo HPP (mitinātās maksājuma lapas) novirzīšanas plūsmu, HMAC datu parakstīšanu un webhook verifikāciju.

Funkcijas

Kotlin-first, Java-friendly — datu klases, korutīnas, null drošība; pilnībā izmantojams no Java
kotlinx.serialization — nav Gson/Jackson atkarības; automātiska snake_case/camelCase kartēšana
HMAC-SHA256 parakstu ģenerēšana un konstantā laika verifikācija
Webhook parsēšana + API bāzēta pasūtījuma verifikācija
Suspend funkcijas nebloķējošai IO caur Kotlin korutīnām
Injicējams HttpClient ērtai testēšanai ar viltus transportu
Mērķis Java 17+

Prasības

JDK 17 vai jaunāka versija
Cost+ tirgotāja konts — dashboard.costplus.io

Instalācija

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>

Ātrais sākums (Kotlin)

1. Inicializējiet klientu

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

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

2. Izveidojiet maksājumu un novirziet uz 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)  // Direct payment method URL
println(result.signature)   // HMAC-SHA256 signature

3. Apstrādājiet 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
}

Ātrais sākums (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 atsauce

`NoPaynClient(config, httpClient?)`

Parametrs	Tips	Obligāts	Noklusējums
`config.apiKey`	`String`	Jā	—
`config.merchantId`	`String`	Jā	—
`config.baseUrl`	`String`	Nē	`https://api.nopayn.co.uk`
`httpClient`	`java.net.http.HttpClient`	Nē	Noklusējuma klients

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

Izveido pasūtījumu caur POST /v1/orders/.

Parametrs	Tips	Obligāts	Apraksts
`amount`	`Int`	Jā	Summa mazākajā valūtas vienībā (centos)
`currency`	`String`	Jā	ISO 4217 kods (`EUR`, `GBP`, `USD`, `NOK`, `SEK`)
`merchantOrderId`	`String?`	Nē	Jūsu iekšējā pasūtījuma atsauce
`description`	`String?`	Nē	Pasūtījuma apraksts
`returnUrl`	`String?`	Nē	Novirzīšana pēc veiksmīga maksājuma
`failureUrl`	`String?`	Nē	Novirzīšana atcelšanas/termiņa beigšanās/kļūdas gadījumā
`webhookUrl`	`String?`	Nē	Asinhroniem statusa izmaiņu paziņojumiem
`locale`	`String?`	Nē	HPP valoda (`en-GB`, `de-DE`, `nl-NL` utt.)
`paymentMethods`	`List<String>?`	Nē	Filtrēt HPP metodes
`expirationPeriod`	`String?`	Nē	ISO 8601 ilgums (`PT30M`)

Pieejamās maksājumu metodes: credit-card, apple-pay, google-pay, vipps-mobilepay

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

Iegūst pasūtījuma datus caur GET /v1/orders/{id}/.

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

Veic pilnu vai daļēju atmaksu caur POST /v1/orders/{id}/refunds/.

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

Ērtuma metode, kas izveido pasūtījumu un atgriež:

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`

Ģenerē HMAC-SHA256 heksadecimālo parakstu. Kanoniskais ziņojums ir $amount:$currency:$orderId, parakstīts ar API atslēgu.

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

Konstantā laika HMAC-SHA256 paraksta verifikācija.

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

Parsē webhook saturu, tad izsauc GET /v1/orders/{id}/, lai verificētu faktisko statusu.

Atsevišķās HMAC utilītas

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)

No Java:

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

Kļūdu apstrāde

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
}

Pasūtījumu statusi

Statuss	Galīgs?	Apraksts
`new`	Nē	Pasūtījums izveidots
`processing`	Nē	Maksājums procesā
`completed`	Jā	Maksājums veiksmīgs — piegādājiet preci
`cancelled`	Jā	Maksājums atcelts klienta
`expired`	Jā	Maksājuma saites termiņš beidzies
`error`	Jā	Tehniska kļūme

Webhook labākā prakse

Vienmēr verificējiet caur API — webhook saturs satur tikai pasūtījuma ID, nekad statusu. SDK verifyWebhook() to dara automātiski.
Atgrieziet HTTP 200, lai apstiprinātu saņemšanu. Jebkurš cits kods izsauc līdz 10 atkārtojumiem (2 minūtes starpā).
Ieviesiet rezerves aptaujātāju — pasūtījumiem, kas vecāki par 10 minūtēm un nav sasnieguši galīgo statusu, aptaujājiet getOrder() kā drošības tīklu.
Esiet idempotents — jūs varat saņemt vienu un to pašu webhook vairākas reizes.

Testa kartes

Izmantojiet šīs kartes Cost+ testa režīmā (sandbox vietne):

Karte	Numurs	Piezīmes
Visa (veiksmīgs)	`4111 1111 1111 1111`	Jebkurš CVV
Mastercard (veiksmīgs)	`5544 3300 0003 7`	Jebkurš CVV
Visa (noraidīts)	`4111 1111 1111 1105`	Do Not Honor
Visa (nepietiekami līdzekļi)	`4111 1111 1111 1151`	Insufficient Funds

Izmantojiet jebkuru nākotnes derīguma termiņu un jebkuru 3 ciparu CVC.

Demo lietotne

Docker bāzēta demo lietotne (Ktor) ir iekļauta GitHub repozitorijā pilnas maksājumu plūsmas testēšanai.

Atbalsts

Nepieciešama palīdzība? Sazinieties ar mūsu atbalsta komandu: support@costplus.io.

On this page