Documentation API POS

Guide complet pour intégrer les paiements en stablecoin dans votre système POS avec l'API OSTRIA

Authentification

L'API POS utilise un système d'authentification par clé API, distinct du système JWT utilisé par l'application web.

Méthodes d'authentification

Deux méthodes sont supportées :

Header X-API-Key (Recommandé)

X-API-Key: ostria_xxxxx...xxxxx

Header Authorization Bearer (Alternative)

Authorization: Bearer ostria_xxxxx...xxxxx

Obtenir votre clé API :

  • Contactez-nous à info@ostriapay.com pour obtenir votre clé API
  • Format : ostria_xxxxx...xxxxx
  • Nous configurons votre compte marchand et activons l'API POS pour votre compte
  • Restrictions d'IP optionnelles disponibles sur demande

URL de base

L'URL de base de l'API vous sera communiquée lors de l'obtention de votre clé API.

Contactez-nous à info@ostriapay.com pour obtenir votre clé API et l'URL de base de l'environnement approprié (production ou développement).

Endpoints

POST Créer un paiement

/api/pos/payments/create

Authentification : Requise (API Key)

Request Body

JSON

{
    "amount_eur": 50.00,
    "pos_transaction_id": "POS-TEST-001",  // Optionnel
    "date": "2026-01-18T12:00:00Z",       // Optionnel
    "notification_mode": "polling",        // "polling" ou "webhook"
    "webhook_url": "https://..."           // Requis si notification_mode = "webhook"
}

Response 200

JSON

{
    "payment_id": "PAY-ABC123DEF456",
    "qr_code_base64": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "amount_eur": 50.00,
    "amount_crypto": 54.35,
    "crypto_type": "USDC",
    "exchange_rate": 0.92,
    "polling_url": "/api/pos/payments/PAY-ABC123DEF456/status",
    "created_at": "2026-01-18T12:00:00Z"
}

Notes importantes :

  • Le qr_code_base64 est retourné au format data URI complet (data:image/png;base64,{base64_string}), prêt à être utilisé directement dans un tag HTML <img>
  • Le payment_id doit être sauvegardé pour les requêtes de polling
  • Le webhook_url est requis uniquement si notification_mode = "webhook"

Erreurs possibles :

  • 400 : Requête invalide (webhook_url manquant, wallet non configuré, etc.)
  • 401 : Authentification échouée (clé API invalide/inactive)
  • 403 : API POS non activée pour le merchant

GET Vérifier le statut (Polling)

/api/pos/payments/{payment_id}/status

Authentification : Requise (API Key)

Response 200

JSON

{
    "payment_id": "PAY-ABC123DEF456",
    "status": "pending",  // "pending", "confirmed", "completed"
    "paid": false,
    "amount_eur": 50.00,
    "amount_crypto": 54.35,
    "crypto_type": "USDC",
    "transaction_hash": null,  // Disponible quand paid = true
    "confirmed_at": null,      // Disponible quand paid = true
    "created_at": "2026-01-18T12:00:00Z"
}

Recommandations de polling :

  • Fréquence recommandée : Poller toutes les 3-5 secondes
  • Durée maximale : 3 minutes (environ 60 appels)
  • Arrêtez le polling dès que paid: true pour optimiser les performances

Workflow de polling :

  1. Créer le paiement → Récupérer payment_id
  2. Afficher le QR code au client
  3. Poller GET /api/pos/payments/{payment_id}/status toutes les 3-5 secondes
  4. Arrêter le polling quand paid: true
  5. Confirmer la transaction POS

GET Récupérer les détails complets

/api/pos/payments/{payment_id}

Authentification : Requise (API Key)

Response 200

JSON

{
    "payment_id": "PAY-ABC123DEF456",
    "status": "completed",
    "paid": true,
    "amount_eur": 50.00,
    "amount_crypto": 54.35,
    "crypto_type": "USDC",
    "exchange_rate": 0.92,
    "transaction_hash": "0x1234567890abcdef...",
    "confirmations": 3,
    "created_at": "2026-01-18T12:00:00Z",
    "confirmed_at": "2026-01-18T12:05:30Z",
    "completed_at": "2026-01-18T12:05:30Z",
    "pos_transaction_id": "POS-TEST-001",
    "notification_mode": "polling"
}

Webhooks

Recevez des notifications automatiques lorsque les paiements sont confirmés

Configuration

Pour recevoir des notifications webhook, configurez lors de la création du paiement :

JSON

{
    "amount_eur": 50.00,
    "notification_mode": "webhook",
    "webhook_url": "https://your-pos-system.com/webhook/ostria"
}

Format du webhook

Lorsqu'un paiement est confirmé, Ostria envoie une requête POST à votre webhook_url :

Method : POST

Headers : Content-Type: application/json

Body

JSON

{
    "payment_id": "PAY-ABC123DEF456",
    "status": "completed",
    "paid": true,
    "amount_eur": 50.00,
    "amount_crypto": 54.35,
    "crypto_type": "USDC",
    "transaction_hash": "0x1234567890abcdef...",
    "confirmed_at": "2026-01-18T12:05:30Z"
}

Retry et gestion d'erreurs :

  • Retry automatique : 3 tentatives maximum
  • Backoff exponentiel : 1s, 2s, 4s
  • Timeout : 30 secondes par tentative

Recommandations :

  • ✅ Votre endpoint webhook doit répondre avec un code HTTP 200-299 pour être considéré comme réussi
  • ✅ Répondez rapidement (< 5 secondes) pour éviter les timeouts
  • ✅ Implémentez l'idempotence côté POS (vérifier payment_id pour éviter les doublons)
  • ✅ Loggez toutes les notifications reçues pour le debugging

Exemple d'intégration rapide

Voici un exemple concret d'intégration en JavaScript pour vous donner une idée de la simplicité

Créer un paiement et afficher le QR code

JavaScript

// 1. Créer le paiement
const response = await fetch('{BASE_URL}/api/pos/payments/create', {
    method: 'POST',
    headers: {
        'X-API-Key': 'ostria_votre_cle_api',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        amount_eur: 50.00,
        pos_transaction_id: 'TXN-001',
        notification_mode: 'polling'
    })
});

const payment = await response.json();

// 2. Afficher le QR code (format data URI complet)
const img = document.createElement('img');
img.src = payment.qr_code_base64; // Prêt à utiliser directement
document.getElementById('qr-container').appendChild(img);

// 3. Poller le statut toutes les 3 secondes
const pollStatus = async () => {
    const statusResponse = await fetch(
        `{BASE_URL}/api/pos/payments/${payment.payment_id}/status`,
        {
            headers: {
                'X-API-Key': 'ostria_votre_cle_api'
            }
        }
    );
    const status = await statusResponse.json();
    
    if (status.paid) {
        console.log('Paiement confirmé !');
        // Confirmer la transaction dans votre POS
        confirmTransaction(payment.payment_id);
    } else {
        // Continuer le polling
        setTimeout(pollStatus, 3000);
    }
};

pollStatus();

Documentation Swagger

Interface interactive pour tester l'API directement depuis votre navigateur

Interface publique pour partenaires

Une documentation Swagger dédiée est disponible pour les partenaires :

L'URL de la documentation Swagger interactive vous sera communiquée lors de l'obtention de votre clé API.

Caractéristiques :

  • ✅ Accessible sans authentification pour faciliter l'intégration
  • ✅ Filtre uniquement les endpoints avec le tag "POS"
  • ✅ Exemples de requêtes et réponses
  • ✅ Interface interactive pour tester l'API