Vytvoření platby (charge)

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

API voláním, kterým dokončíte platbu Twisto, je volání endpointu /charges.

Toto volání se provádí až poté, co od Twisto obdržíte výsledek schváleného checkoutu.

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

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

Toto API volání obsahuje:

Oprávnění (authority)
Referenci (volitelné)
Částku
Měnu
Příznak capture

Odpověď API Twisto obsahuje:

Id platby — jedinečný identifikátor charge pro refundace nebo flow zrušení / zachycení
Stav — aktuální stav platby (authorized captured cancelled refunded error)
Zachycenou částku
Refundovanou částku
Číslo účtenky — jedinečný identifikátor pro zákazníka, tiskne se na účtenkách

Validace stavu
Pokud ve svém systému validujete hodnotu state v odpovědi, ujistěte se, že akceptujete výše uvedené hodnoty jako úspěšné odpovědi.

Toto volání /charges by mělo probíhat z vašeho serveru, nikoli přímo z klientského frontendu.

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

Oprávnění (authority)

Twisto ke zpracování platby vyžaduje token oprávnění. Bude to:

Id checkoutu získané z prvního API volání Twisto

Příklad předání těchto informací:

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

Údaje o platbě

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

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

Příklady předání těchto informací:

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

Příznak capture

Při vytvoření platby je nutné určit, zda se mají prostředky okamžitě zachytit, nebo pouze autorizovat (viz Registrace obchodníka). Twisto to předáte 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
}

Okrajové 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, jak situaci řešit:

Poslat hlavičku idempotence u požadavku ChargeCreate podle popisu v části transakční API volání.
Zavolat ChargeList (viz API reference | ChargeList) a v odpovědi najít platbu podle reference.
- Buď na CheckoutCreate pošlete jedinečný řetězec reference, 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 snazší vyhledávání

Úspěšnou odpovědí od Twisto jste platbu dokončili!