Vytvoření charge

Neplatí, pokud jste při registraci obchodníka zvolili režim Immediate Capture.

Voláním API, kterým dokončíte platbu Twisto, je požadavek na endpoint /charges.

Tento požadavek se provádí až poté, co od Twisto obdržíte schválený výsledek checkoutu.

Stav checkoutu se sděluje webhooky, parametrem v URL přesměrování zpět k obchodníkovi nebo ho lze získat požadavkem GET checkoutRetrieve.

Pokud checkout není schválen, /charges bude zamítnuto

Toto volání API obsahuje:

Authority (zdroj oprávnění)
Referenci (volitelnou)
Částku
Měnu
Příznak capture

Odpověď Twisto API obsahuje:

ID charge — jedinečná reference pro refundace nebo tok zrušení / zachycení
State — aktuální stav charge (authorized captured cancelled refunded error)
Zachycenou částku
Refundovanou částku
Číslo účtenky — jedinečná reference pro zákazníka, tisk na účtenkách

Validace stavu

Pokud ve svém systému validujete hodnotu state v odpovědi, ujistěte se, že akceptujete všechny výše uvedené hodnoty jako úspěšné odpovědi tam, kde to dává smysl.

Volání /charges musí probíhat z vašeho serveru, ne přímo z klientského frontendu.

sequenceDiagram actor Customer participant Client Server->>Twisto: POST /charges using ID Twisto->>Server: Return Charge with status 'captured'

Authority

Twisto ke zpracování charge vyžaduje token authority. Bude to:

ID checkoutu z prvního volání API na Twisto

Příklad předání:

"authority": {
    "type": "checkout_id",
    "value": "string"
}

Podrobnosti charge

Twisto vyžaduje při charge předat následující údaje:

Reference (volitelná) — u manuálního vypořádání se zobrazí v bankovní transakci. Pokud ji neuvedete, vygenerujeme náhodnou
Částka
Měna
Příznak capture

Příklady:

{
  "reference": "your_order_ reference",
  "amount": 300,
  "currency": "EUR"
}

Příznak capture

Při vytvoření charge je nutné určit, zda se prostředky mají okamžitě zachytit, nebo pouze autorizovat (viz Registrace obchodníka). Předáte to například takto:

{
  "capture": true
}

Celý požadavek

Příklad těla požadavku:

{
  "authority": {
    "type": "checkout_id",
    "value": "string"
  },
  "reference": "your_order_reference",
  "amount": 300,
  "currency": "EUR",
  "capture": true
}

Mezní případy

Žádná odpověď kvůli chybě sítě

Bez odpovědi nelze zavolat ChargeRetrieve, protože neznáte ID ani to, zda byl požadavek úspěšný.

Existují 2 způsoby řešení:

Posílejte hlavičku idempotence u požadavku ChargeCreate podle popisu v části transakční volání API.
Zavolejte ChargeList (viz API reference | ChargeList) a v odpovědi charge najděte podle reference.
- Buď pošlete jedinečný řetězec reference u CheckoutCreate, nebo je objednávce přiřazena náhodná reference, kterou obdržíte v odpovědi CheckoutCreate.
- ChargeList navíc umožňuje filtrovat podle data a času a stránkovat pro snadnější výběr

Úspěšnou odpovědí od Twisto máte charge dokončenou.