Cost+Docs

Java / Kotlin

SDK uffiċjali ta' Kotlin/Java għall-gateway tal-ħlas Cost+

SDK uffiċjali ta' Kotlin għall-gateway tal-ħlas Cost+, kompletament interoperabbli ma' Java. Jissimplifika l-flusso ta' redirect tal-HPP (Paġna ta' Ħlas Ospitata), il-firma tal-payload HMAC, u l-verifika tal-webhooks.

Karatteristiċi

  • Kotlin-first, Java-friendly — data classes, coroutines, null safety; kompletament użabbli minn Java
  • kotlinx.serialization — l-ebda dipendenza ta' Gson/Jackson; mappa awtomatika ta' snake_case/camelCase
  • Ġenerazzjoni ta' firma HMAC-SHA256 u verifika b'ħin kostanti
  • Ipparsjar tal-webhooks + verifika tal-ordni bbażata fuq l-API
  • Suspend functions għal IO mhux blokkanti permezz ta' coroutines ta' Kotlin
  • HttpClient injettabbli għall-ittestjar faċli b'mock transports
  • Jimmira Java 17+

Rekwiżiti

Installazzjoni

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>

Bidu Malajr (Kotlin)

1. Inizjalizza l-Klijent

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

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

2. Oħloq Ħlas u Irridirezzjona lejn il-HPP

val result = nopayn.generatePaymentUrl(
    CreateOrderParams(
        amount = 1295,            // €12.95 f'ċenteżmi
        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)    // URL tal-HPP
println(result.paymentUrl)  // URL tal-metodu ta' ħlas dirett
println(result.signature)   // Firma HMAC-SHA256

3. Ittratta l-Webhook

// Fil-handler HTTP tiegħek (Ktor, Spring, eċċ.)
val rawBody: String = request.body()
val verified = nopayn.verifyWebhook(rawBody)

println(verified.order.status)  // "completed", "cancelled", eċċ.
println(verified.isFinal)       // true meta l-ordni ma tinbidilx aktar

if (verified.order.status == "completed") {
    // Issodisfa l-ordni
}

Bidu Malajr (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());

        // L-utilitajiet tal-firma jaħdmu b'mod sinkronu
        String sig = client.generateSignature(1295, "EUR", order.getId());
        boolean valid = client.verifySignature(1295, "EUR", order.getId(), sig);
    }
}

Referenza tal-API

NoPaynClient(config, httpClient?)

ParametruTipMeħtieġDefault
config.apiKeyStringIva—
config.merchantIdStringIva—
config.baseUrlStringLehttps://api.nopayn.co.uk
httpClientjava.net.http.HttpClientLeKlijent default

client.createOrder(params): Order (suspend)

Joħloq ordni permezz ta' POST /v1/orders/.

ParametruTipMeħtieġDeskrizzjoni
amountIntIvaAmmont fl-unità minuri ISO 4217 tal-munita (per eżempju, ċenteżmi għal EUR)
currencyStringIvaKodiċi ISO 4217 (EUR, GBP, USD, NOK, SEK)
merchantOrderIdString?LeIr-referenza interna tal-ordni tiegħek
descriptionString?LeDeskrizzjoni tal-ordni
returnUrlString?LeRedirect wara ħlas li rnexxielu
failureUrlString?LeRedirect fuq kanċellazzjoni/skadenza/żball
webhookUrlString?LeNotifiki asinkroni ta' bidla fl-istatus
localeString?LeLingwa tal-HPP (en-GB, de-DE, nl-NL, eċċ.)
paymentMethodsList<String>?LeIffiltra l-metodi tal-HPP
expirationPeriodString?LeTul ta' żmien ISO 8601 (PT30M)

Metodi ta' ħlas disponibbli: credit-card, apple-pay, google-pay, vipps-mobilepay

client.getOrder(orderId): Order (suspend)

Jiġbed id-dettalji tal-ordni permezz ta' GET /v1/orders/{id}/.

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

Joħroġ rifużjoni sħiħa jew parzjali permezz ta' POST /v1/orders/{id}/refunds/.

client.generatePaymentUrl(params): PaymentUrlResult (suspend)

Metodu ta' konvenjenza li joħloq ordni u jirritorna:

PaymentUrlResult(
    orderId: String,     // UUID tal-ordni NoPayn
    orderUrl: String,    // URL tal-HPP
    paymentUrl: String?, // URL ta' ħlas dirett (l-ewwel tranżazzjoni)
    signature: String,   // HMAC-SHA256 ta' amount:currency:orderId
    order: Order,        // Oġġett sħiħ tal-ordni
)

client.generateSignature(amount, currency, orderId): String

Jiġġenera firma HMAC-SHA256 hex. Il-messaġġ kanoniku huwa $amount:$currency:$orderId, iffirmat biċ-ċavetta API.

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

Verifika b'ħin kostanti ta' firma HMAC-SHA256.

client.verifyWebhook(rawBody): VerifiedWebhook (suspend)

Jipparsja l-korp tal-webhook, imbagħad isejjaħ GET /v1/orders/{id}/ biex jivverifika l-istatus attwali.

Utilitajiet HMAC Standalone

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)

Minn Java:

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

Trattar tal-Żbalji

import io.nopayn.*

try {
    nopayn.createOrder(CreateOrderParams(amount = 100, currency = "EUR"))
} catch (e: ApiException) {
    println(e.statusCode)  // 401, 400, eċċ.
    println(e.errorBody)   // Risposta ta' żball mhux ipproċessata tal-API
} catch (e: NoPaynException) {
    println(e.message)     // Żball tan-network jew tal-ipparsjar
}

Statuses tal-Ordni

StatusFinali?Deskrizzjoni
newLeOrdni maħluqa
processingLeĦlas qed isir
completedIvaĦlas irnexxielu — ikkonsenja l-prodotti
cancelledIvaĦlas ikkanċellat mill-klijent
expiredIvaLink tal-ħlas skada
errorIvaFalliment tekniku

L-Aħjar Prattiċi għall-Webhooks

  1. Dejjem ivverifika permezz tal-API — il-payload tal-webhook fih biss l-ID tal-ordni, qatt l-istatus. Il-verifyWebhook() tal-SDK jagħmel dan awtomatikament.
  2. Irritorna HTTP 200 biex tikkonferma r-riċevuta. Kwalunkwe kodiċi ieħor jiskatta sa 10 retries (2 minuti bejn xulxin).
  3. Implimenta backup poller — għal ordnijiet itqal minn 10 minuti li għadhom ma laħqux status finali, agħmel polling ta' getOrder() bħala xibka ta' sigurtà.
  4. Kun idempotenti — tista' tirċievi l-istess webhook aktar minn darba.

Karti tat-Test

Uża dawn il-karti f'modalità tat-test ta' Cost+ (website sandbox):

KartaNumruNoti
Visa (suċċess)4111 1111 1111 1111Kwalunkwe CVV
Mastercard (suċċess)5544 3300 0003 7Kwalunkwe CVV
Visa (miċħuda)4111 1111 1111 1105Do Not Honor
Visa (fondi insuffiċjenti)4111 1111 1111 1151Insufficient Funds

Uża kwalunkwe data ta' skadenza futura u kwalunkwe CVC ta' 3 ċifri.

App Demo

App demo bbażata fuq Docker (Ktor) hija inkluża fir-repożitorju ta' GitHub għall-ittestjar tal-flusso sħiħ tal-ħlas.

Appoġġ

Għandek bżonn l-għajnuna? Ikkuntattja t-tim tal-appoġġ tagħna fuq support@costplus.io.

On this page