Een geavanceerde Kayana integratie met RYFT bouwen in Python

Bouw een betalingsstroom met

Python (FastAPI) en de Ryft SDK

om veilig kaartgegevens in te zamelen en betalingen te verwerken. Deze handleiding legt uit hoe de

Python-plugin (

ryft_plugin.py

) de PHP-serverlogica vervangt

terwijl dezelfde checkout-functionaliteit behouden blijft. In plaats van handmatig alle backend-API's aan te roepen, stelt de plugin een vereenvoudigd ingangspunt beschikbaar:

POST /launch

Dit eindpunt:

1. Maakt een sessie voor de betaling
2. Opent een browserkasse-pagina
3. Roept intern de vereiste Kayana-betalingsgateway-API's aan
4. Geeft een beveiligd Ryft-kaartbetalingsformulier weer

Overzicht

De Python-plugin fungeert als een

payment proxy server

tussen de frontend checkout-pagina en de Kayana payment API. In plaats van PHP curl-verzoeken gebruikt de plugin:

• FastAPI voor backend-eindpunten
• Python requests library voor API-communicatie
• Ryft JavaScript SDK voor veilige kaartverwerking

Dit stelt ontwikkelaars in staat om een lokale betalingsgateway met behulp van Python uit te voeren.

Wat je gaat bouwen

De Python-plugin biedt de volgende functies:

• Een checkout-sessie starten
• Een betalingsinstantie maken met behulp van de Kayana API
• De openbare Ryft-sleutel ophalen voor initialisatie van de frontend
• Een beveiligde checkout-pagina weergeven
• Betalingen verwerken met behulp van de Ryft SDK
• Succesvolle betalingssessies registreren

Voordat u begint

U hebt het volgende nodig:

• Een Kayana Property ID
• Een Kayana API key
• Python 3.10+
• Geïnstalleerde afhankelijkheden:
• FastAPI
• Uvicorn
• Requests

Python Plugin-configuratie

De plugin definieert configuratie-instellingen die worden gebruikt voor API-communicatie. CONFIG = { "BASE_URL": "https://integration.dev.kayana.co.uk", "API_KEY": "YOUR_API_KEY" } Deze waarden bepalen:

• De Kayana API-omgeving
• Verificatieheaders
• Betalingsendpoint-URL's

Hoe de Python Plugin Werkt

1. Server maakt een payment instance aan en ontvangt een client_secret
2. Server haalt de Ryft public_key op
3. Frontend rendert het betalingsformulier en voltooit de transactie

Stap 1 — Een betaalsessie starten

Het

invoerpunt van de plugin is

/launch

. Dit eindpunt:

• valideert het verzoek
• creëert een sessie
• opent de betalingspagina automatisch

Eindpunt

POST /launch

Verzoekberichttekst

Hoe u uw X API-sleutel kunt verkrijgen

Volg deze stappen in Partner Admin:

• Meld u aan bij Kayana Partner Admin.
• Navigeer naar Instellingen (linkerzijbalk).
• Selecteer API Key Management.
• Klik op Create API Key.

Kopieer de gegenereerde sleutel onmiddellijk en stuur deze in de header.

Voorbeeldverzoek

curl -X POST http://localhost:8000/launch \ -H "Content-Type: application/json" \ -d '{ "property_id": "Prop_abc123example", "amount": 12.0, "currency_code": "GBP", "customer_email": "customer@example.com" }'

Voorbeeldrespons

{ "launched": true, "session_id": "e3d2f82a-8d9e-4c9b-8d4f-b3a29e82f1aa", "url": "http://localhost:8000/?session_id=e3d2f82a-8d9e-4c9b-8d4f-b3a29e82f1aa", "message": "Browser geopend met betalingspagina." }

Belangrijk: Interne API-aanroepen

In tegenstelling tot de standaard Kayana-integratiegids,

roept de plugin de gateway-API's automatisch intern aan

.

Intern geactiveerde API's

Wanneer de checkoutpagina wordt geladen, roept de frontend aan: POST /proxy/create-payment die intern aanroept: POST /web/payment Dit creëert de

betalingsinstantie

en retourneert de client_secret. Vervolgens haalt de plugin de Ryft-versleutelingssleutel op. GET /proxy/public-key die intern aanroept: GET /web/payment/public-key Dit retourneert de

PSP-openbare sleutel

die nodig is om de Ryft SDK te initialiseren.

Stap 2 — Betaalinstantie maken (Intern)

Endpoint gebruikt intern door de plugin: POST /proxy/create-payment Dit roept de Kayana API aan: POST /web/payment

Verzoekpayload

{ "property_id": "Prop_abc123example", "psp_code": "RYFT", "currency_code": "GBP", "amount": 12.0, "customer_email": "customer@example.com" }

Respons

{ "status": true, "client_secret": "ps_secret_example" } De client_secret is vereist door de

Ryft SDK om de betaling te bevestigen

.

Stap 3 — PSP Public Key Ophalen (Intern)

Endpoint gebruikt intern: GET /proxy/public-key Roept intern aan: GET /web/payment/public-key

Vereiste Headers

Antwoord

{ "status": true, "public_key": "pk_sandbox_abc123examplekey" }

Stap 4 – Betaalpagina weergeven

De plugin geeft de uitcheckpagina dynamisch weer met FastAPI.

Endpoint

GET / De HTML-sjabloon bevat de Ryft SDK. <script src="https://embedded.ryftpay.com/v2/ryft.min.js"></script> De betaalpagina voert de volgende acties uit:

1. Sessiegegevens laden
2. Betalingsinstantie maken
3. Openbare sleutel ophalen
4. Ryft initialiseren
5. Kaartbetalingsformulier inschakelen

Stap 5 – Initialise Ryft SDK

Zodra beide sleutels zijn opgehaald, initialiseert de frontend de Ryft SDK. Ryft.init({ publicKey: STATE.publicKey, clientSecret: STATE.clientSecret }); Dit stelt de SDK in staat om veilig kaartinformatie in te zamelen.

Stap 6 – Succesvolle betalingen registreren

Wanneer een betaling succesvol is, registreert de plugin de betalingssessie.

Endpoint

POST /api/log-payment

Voorbeeld geregistreerde gegevens

Sessie-ID Eigendoms-ID Klantemail Bedrag Betalingsstatus Dit helpt bij het volgen van transacties voor foutopsporing of auditing.

Aanvullende eindpunten voor bestellingen

Voorgestelde stroom:

Bestelling maken → Betaling autoriseren ↓ ├── Vastleggen → Succes ├── Annuleren → Betaling ongedaan maken └── Restitutie → Na vastlegging

Verificatie

Alle API-verzoeken moeten de volgende headers bevatten:

1. Geautoriseerde betaling vastleggen

Eindpunt

POST /web/payment/capture-authorised-payment

Aanvraagparameters

cURL-voorbeeld

curl --location 'https://integration.dev.kayana.co.uk/web/payment/capture-authorised-payment' \ --header 'Content-Type: application/json' \ --header 'type: business' \ --header 'x-api-key: <YOUR_API_KEY>' \ --data '{ "order_id": "Order_xxx", "amount": 5 }'

Voorbeeldantwoord

{ "status": "success", "message": "Payment captured successfully", "data": { "order_id": "Order_xxx", "captured_amount": 5 } }

2. Geautoriseerde betaling annuleren

Eindpunt

POST /web/payment/cancel-authorised-payment

Aanvraagparameters

cURL-voorbeeld

curl --location 'https://integration.dev.kayana.co.uk/web/payment/cancel-authorised-payment?order_id=Order_xxx' \ --header 'Content-Type: application/json' \ --header 'type: business' \ --header 'x-api-key: <YOUR_API_KEY>'

Voorbeeldantwoord

{ "status": "success", "message": "Payment cancelled successfully" }

3. Betaling terugbetalen

Eindpunt

POST /web/payment/refund

Aanvraagparameters

cURL-voorbeeld

curl --location --request POST 'https://integration.dev.kayana.co.uk/web/payment/refund?order_id=Order_xxx&amount=0.4' \ --header 'Content-Type: application/json' \ --header 'type: business' \ --header 'x-api-key: <YOUR_API_KEY>'

Voorbeeldantwoord

{ "status": "success", "message": "Refund processed", "data": { "order_id": "Order_xxx", "refunded_amount": 0.4 } }

4. Bestelgegevens ophalen

Eindpunt

GET /web/order/fetch-order-details-by-order-id

Aanvraagparameters

cURL-voorbeeld

curl --location 'https://integration.dev.kayana.co.uk/web/order/fetch-order-details-by-order-id?order_id=Order_xxx' \ --header 'type: business' \ --header 'x-api-key: <YOUR_API_KEY>'

Voorbeeldantwoord

{ "status": "success", "data": { "order_id": "Order_xxx", "status": "captured", "amount": 5 } }

Foutafhandeling

De plugin bevat een geavanceerd foutclassificatiesysteem. Fouten worden ingedeeld in:

• Ongeldig autorisatietoken
• Ontbrekende headers
• Ongeldig eigendoms-ID
• Niet-ondersteunde valuta
• PSP-configuratie ontbreekt

Voorbeeld classificatielogica: _classify_error(data, status_code) Elke fout retourneert: error_code message solution Dit biedt duidelijke feedback aan ontwikkelaars.

De Plugin Testen

Voer de server uit met:

• uvicorn main:app --reload --port 8000

De FastAPI-server wordt gestart op:

• http://localhost:8000

API-documentatie is beschikbaar op:

• http://localhost:8000/docs

Sandbox Test Cards

U kunt betalingen testen met Ryft sandbox cards. Maak een Checkout Page met Kaya…

Live gaan

Voordat u naar productie gaat:

1. Vervang de sandbox API-sleutel
2. Werk de basis-URL bij
3. Gebruik productie openbare sleutels
4. Schakel testkaarten uit
5. Beveilig API-referenties

Geef nooit productie sleutels bloot in client-side code.

Ondersteuning

Hulp nodig?

• Technische problemen: Neem contact op met Kayana Technical Support
• Productie-referenties: Vraag aan uw Kayana-accountmanager
• PSP-configuratie: Neem contact op met Kayana Technical Support

Wat nu?

• Verken webhook-integratie voor betalingsmeldingen
• Meer informatie over terugbetalingen en geschillenafhandeling
• Stel terugkerende betalingen in voor abonnementen

Volgende stappen

Als u liever Stripe als uw Payment Service Provider (PSP) gebruikt, ondersteunt Kayana ook een volledige Stripe-integratieflow. Raadpleeg onze gids over Het bouwen van een afrondingspagina met Kayana's Stripe Plugin (Python).