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
HttpClientinjettabbli għall-ittestjar faċli b'mock transports- Jimmira Java 17+
Rekwiżiti
- JDK 17 jew aktar tard
- Kont ta' kummerċjant Cost+ — dashboard.costplus.io
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-SHA2563. 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?)
| Parametru | Tip | Meħtieġ | Default |
|---|---|---|---|
config.apiKey | String | Iva | — |
config.merchantId | String | Iva | — |
config.baseUrl | String | Le | https://api.nopayn.co.uk |
httpClient | java.net.http.HttpClient | Le | Klijent default |
client.createOrder(params): Order (suspend)
Joħloq ordni permezz ta' POST /v1/orders/.
| Parametru | Tip | Meħtieġ | Deskrizzjoni |
|---|---|---|---|
amount | Int | Iva | Ammont fl-unità minuri ISO 4217 tal-munita (per eżempju, ċenteżmi għal EUR) |
currency | String | Iva | Kodiċi ISO 4217 (EUR, GBP, USD, NOK, SEK) |
merchantOrderId | String? | Le | Ir-referenza interna tal-ordni tiegħek |
description | String? | Le | Deskrizzjoni tal-ordni |
returnUrl | String? | Le | Redirect wara ħlas li rnexxielu |
failureUrl | String? | Le | Redirect fuq kanċellazzjoni/skadenza/żball |
webhookUrl | String? | Le | Notifiki asinkroni ta' bidla fl-istatus |
locale | String? | Le | Lingwa tal-HPP (en-GB, de-DE, nl-NL, eċċ.) |
paymentMethods | List<String>? | Le | Iffiltra l-metodi tal-HPP |
expirationPeriod | String? | Le | Tul 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
| Status | Finali? | Deskrizzjoni |
|---|---|---|
new | Le | Ordni maħluqa |
processing | Le | Ħlas qed isir |
completed | Iva | Ħlas irnexxielu — ikkonsenja l-prodotti |
cancelled | Iva | Ħlas ikkanċellat mill-klijent |
expired | Iva | Link tal-ħlas skada |
error | Iva | Falliment tekniku |
L-Aħjar Prattiċi għall-Webhooks
- 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. - Irritorna HTTP 200 biex tikkonferma r-riċevuta. Kwalunkwe kodiċi ieħor jiskatta sa 10 retries (2 minuti bejn xulxin).
- 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à. - 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):
| Karta | Numru | Noti |
|---|---|---|
| Visa (suċċess) | 4111 1111 1111 1111 | Kwalunkwe CVV |
| Mastercard (suċċess) | 5544 3300 0003 7 | Kwalunkwe CVV |
| Visa (miċħuda) | 4111 1111 1111 1105 | Do Not Honor |
| Visa (fondi insuffiċjenti) | 4111 1111 1111 1151 | Insufficient 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.