Share
Explore

Twig checkout API documentation v1

Flow diagram

twig checkout.png




Order Flow

The merchant site calls
/order/init
to initiate the
Twig
checkout process.
twig 1.png
2. Then the merchant’s site redirects the user to
Twig
checkout page referring to the URL in response from
/order/init
twigstep3.png
3. The user will confirm (validating their assets) the order and authorize the payment then it will be redirected to merchant’s confirmation URL (or cancel URL, depends on the confirmation success).
confirmauthorize.png
4. The merchant creates the order by capturing it via
POST /payments/capture
and finalizes it.
capture.png
5.
Twig
proceeds with order processing and returns with a success or failure.




API

Base URL to use for testing:
https://checkout.dev.cartediem.org


POST
/operations/order/init


Merchant makes a POST request to /order/init to initiate the
Twig
checkout process and in return receives the order data and checkoutUrl.

Payload

Required:
merchantOrderReference -
merchant’s unique id for the order
amount -
order total amount with breakdown (items, tax, shipping)
currencyCode -
currency code
value -
total
amount for the order
breakdown -
total amount breakdown by
items, tax, shipping
items -
total amount for items
tax -
total tax amount
shipping -
total shipping amount
shipping -
shipping details
method
amount -
total amount of shipping
address -
address of the user
firstName
lastName
addressLine1
addressLine2 (optional)
city
state
postalCode
countryCode
lineItems -
items purchased by the user
itemId -
merchant’s unique id for the item
name
description
category
quantity
amount
tax
imageUrl
merchantDateCreated -
merchant’s order creation date
merchant -
merchant configs
redirectConfirmUrl -
user confirms and authorizes the payment
redirectCancelUrl -
user cancels the order
validateOrderUrl
- URL to validate the order before authorizing it
pushUrl
- used to notify the merchant with the status of the order (i.e when an order is completed)
requiresValidationSuccess
- if merchant wants to validate the order (via validateOrderUrl) and there is a connection timeout, this variable determines whether Twig should capture the order or cancel it.
requiresCapture
- if there is an authorization for an order, should it be captured after authorization ends.
customer
firstName
lastName
email
phoneNumber
- optional

Optional
billing -
billing address. Contains
address
object from the
shipping
field above.
expiration -
expiration of the order on merchant platform

Returns
:

200 OK
checkoutUrl -
URL to redirect to
Twig
checkout.
Note:
when redirecting append the orderId as path variable to the URL i.e https://twig.netlify.app/checkout/orderId
checkoutExpiration -
checkout expiration on user’s side. If it expires the whole process should start from beginning with operations/order/init
expiration -
order expiration
order -
order data
orderId
-
Twig’s
order unique id.
merchantOrderReference -
Merchant’s order unique id.
clientId -
merchant unique id
amount -
described above
customer -
described above
lineItems -
described above
shipping -
described above
billing -
described above
merchantDateCreated -
Order creation date from merchant
4XX BAD REQUEST -
payload format incorrect
5XX SERVER ERROR -
twig error

Authorization header

API-TOKEN askjdh209ausdjasdasdiasd9as

Body

{
"merchantOrderReference": "merchant_order_id",
"merchantDateCreated":"2021-04-20T18:32:04.646+00:00",
"amount": {
"currencyCode": "USD",
"value": "240.00",
"breakdown": {
"items": "180.00",
"shipping":"30.00",
"tax": "20.00"
}
},
"customer":{
"firstName":"bllablal",
"lastName":"bllablla",
"email":"email@email.com",
"phoneNumber":"+332212323"
},
"lineItems": [
{
"itemId":"123",
"name": "T-Shirt",
"description": "Green XL",
"amount": "90.0",
"tax": "10.00",
"quantity": "1",
"imageUrl":"https:///....",
"category": "PHYSICAL_GOODS"
},
{
"itemId":"321",
"name": "Shoes",
"description": "Running, Size 10.5",
"amount":"45.00",
"tax": "5.00",
"quantity": "2",
"imageUrl":"https:///....",
"category": "PHYSICAL_GOODS"
}
],
"shipping": {
"method": "United States Postal Service",
"amount":"20",
"address": {
"firstName": "John",
"lastName": "Doe",
"addressLine1": "123 Townsend St",
"addressLine2": "Floor 6",
"city": "San Francisco"
}
"merchant":{
"redirectConfirmUrl":"merchant.confirm.redirect.url",
"redirectCancelUrl":"merchant.cancel.redirect.url",
"validateOrderUrl":"merchant.validate.order",
"pushUrl": "merchant.push.url",
"requiresValidationSuccess":true,
"requiresCapture":false
}
}

POST
/payments/order/capture


Merchant makes a POST request to
/payments/order/capture
to notify
Twig
that it can proceed with the payment and finalize the order.

Note: order should be authorized by the user from the checkout client before capturing it.

Payload

Required:
orderId
-
Twig’s
order unique id.

Returns
:

200 OK
orderId
status
reason -
if any error or order capture fail
4XX BAD REQUEST -
payload format incorrect
5XX SERVER ERROR -
twig error

Authorization header

API-TOKEN askjdh209ausdjasdasdiasd9as

Body

{
"orderId" : "2132kasdad-23askdasd"
"status": "status",
"reason":"reason"
}

GET
/operations/order/{orderId}


Retrieves an order.

Payload

Required:
orderId
-
Twig’s
order unique id.

Returns
:

200 OK
order object with details
4XX BAD REQUEST -
payload format incorrect
5XX SERVER ERROR -
twig error

Authorization header

API-TOKEN askjdh209ausdjasdasdiasd9as

GET
/operations/order/cancel/{orderId}


Cancels an order.

Payload

Required:
orderId
-
Twig’s
order unique id.

Returns
:

200 OK
orderId
status
4XX BAD REQUEST -
payload format incorrect
5XX SERVER ERROR -
twig error

Authorization header

API-TOKEN askjdh209ausdjasdasdiasd9as



Webhooks

Webhooks will be used by the merchant to be notified from the twig services.

POST
merchant/validateOrderUrl

This webhook will be used to validate the order before processing it

Payload

orderId -
Twig’s
order unique id.
merchantOrderReference - merchant’s order id
amount
lineItems
shipping
billing
merchant - object will contain merchant urls provided during the order init
merchantDateCreated

Expected result
:

200 OK
orderId
valid
reason - if order was invalid
4XX BAD REQUEST -
payload format incorrect
5XX SERVER ERROR -
merchant error

POST
merchant/pushUrl

Since the processing is asynchronous this webhook will be used to notify the merchant for order status updates.

Payload

orderId -
Twig’s
order unique id.
status - order status
updatedAt - date when status was updated

Expected result
:

200 OK

4XX BAD REQUEST -
payload format incorrect
5XX SERVER ERROR -
merchant error
Want to print your doc?
This is not the way.
Try clicking the ⋯ next to your doc name or using a keyboard shortcut (
CtrlP
) instead.