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
HttpClientza jednostavno testiranje s mock transportima - Cilja Java 17+
Zahtjevi
- JDK 17 ili noviji
- Cost+ trgovački račun — dashboard.costplus.io
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 signature3. 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?)
| Parametar | Tip | Obavezno | Zadano |
|---|---|---|---|
config.apiKey | String | Da | — |
config.merchantId | String | Da | — |
config.baseUrl | String | Ne | https://api.nopayn.co.uk |
httpClient | java.net.http.HttpClient | Ne | Zadani klijent |
client.createOrder(params): Order (suspend)
Stvara narudžbu putem POST /v1/orders/.
| Parametar | Tip | Obavezno | Opis |
|---|---|---|---|
amount | Int | Da | Iznos u manjoj jedinici ISO 4217 valute (na primjer, centi za EUR) |
currency | String | Da | ISO 4217 kod (EUR, GBP, USD, NOK, SEK) |
merchantOrderId | String? | Ne | Vaša interna referenca narudžbe |
description | String? | Ne | Opis narudžbe |
returnUrl | String? | Ne | Preusmjeravanje nakon uspješnog plaćanja |
failureUrl | String? | Ne | Preusmjeravanje pri poništenju/isteku/grešci |
webhookUrl | String? | Ne | Asinkrone obavijesti o promjeni statusa |
locale | String? | Ne | Jezik HPP-a (en-GB, de-DE, nl-NL itd.) |
paymentMethods | List<String>? | Ne | Filtriranje HPP načina |
expirationPeriod | String? | Ne | ISO 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
| Status | Konačan? | Opis |
|---|---|---|
new | Ne | Narudžba stvorena |
processing | Ne | Plaćanje u tijeku |
completed | Da | Plaćanje uspjelo — isporučite robu |
cancelled | Da | Plaćanje poništeno od strane kupca |
expired | Da | Poveznica za plaćanje je istekla |
error | Da | Tehnički kvar |
Najbolje prakse za webhookove
- Uvijek provjerite putem API-ja — webhook podaci sadrže samo ID narudžbe, nikada status. SDK-ov
verifyWebhook()to radi automatski. - Vratite HTTP 200 za potvrdu primitka. Bilo koji drugi kod pokreće do 10 ponovnih pokušaja (svake 2 minute).
- Implementirajte rezervno anketiranje — za narudžbe starije od 10 minuta koje nisu dosegle konačni status, anketirajte
getOrder()kao sigurnosnu mrežu. - Budite idempotentni — možete primiti isti webhook više puta.
Testne kartice
Koristite ove kartice u Cost+ testnom načinu (sandbox web stranica):
| Kartica | Broj | Napomene |
|---|---|---|
| Visa (uspjeh) | 4111 1111 1111 1111 | Bilo koji CVV |
| Mastercard (uspjeh) | 5544 3300 0003 7 | Bilo koji CVV |
| Visa (odbijena) | 4111 1111 1111 1105 | Do Not Honor |
| Visa (nedovoljna sredstva) | 4111 1111 1111 1151 | Insufficient 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.