Cost+Docs

Java / Kotlin

SDK oifigiúil Kotlin/Java do gheata íocaíochta Cost+

SDK oifigiúil Kotlin do gheata íocaíochta Cost+, go hiomlán idir-inoibritheach le Java. Simpliú an tsreabha atreoraithe HPP (Leathanach Íocaíochta Óstáilte), síniú sonraí HMAC, agus fíorú webhook.

Gnéithe

  • Kotlin-ar-dtús, cairdiúil do Java -- ranganna sonraí, coroutines, sábháilteacht nialais; go hiomlán inúsáidte ó Java
  • kotlinx.serialization -- gan spleáchas Gson/Jackson; mapáil uathoibríoch snake_case/camelCase
  • Giniúint sínithe HMAC-SHA256 agus fíorú ama-leanúnaigh
  • Parsáil webhook + fíorú ordaithe bunaithe ar API
  • Feidhmeanna fionraí le haghaidh IO neamhbhlocáil trí coroutines Kotlin
  • HttpClient insíothlaithe le haghaidh tástáil éasca le haistrithe bréige
  • Dírithe ar Java 17+

Riachtanais

Suiteáil

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>

Mearthosnú (Kotlin)

1. Túsaigh an Cliant

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

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

2. Cruthaigh Íocaíocht agus Atreorófar chuig an 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. Láimhseáil an 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
}

Mearthosnú (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);
    }
}

Tagairt API

NoPaynClient(config, httpClient?)

ParaiméadarCineálRiachtanachRéamhshocrú
config.apiKeyStringTá--
config.merchantIdStringTá--
config.baseUrlStringNílhttps://api.nopayn.co.uk
httpClientjava.net.http.HttpClientNílCliant réamhshocraithe

client.createOrder(params): Order (suspend)

Cruthaíonn ordú tríd an POST /v1/orders/.

ParaiméadarCineálRiachtanachCur Síos
amountIntTáMéid i mionaonad ISO 4217 an airgeadra (mar shampla, cent le haghaidh EUR)
currencyStringTáCód ISO 4217 (EUR, GBP, USD, NOK, SEK)
merchantOrderIdString?NílDo thagairt inmheánach ordaithe
descriptionString?NílCur síos ar an ordú
returnUrlString?NílAtreorú tar éis íocaíochta rathúla
failureUrlString?NílAtreorú ar cheallú/éag/earráid
webhookUrlString?NílFógraí athraithe stádais asincrónach
localeString?NílTeanga HPP (en-GB, de-DE, nl-NL, srl.)
paymentMethodsList<String>?NílScag modhanna HPP
expirationPeriodString?NílFad ISO 8601 (PT30M)

Modhanna íocaíochta ar fáil: credit-card, apple-pay, google-pay, vipps-mobilepay

client.getOrder(orderId): Order (suspend)

Faigheann sonraí ordaithe tríd an GET /v1/orders/{id}/.

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

Eisíonn aisíocaíocht iomlán nó pháirteach tríd an POST /v1/orders/{id}/refunds/.

client.generatePaymentUrl(params): PaymentUrlResult (suspend)

Modh áise a chruthaíonn ordú agus a sheolann ar ais:

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

Gineann síniú HMAC-SHA256 hex. Is é an teachtaireacht chanónta ná $amount:$currency:$orderId, sínithe leis an eochair API.

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

Fíorú ama-leanúnaigh ar shíniú HMAC-SHA256.

client.verifyWebhook(rawBody): VerifiedWebhook (suspend)

Parsáileann corp an webhook, ansin glaonn GET /v1/orders/{id}/ chun an stádas iarbhír a fhíorú.

Fóntais HMAC Neamhspleácha

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:

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

Láimhseáil Earráidí

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
}

Stádais Ordaithe

StádasDeiridh?Cur Síos
newNílOrdú cruthaithe
processingNílÍocaíocht ar siúl
completedTáD'éirigh leis an íocaíocht -- seachaid na hearraí
cancelledTáCheal an custaiméir an íocaíocht
expiredTáD'éag an nasc íocaíochta
errorTáTeip theicniúil

Dea-Chleachtais Webhook

  1. Fíoraigh tríd an API i gcónaí -- ní bhíonn ach aitheantas an ordaithe sa sonraí webhook, ní an stádas riamh. Déanann verifyWebhook() an SDK é seo go huathoibríoch.
  2. Seol HTTP 200 ar ais chun fáiltiú a admháil. Spreagann aon chód eile suas le 10 n-atriail (2 nóiméad eatarthu).
  3. Cuir cúltaca pólaí i bhfeidhm -- d'orduithe atá níos sine ná 10 nóiméad nach bhfuil stádas deiridh bainte amach acu, pólail getOrder() mar líontán sábháilteachta.
  4. Bí idéimpotent -- d'fhéadfá an webhook céanna a fháil arís is arís eile.

Cártaí Tástála

Úsáid na cártaí seo i mód tástála Cost+ (suíomh gréasáin gaineamhchláir):

CártaUimhirNótaí
Visa (rath)4111 1111 1111 1111Aon CVV
Mastercard (rath)5544 3300 0003 7Aon CVV
Visa (diúltaithe)4111 1111 1111 1105Do Not Honor
Visa (cistí neamhleor)4111 1111 1111 1151Insufficient Funds

Úsáid aon dáta éaga amach anseo agus aon CVC 3 dhigit.

Aip Thaispeána

Tá aip thaispeána Docker-bhunaithe (Ktor) san áireamh sa stór GitHub chun an sreabhadh íocaíochta iomlán a thástáil.

Tacaíocht

Cabhair ag teastáil? Déan teagmháil lenár bhfoireann tacaíochta ag support@costplus.io.

On this page