Create a Checkout

Learn how to create a checkout using the Twisto API, including payment product types, customer details, order information, transaction history, and configuration options.

The first API call you will make in processing a Twisto payment is a call to our /checkouts endpoint. This request is made once a customer chooses Twisto as their payment method for a transaction.

This API call will contain:

Type of payment product
Customer details
Order information
Configuration information

The Twisto API response will contain:

A checkout Id - to identify the newly created checkout
A redirect url - to redirect the customer to the Twisto checkout flow where they will complete their application or log in to their Twisto account to confirm the payment.

This /checkouts API call should be made from your server and not directly from the client front end.

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

Type of Payment product

In the /checkouts call you will determine which Payment product is to be used for the purchase. This is done in the field "type": which can have value "standard" for a Twisto Pay payment product or "pay-in-three" for a Pay in 3 payment product. If left blank, standard Twisto Pay is used.

Checkouts call for Twisto Pay:

{
  "type": "standard"
}

Checkouts call for Pay in 3:

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

For more details about the products and availability in selected countries, please refer to How Twisto works

Customer details

Twisto requires certain customer details to be passed at the time of checkout. This data fields are country specific:

Email address - mandatory
First and Last name - optional
Mobile phone number - optional
Billing Address - optional

Despite some of the customer details being optional, we highly recommend including this information in the /checkouts call.

If this information is not included in the /checkouts call, the customer will need to fill it in manually.

Here is an example of how this information can be passed:

"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"
  }

Order information

Twisto also requires details of the order to be passed in the Checkout request, including:

Reference (optional) - this is a unique order ID you use in your system
Amount
Currency
Items (optional)

Amount of the order

Order "amount" is the sum amount of all individual items ("amount" * "quantity" per each "item").

Here are some examples of how this information can be passed:

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

Items

When a customer fills their cart, these details could be passed in the /checkouts request to Twisto.

Amount of the item

Item "amount" is the price of each individual unit.

Items array is optional. However if you include it in the call, then item "type": is required field and can have following values: "sku", "tax", "shipping", "discount", "store_credit". Note that the maximum capacity of "tax", "shipping" and "discount" is 1.

Below is an example of how this could look:

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

Discounts

The majority of ecommerce websites support some form of discount code or promotion feature. In these scenarios, in order for the checkout sums to add up as expected, Twisto requires these discount amounts to be passed to us in the /checkouts API call. The way this should be handled, is by simply adding an additional 'item' to the checkout of 'type: discount' e.g.

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

Transaction history

In order to correctly process and evaluate the customer, we are among other things looking into past transactions with the Merchant. This information include:

Account creation and last login
Amount purchased
Payment type and currency
Amount refunded

The more information you include in the Transaction history, the more likely it is that the transaction would pass our risk engine checks and will go through.

Here is an example of how this information can be passed:

"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"
  },
}

Configuration information

This is the final part of the checkouts request payload that will give Twisto the correct address to return the customer, AFTER they have gone through the Twisto payment process. The redirect_uri is simply your desired url, where Twisto will redirect the customer, appending the status and checkout Id

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

Here is an example of how Twisto would return a successful order confirmation:

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

Expected errors

Here is a table of errors that API may return for your request:

Status	Code	Message	Description
400	`malformed_request`	`Invalid JSON`	The request body is not a valid JSON.
400	`malformed_request`	`Request body issue`	Some of the fields are not valid. E.g. `"details": [{'message': '"a" is not a valid choice.', 'name': 'type'}]`
400	`error`	`Eshop has a merchant that was blocked`	{{Message}}.
400	`error`	`It has to be unique`	Order reference must be unique.
403	`forbidden`	`Forbidden credentials for given hostname`	Your credentials are not valid on this hostname.
403	`forbidden`	`Customer has installments blocked`	Checkout was rejected for this customer because: {{Message}}.
403	`forbidden`	`Customer is overdue`	Checkout was rejected for this customer because: {{Message}}.
403	`forbidden`	`Customer has terminated contract`	Checkout was rejected for this customer because: {{Message}}.
403	`forbidden`	`Installments over customer limit`	Checkout was rejected for this customer because: {{Message}}.
403	`forbidden`	`Customer is over monthly installments limit`	Checkout was rejected for this customer because: {{Message}}.
403	`forbidden`	`Unpaid amount not large enough`	Order amount is not large enough for this type of product.

After you have created an Order

Once you have received a successful /checkouts API response, you will need to:

Store the 'id' returned by the API against your order / cart records
Redirect the customer to the url returned by the API

Once redirected, the customer will see the Twisto payment page and they will proceed with the purchase.

After the customer has completed this step, they will be redirected back to your website. Specifically to your 'redirect_uri' that was passed to Twisto in your /checkouts request.

There will be two key values appended to this url that should be consumed by your code and handled appropriately.

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

Status

This is the status of the customer application / order confirmation. This will be one of four possible options:

captured - Order was approved and activated - This status is only relevant when immediate capture is on
authorized - Order was accepted and ready to be charged
rejected - Order was rejected due to scoring reasons
error - There was an error with the order

Your order is NOT complete

This result, even if Approved, does not indicate the payment process is complete. This is simply confirmation from Twisto that the customer account has the available funds for the order and that both Twisto and the customer have approved this checkout ID to be used to create a charge.

Checkout id

This is the same value that was stored against your order / cart records after receiving a successful /checkouts API response.

This value should be used to identify the cart associated with the result.

Complete your charge

Once the order has been in approved, you will receive the status via a webhook and also in redirect URL from Twisto and you can then Create the Charge.