Java / Kotlin

SDK officiel Kotlin pour la passerelle de paiement Cost+, entièrement interopérable avec Java. Simplifie le flux de redirection HPP (page de paiement hébergée), la signature de payload HMAC et la vérification des webhooks.

Fonctionnalités

Kotlin-first, compatible Java — data classes, coroutines, null safety ; entièrement utilisable depuis Java
kotlinx.serialization — aucune dépendance Gson/Jackson ; mappage automatique snake_case/camelCase
Génération de signature HMAC-SHA256 et vérification en temps constant
Analyse des webhooks + vérification des commandes via l'API
Fonctions suspend pour les I/O non bloquantes via les coroutines Kotlin
HttpClient injectable pour faciliter les tests avec des transports simulés
Cible Java 17+

Prérequis

JDK 17 ou ultérieur
Un compte marchand Cost+ — dashboard.costplus.io

Installation

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>

Démarrage rapide (Kotlin)

1. Initialiser le client

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

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

2. Créer un paiement et rediriger vers la 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. Gérer le 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
}

Démarrage rapide (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);
    }
}

Référence API

`NoPaynClient(config, httpClient?)`

Paramètre	Type	Obligatoire	Par défaut
`config.apiKey`	`String`	Oui	—
`config.merchantId`	`String`	Oui	—
`config.baseUrl`	`String`	Non	`https://api.nopayn.co.uk`
`httpClient`	`java.net.http.HttpClient`	Non	Client par défaut

`client.createOrder(params): Order` (suspend)

Crée une commande via POST /v1/orders/.

Paramètre	Type	Obligatoire	Description
`amount`	`Int`	Oui	Montant dans la plus petite unité monétaire (centimes)
`currency`	`String`	Oui	Code ISO 4217 (`EUR`, `GBP`, `USD`, `NOK`, `SEK`)
`merchantOrderId`	`String?`	Non	Votre référence interne de commande
`description`	`String?`	Non	Description de la commande
`returnUrl`	`String?`	Non	Redirection après paiement réussi
`failureUrl`	`String?`	Non	Redirection en cas d'annulation/expiration/erreur
`webhookUrl`	`String?`	Non	Notifications asynchrones de changement de statut
`locale`	`String?`	Non	Langue de la HPP (`en-GB`, `de-DE`, `nl-NL`, etc.)
`paymentMethods`	`List<String>?`	Non	Filtrer les méthodes HPP
`expirationPeriod`	`String?`	Non	Durée ISO 8601 (`PT30M`)

Méthodes de paiement disponibles : credit-card, apple-pay, google-pay, vipps-mobilepay

`client.getOrder(orderId): Order` (suspend)

Récupère les détails de la commande via GET /v1/orders/{id}/.

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

Effectue un remboursement total ou partiel via POST /v1/orders/{id}/refunds/.

`client.generatePaymentUrl(params): PaymentUrlResult` (suspend)

Méthode utilitaire qui crée une commande et renvoie :

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`

Génère une signature HMAC-SHA256 hexadécimale. Le message canonique est $amount:$currency:$orderId, signé avec la clé API.

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

Vérification en temps constant d'une signature HMAC-SHA256.

`client.verifyWebhook(rawBody): VerifiedWebhook` (suspend)

Analyse le corps du webhook, puis appelle GET /v1/orders/{id}/ pour vérifier le statut réel.

Utilitaires HMAC autonomes

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)

Depuis Java :

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

Gestion des erreurs

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
}

Statuts des commandes

Statut	Final ?	Description
`new`	Non	Commande créée
`processing`	Non	Paiement en cours
`completed`	Oui	Paiement réussi — livrez les marchandises
`cancelled`	Oui	Paiement annulé par le client
`expired`	Oui	Le lien de paiement a expiré
`error`	Oui	Erreur technique

Bonnes pratiques pour les webhooks

Vérifiez toujours via l'API — le payload du webhook contient uniquement l'identifiant de la commande, jamais le statut. Le verifyWebhook() du SDK le fait automatiquement.
Renvoyez HTTP 200 pour accuser réception. Tout autre code déclenche jusqu'à 10 tentatives (espacées de 2 minutes).
Implémentez un polling de secours — pour les commandes de plus de 10 minutes qui n'ont pas atteint un statut final, interrogez getOrder() comme filet de sécurité.
Soyez idempotent — vous pouvez recevoir le même webhook plusieurs fois.

Cartes de test

Utilisez ces cartes en mode test Cost+ (site web sandbox) :

Carte	Numéro	Notes
Visa (succès)	`4111 1111 1111 1111`	N'importe quel CVV
Mastercard (succès)	`5544 3300 0003 7`	N'importe quel CVV
Visa (refusée)	`4111 1111 1111 1105`	Do Not Honor
Visa (fonds insuffisants)	`4111 1111 1111 1151`	Insufficient Funds

Utilisez n'importe quelle date d'expiration future et n'importe quel CVC à 3 chiffres.

Application de démonstration

Une application de démonstration basée sur Docker (Ktor) est incluse dans le dépôt GitHub pour tester le flux de paiement complet.

Support

Besoin d'aide ? Contactez notre équipe de support à support@costplus.io.

On this page