Vytvoření checkoutu (PSP)

Naučte se vytvářet checkout v PSP API Twisto včetně typu platebního produktu, reference obchodníka, údajů o zákazníkovi, informací o objednávce, historie transakcí a konfigurace.

Prvním API voláním při zpracování platby Twisto je volání endpointu /checkouts. Toto volání provedete ve chvíli, kdy si zákazník zvolí Twisto jako platební metodu u transakce.

Toto API volání obsahuje:

Typ platebního produktu a reference obchodníka
Údaje o zákazníkovi
Informace o objednávce
Konfigurační informace

Odpověď API Twisto obsahuje:

Id checkoutu — identifikaci nově vytvořeného checkoutu
URL pro přesměrování — přesměruje zákazníka do platebního flow Twisto, kde dokončí žádost nebo se přihlásí ke svému účtu Twisto a potvrdí platbu.

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

sequenceDiagram actor Customer Customer->>Client: Go to payment page Client->>Server: Send order information Server->>Twisto: POST /checkoutCreate Twisto->>Server: Return new Checkout Server->>Client: Return checkout ID and URL Client->>Customer: Redirect customer to URL

Typ platebního produktu

Ve volání /checkouts určíte, který platební produkt se má u nákupu použít. Děje se to v poli "type":, které může mít hodnotu "standard" pro produkt Twisto Pay nebo "pay-in-three" pro produkt Rozloženo na 3 platby. Pokud pole vynecháte, použije se standardní Twisto Pay.

Volání checkoutu pro Twisto Pay:

{
  "type": "standard"
}

Volání checkoutu pro Rozloženo na 3 platby:

{
  "type": "pay-in-three"
}

Více o produktech a dostupnosti v jednotlivých zemích najdete v článku Jak Twisto funguje

Volání /checkouts musí také určit obchodníka, za kterého se volání provádí. Použijte pole "merchant_reference" s ID obchodníka:

{
  "merchant_reference": "string"
}

Údaje o zákazníkovi

Twisto vyžaduje při checkoutu předat určitá data o zákazníkovi. Pole jsou závislá na zemi:

E-mailová adresa — povinné
Jméno a příjmení — volitelné
Mobilní telefon — volitelné
Fakturační adresa — volitelné

I když jsou některé údaje o zákazníkovi volitelné, důrazně doporučujeme je ve volání /checkouts uvádět.

Pokud je ve volání /checkouts nezašlete, zákazník je bude muset doplnit ručně.

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

"shopper": {
    "first_name": "John",
    "last_name": "Smith",
    "phone": "+48 450 000 000",
    "billing_address": {
      "line1": "Boleslawicka",
      "line2": "24/13",  // Or add street number to `line1` and omit `line2`
      "city": "Warszawa",
      "postal_code": "03-352",
      "country": "PL"
    },
    "personal_id": "51012285271",
    "email": "john.smith@example.com"
  }

Informace o objednávce

Twisto dále vyžaduje v požadavku na checkout údaje o objednávce, mimo jiné:

Reference (volitelné) — jedinečné id objednávky ve vašem systému
Částka
Měna
Položky (volitelné)

Částka objednávky

"amount" objednávky je součet všech položek ("amount" × "quantity" u každé položky "item").

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

"order": {
    "reference": "id_generated_by_the_merchant",
    "amount": 41.2,
    "currency": "PLN",
}

Položky

Když zákazník naplní košík, tyto údaje můžete předat v požadavku /checkouts Twisto.

Částka položky

"amount" položky je cena jedné jednotky.

Pole položek je volitelné. Pokud ho však do volání zahrnete, je pole "type": u položky povinné a může nabývat hodnot: "sku", "tax", "shipping", "discount", "store_credit". Maximální počet položek typu "tax", "shipping" a "discount" je 1.

Níže je příklad, jak to může vypadat:

"items": [
      {
        "name": "Headphones",
        "amount": 20.6,
        "quantity": 2,
        "type": "sku",
        "reference": "string"
      }
    ]

Slevy

Většina e‑shopů podporuje slevové kódy nebo akce. Aby součty v checkoutu seděly, je potřeba tyto částky slev předat Twisto v API volání /checkouts. Postupujte tak, že do checkoutu přidáte další položku s 'type: discount', např.:

"items": [
      {
        "name": "Loyalty Discount",
        "amount": -20,
        "quantity": 1,
        "type": "discount"
      }
]

Historie transakcí

Abychom zákazníka správně vyhodnotili, mimo jiného nahlížíme do minulých transakcí s obchodníkem. Informace zahrnují například:

Vytvoření účtu a poslední přihlášení
Utracenou částku
Typ platby a měnu
Refundovanou částku

Čím více informací v historii transakcí uvedete, tím spíše transakce projde kontrolami rizikového enginu a proběhne.

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

"shopper": {
  "statistics": {
    "account_created": "2019-08-24T14:15:22Z",
    "sales_total_count": 1,
    "sales_total_amount": 41.2,
    "sales_avg_amount": 41.2,
    "sales_max_amount": 41.2,
    "refunds_total_amount": 0,
    "previous_chargeback": true,
    "currency": "PLN",
    "last_login": "2019-08-24T14:15:22Z",
    "has_previous_purchases": true,
    "fraud_check_result": "pass"
  },
}

Konfigurační informace

Závěrečná část těla požadavku na checkout řekne Twisto správnou adresu pro návrat zákazníka poté, co projde platebním procesem Twisto. redirect_uri je vaše cílová URL, na kterou Twisto zákazníka přesměruje a připojí výsledek a id checkoutu

"config": {
    "redirect_uri": "https://redirect_uri.yourserver.com/"
}

Příklad návratu po úspěšném potvrzení objednávky:

https://redirect_uri.yourserver.com/?checkout_id=xxxxxxxxxxxxxxxxxxxx&status=authorized

Očekávané chyby

Tabulka chyb, které API může na váš požadavek vrátit:

Stav	Kód	Zpráva	Popis
400	`malformed_request`	`Invalid JSON`	Tělo požadavku není platné JSON.
400	`malformed_request`	`Request body issue`	Některá pole nejsou platná. Např. `"details": [{'message': '"a" is not a valid choice.', 'name': 'type'}]`
400	`error`	`Merchant does not exist`	Obchodník pro zadanou `merchant_reference` neexistuje.
400	`error`	`Eshop has a merchant that was blocked`	{{Message}}.
400	`error`	`It has to be unique`	Reference objednávky musí být jedinečná.
403	`forbidden`	`Forbidden credentials for given hostname`	Vaše přihlašovací údaje nejsou na tomto hostname platné.
403	`forbidden`	`Customer has installments blocked`	Checkout byl pro tohoto zákazníka zamítnut, protože: {{Message}}.
403	`forbidden`	`Customer is overdue`	Checkout byl pro tohoto zákazníka zamítnut, protože: {{Message}}.
403	`forbidden`	`Customer has terminated contract`	Checkout byl pro tohoto zákazníka zamítnut, protože: {{Message}}.
403	`forbidden`	`Installments over customer limit`	Checkout byl pro tohoto zákazníka zamítnut, protože: {{Message}}.
403	`forbidden`	`Customer is over monthly installments limit`	Checkout byl pro tohoto zákazníka zamítnut, protože: {{Message}}.
403	`forbidden`	`Unpaid amount not large enough`	Částka objednávky není pro tento typ produktu dostatečně vysoká.

Po vytvoření objednávky

Po úspěšné odpovědi API /checkouts je potřeba:

Uložit id vrácené API k záznamu objednávky / košíku
Přesměrovat zákazníka na URL vrácené API

Po přesměrování uvidí zákazník platební stránku Twisto a pokračuje v nákupu.

Po dokončení tohoto kroku bude zákazník přesměrován zpět na váš web, konkrétně na redirect_uri, které jste v požadavtu /checkouts předali Twisto.

K této URL budou připojeny dvě klíčové hodnoty, které by váš kód měl zpracovat a vhodně obsloužit.

https://redirect_uri.yourserver.com/?checkout_id=xxxxxxxxxxxxxxxxxxxx&status=authorized

Stav

Stav žádosti zákazníka / potvrzení objednávky. Může nabývat jedné ze čtyř možností:

captured — Objednávka byla schválena a aktivována — tento stav platí jen při zapnutém okamžitém zachycení (immediate capture)
authorized — Objednávka byla přijata a je připravena k zaúčtování (charge)
rejected — Objednávka byla zamítnuta ze skóringových důvodů
error — Při objednávce došlo k chybě

Vaše objednávka ještě NENÍ dokončena

Tento výsledek ani v případě schválení neznamená, že je platební proces hotový. Potvrzuje jen, že má zákazník na účtu Twisto k dispozici prostředky na objednávku a že Twisto i zákazník schválili použití tohoto id checkoutu k vytvoření platby (charge).

Neplatí, pokud jste při registraci obchodníka zvolili režim Immediate Capture — v tom případě je objednávka dokončena.

Id checkoutu

Stejná hodnota, kterou jste po úspěšné odpovědi API /checkouts uložili k objednávce / košíku.

Tuto hodnotu použijte k identifikaci košíku spojeného s výsledkem.

Dokončete platbu (charge)

Jakmile je objednávka ve stavu schválena, stav obdržíte webhookem i v přesměrovací URL od Twisto a můžete vytvořit platbu (charge).