Java / Kotlin
Uradni Kotlin/Java SDK za plačilni prehod Cost+
Uradni Kotlin SDK za plačilni prehod Cost+, v celoti združljiv z Javo. Poenostavlja tok preusmeritve HPP (gostovane plačilne strani), HMAC podpisovanje koristnih podatkov in preverjanje webhook-ov.
Lastnosti
- Kotlin-prvi, Java-prijazen — data classes, coroutines, null safety; v celoti uporaben iz Jave
- kotlinx.serialization — brez odvisnosti od Gson/Jackson; samodejno preslikavanje snake_case/camelCase
- HMAC-SHA256 generiranje podpisov in preverjanje s konstantnim časom
- Razčlenjevanje webhook-ov + preverjanje naročil na osnovi API-ja
- Suspend funkcije za neblokirajoči IO prek Kotlin coroutines
- Vnosljiv
HttpClientza enostavno testiranje z lažnimi transporti - Ciljno Java 17+
Zahteve
- JDK 17 ali novejši
- Trgovski račun Cost+ — dashboard.costplus.io
Namestitev
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>Hitri začetek (Kotlin)
1. Inicializirajte odjemalca
import io.nopayn.*
import kotlinx.coroutines.runBlocking
fun main() = runBlocking {
val nopayn = NoPaynClient(
NoPaynConfig(
apiKey = "your-api-key",
merchantId = "your-project",
)
)
}2. Ustvarite plačilo in preusmerite 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) // Neposredni URL plačilne metode
println(result.signature) // HMAC-SHA256 podpis3. Obdelajte webhook
// V vašem HTTP obdelovalcu (Ktor, Spring itd.)
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") {
// Izpolnite naročilo
}Hitri začetek (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());
// Pripomočki za podpise delujejo sinhrono
String sig = client.generateSignature(1295, "EUR", order.getId());
boolean valid = client.verifySignature(1295, "EUR", order.getId(), sig);
}
}API referenca
NoPaynClient(config, httpClient?)
| Parameter | Tip | Obvezno | Privzeto |
|---|---|---|---|
config.apiKey | String | Da | — |
config.merchantId | String | Da | — |
config.baseUrl | String | Ne | https://api.nopayn.co.uk |
httpClient | java.net.http.HttpClient | Ne | Privzeti odjemalec |
client.createOrder(params): Order (suspend)
Ustvari naročilo prek POST /v1/orders/.
| Parameter | Tip | Obvezno | Opis |
|---|---|---|---|
amount | Int | ja | Znesek v manjši enoti ISO 4217 valute (na primer centi za EUR) |
currency | String | Da | Koda ISO 4217 (EUR, GBP, USD, NOK, SEK) |
merchantOrderId | String? | Ne | Vaša interna referenca naročila |
description | String? | Ne | Opis naročila |
returnUrl | String? | Ne | Preusmeritev po uspešnem plačilu |
failureUrl | String? | Ne | Preusmeritev ob preklicu/poteku/napaki |
webhookUrl | String? | Ne | Asinhrona obvestila o spremembi statusa |
locale | String? | Ne | Jezik HPP (en-GB, de-DE, nl-NL itd.) |
paymentMethods | List<String>? | Ne | Filtriraj metode HPP |
expirationPeriod | String? | Ne | Trajanje ISO 8601 (PT30M) |
Razpoložljive plačilne metode: credit-card, apple-pay, google-pay, vipps-mobilepay
client.getOrder(orderId): Order (suspend)
Pridobi podrobnosti naročila prek GET /v1/orders/{id}/.
client.createRefund(orderId, amount, description?): Refund (suspend)
Izda celotno ali delno vračilo prek POST /v1/orders/{id}/refunds/.
client.generatePaymentUrl(params): PaymentUrlResult (suspend)
Priročna metoda, ki ustvari naročilo in vrne:
PaymentUrlResult(
orderId: String, // NoPayn UUID naročila
orderUrl: String, // HPP URL
paymentUrl: String?, // Neposredni plačilni URL (prva transakcija)
signature: String, // HMAC-SHA256 od amount:currency:orderId
order: Order, // Celoten objekt naročila
)client.generateSignature(amount, currency, orderId): String
Generira HMAC-SHA256 šestnajstiški podpis. Kanonično sporočilo je $amount:$currency:$orderId, podpisano z API ključem.
client.verifySignature(amount, currency, orderId, signature): Boolean
Preverjanje HMAC-SHA256 podpisa s konstantnim časom.
client.verifyWebhook(rawBody): VerifiedWebhook (suspend)
Razčleni telo webhook-a, nato pokliče GET /v1/orders/{id}/ za preverjanje dejanskega statusa.
Samostojne HMAC pripomočke
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);Obravnava napak
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 naročil
| Status | Končni? | Opis |
|---|---|---|
new | Ne | Naročilo ustvarjeno |
processing | Ne | Plačilo v teku |
completed | Da | Plačilo uspešno — dostavite blago |
cancelled | Da | Plačilo preklicano s strani stranke |
expired | Da | Plačilna povezava je potekla |
error | Da | Tehnična napaka |
Najboljše prakse za webhook-e
- Vedno preverite prek API-ja — koristni podatki webhook-a vsebujejo samo ID naročila, nikoli statusa. SDK-jev
verifyWebhook()to naredi samodejno. - Vrnite HTTP 200 za potrditev prejema. Katerakoli druga koda sproži do 10 ponovnih poskusov (2 minuti narazen).
- Implementirajte rezervno poizvedovanje — za naročila, starejša od 10 minut, ki še niso dosegla končnega statusa, poizvedujte
getOrder()kot varnostno mrežo. - Bodite idempotentni — isti webhook lahko prejmete večkrat.
Testne kartice
Uporabite te kartice v testnem načinu Cost+ (spletno mesto peskovnika):
| Kartica | Številka | Opombe |
|---|---|---|
| Visa (uspeh) | 4111 1111 1111 1111 | Katerikoli CVV |
| Mastercard (uspeh) | 5544 3300 0003 7 | Katerikoli CVV |
| Visa (zavrnjena) | 4111 1111 1111 1105 | Zavrnitev |
| Visa (nezadostna sredstva) | 4111 1111 1111 1151 | Nezadostna sredstva |
Uporabite katerikoli prihodnji datum veljavnosti in katerokoli 3-mestno CVC kodo.
Predstavitvena aplikacija
Predstavitvena aplikacija na osnovi Docker (Ktor) je vključena v GitHub repozitorij za testiranje celotnega plačilnega toka.
Podpora
Potrebujete pomoč? Obrnite se na našo ekipo za podporo na support@costplus.io.