Cost+Docs

Java / Kotlin

Službeni Kotlin/Java SDK za Cost+ platni pristupnik

Službeni Kotlin SDK za Cost+ platni pristupnik, potpuno interoperabilan s Javom. Pojednostavljuje tijek preusmjeravanja na HPP (hosted stranicu za plaćanje), HMAC potpisivanje podataka i verifikaciju webhookova.

Značajke

  • Kotlin-first, Java-friendly — data klase, korutine, null sigurnost; potpuno upotrebljiv iz Jave
  • kotlinx.serialization — bez Gson/Jackson ovisnosti; automatsko mapiranje snake_case/camelCase
  • HMAC-SHA256 generiranje potpisa i verifikacija konstantnim vremenom
  • Raščlamba webhookova + verifikacija narudžbe temeljena na API-ju
  • Suspend funkcije za neblokirajući IO putem Kotlin korutina
  • Injectirani HttpClient za jednostavno testiranje s mock transportima
  • Cilja Java 17+

Zahtjevi

Instalacija

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>

Brzi početak (Kotlin)

1. Inicijalizirajte klijent

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

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

2. Stvorite plaćanje i preusmjerite 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)  // Direct payment method URL
println(result.signature)   // HMAC-SHA256 signature

3. Obradite 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
}

Brzi početak (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 referenca

NoPaynClient(config, httpClient?)

ParametarTipObaveznoZadano
config.apiKeyStringDa—
config.merchantIdStringDa—
config.baseUrlStringNehttps://api.nopayn.co.uk
httpClientjava.net.http.HttpClientNeZadani klijent

client.createOrder(params): Order (suspend)

Stvara narudžbu putem POST /v1/orders/.

ParametarTipObaveznoOpis
amountIntDaIznos u manjoj jedinici ISO 4217 valute (na primjer, centi za EUR)
currencyStringDaISO 4217 kod (EUR, GBP, USD, NOK, SEK)
merchantOrderIdString?NeVaša interna referenca narudžbe
descriptionString?NeOpis narudžbe
returnUrlString?NePreusmjeravanje nakon uspješnog plaćanja
failureUrlString?NePreusmjeravanje pri poništenju/isteku/grešci
webhookUrlString?NeAsinkrone obavijesti o promjeni statusa
localeString?NeJezik HPP-a (en-GB, de-DE, nl-NL itd.)
paymentMethodsList<String>?NeFiltriranje HPP načina
expirationPeriodString?NeISO 8601 trajanje (PT30M)

Dostupni načini plaćanja: credit-card, apple-pay, google-pay, vipps-mobilepay

client.getOrder(orderId): Order (suspend)

Dohvaća detalje narudžbe putem GET /v1/orders/{id}/.

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

Izdaje potpuni ili djelomični povrat putem POST /v1/orders/{id}/refunds/.

client.generatePaymentUrl(params): PaymentUrlResult (suspend)

Praktična metoda koja stvara narudžbu i vraća:

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

Generira HMAC-SHA256 heksadecimalni potpis. Kanonska poruka je $amount:$currency:$orderId, potpisana API ključem.

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

Verifikacija HMAC-SHA256 potpisa konstantnim vremenom.

client.verifyWebhook(rawBody): VerifiedWebhook (suspend)

Raščlanjuje tijelo webhooka, zatim poziva GET /v1/orders/{id}/ za provjeru stvarnog statusa.

Samostalni HMAC alati

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

Rukovanje greškama

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 narudžbe

StatusKonačan?Opis
newNeNarudžba stvorena
processingNePlaćanje u tijeku
completedDaPlaćanje uspjelo — isporučite robu
cancelledDaPlaćanje poništeno od strane kupca
expiredDaPoveznica za plaćanje je istekla
errorDaTehnički kvar

Najbolje prakse za webhookove

  1. Uvijek provjerite putem API-ja — webhook podaci sadrže samo ID narudžbe, nikada status. SDK-ov verifyWebhook() to radi automatski.
  2. Vratite HTTP 200 za potvrdu primitka. Bilo koji drugi kod pokreće do 10 ponovnih pokušaja (svake 2 minute).
  3. Implementirajte rezervno anketiranje — za narudžbe starije od 10 minuta koje nisu dosegle konačni status, anketirajte getOrder() kao sigurnosnu mrežu.
  4. Budite idempotentni — možete primiti isti webhook više puta.

Testne kartice

Koristite ove kartice u Cost+ testnom načinu (sandbox web stranica):

KarticaBrojNapomene
Visa (uspjeh)4111 1111 1111 1111Bilo koji CVV
Mastercard (uspjeh)5544 3300 0003 7Bilo koji CVV
Visa (odbijena)4111 1111 1111 1105Do Not Honor
Visa (nedovoljna sredstva)4111 1111 1111 1151Insufficient Funds

Koristite bilo koji budući datum isteka i bilo koji 3-znamenkasti CVC.

Demo aplikacija

Docker-bazirana demo aplikacija (Ktor) uključena je u GitHub repozitoriju za testiranje potpunog tijeka plaćanja.

Podrška

Trebate pomoć? Obratite se našem timu za podršku na support@costplus.io.

On this page