Bestellung erstellen
POST /v1/orders erstellt eine Zahlung und liefert die gehostete checkout_url zurück.
Wichtige Hinweise
- amount ist eine positive ganze Zahl in der kleinsten Währungseinheit. currency ist USD, HKD oder CNY; die Live-Verfügbarkeit hängt vom Konto ab.
- out_trade_no ist eine optionale Händlerreferenz mit 1–128 Zeichen und dient der Idempotenz. subject ist auf 255 Zeichen begrenzt.
- notify_url muss öffentlich per HTTPS erreichbar sein. Im Live-Betrieb ist ohne sie ein aktiver payment.succeeded-Endpunkt nötig. Identische Wiederholung ergibt 200, abweichende Daten 409.
- return_url dient nur dem Browser. Mit &locale=en oder &locale=zh an checkout_url legen Sie die Checkout-Sprache fest. Protokollieren Sie das Bearer-Token nicht.
Beispiel
curl -X POST "https://api.kukopay.com/v1/orders" \
-H "Content-Type: application/json" \
-H "X-Api-Key: $KUKOPAY_API_KEY" \
-d '{
"out_trade_no": "ORD_20260921_0001",
"amount": 2990,
"currency": "USD",
"subject": "Premium plan",
"notify_url": "https://shop.example.com/webhooks/kukopay",
"return_url": "https://shop.example.com/orders/complete"
}'Anfragefelder
| Feld | Pflicht | Beschreibung |
|---|---|---|
out_trade_no | Nein | Händler-Bestellnummer mit 1–128 Zeichen. Ohne Angabe wird sie erzeugt; zu lange Werte werden abgelehnt statt gekürzt. |
amount | Ja | Positive ganze Zahl in der kleinsten Währungseinheit. 2990 entspricht 29,90 USD. Zeichenfolgen, Dezimalzahlen und negative Werte werden abgelehnt. |
currency | Nein | USD, HKD oder CNY; Standard ist USD. Alle drei sind in der Sandbox verfügbar. Live gelten nur für Ihr Konto freigeschaltete Währungen, sonst folgt 400 invalid_request. |
subject | Nein | Artikelbezeichnung mit höchstens 255 Zeichen. Längere Angaben werden abgelehnt. |
notify_url | Bedingt | Öffentliche HTTPS-URL für bestellbezogene asynchrone Benachrichtigungen. Auch die Sandbox weist localhost und private Adressen mit 400 zurück; nutzen Sie für lokale Tests einen öffentlichen Tunnel. |
return_url | Nein | Browser-Ziel des Käufers nach erfolgreicher Zahlung. Diese Weiterleitung ist keine Zahlungsbestätigung. |
Ohne notify_url braucht eine Live-Bestellung mindestens einen aktivierten Live-Webhook-Endpunkt für payment.succeeded. Eine bestellbezogene URL hat Vorrang vor der normalen Endpunktverteilung.
Die erste Erstellung liefert HTTP 201, ein identischer Wiederholungsversuch mit derselben Händlernummer HTTP 200 und abweichende Bestelldaten HTTP 409.
Checkout-Sprache
Der Checkout unterstützt Chinesisch und Englisch. Standardmäßig folgt er der Browsersprache des Käufers und nutzt sonst Englisch. Ergänzen Sie &locale=en oder &locale=zh an checkout_url, um eine Sprache festzulegen.
Rückkehr zu Ihrer Website
Nach der Zahlung zeigt der Checkout einen Beleg und leitet nach etwa fünf Sekunden zu return_url weiter. Käufer können sofort zurückkehren oder bleiben. Ein bereits bezahlter Link leitet beim erneuten Öffnen nicht automatisch weiter.
| Platzhalter | Ersetzt durch |
|---|---|
{TRADE_NO} | KukoPay-Transaktionsnummer |
{OUT_TRADE_NO} | Ihre Händler-Bestellnummer |
https://shop.example.com/orders/{OUT_TRADE_NO}/completeDie Browser-Rückkehr beweist keine Zahlung; Käufer können die Seite schließen. Erfüllen Sie erst nach geprüftem Webhook oder Bestellabfrage.
Markenauftritt
Legen Sie Händlername, Logo und Markenfarbe im Portal unter Konto → Marke und Checkout fest. Die Einstellungen gelten für Sandbox und Live; ohne Konfiguration erscheint der bei der Registrierung angegebene Firmenname.