Share
Explore

Twig checkout API documentation v1

NOTE: documentation has moved to another page:
twig documentation
⁠
.
Flow diagram

⁠
twigflow.png
⁠
⁠


Order Flow

The merchant site calls v1/operations/order/init to initiate the Twig checkout process.

⁠
twig1.png
⁠
⁠

2. Then the merchant’s site redirects the user to Twig checkout page referring to the URL in response from operations/order/init
⁠
twigstep3.png
⁠
⁠
3. The user will confirm 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 v1/payment/capture and finalizes it.
⁠
twig2.png
⁠
⁠
5. Twig proceeds with order processing and updates the merchant with the latest status , success or failure.


API

NOTE: every date value is in ISO8601
⁠
POST v1/operations/order/init

Merchant makes a POST request to v1/operations/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
country
postalCode
countryCode
lineItems - items purchased by the user
itemId - merchant’s unique id for the item
name
description
category
categoryHierarchy - optional: an array with category details for an item i.e [’T-Shirt’,’Polo’,’Red’]
metadata - optional: json object representing all properties for an item etc
quantity
amount
tax
imageUrl
dateCreated - merchant’s order creation date
merchant - merchant configs - optional, if not provided will be populated by merchant configs from the registration
confirmUrl - user confirms and authorizes the payment
cancelUrl - user cancels the order
validationUrl - URL to validate the order after user has authorized it
requiresValidateCallbackSuccess - should Twig wait for merchant response on order validation , this variable determines whether Twig should capture the order or cancel it (in case of merchant server does not response).
pushUrl - used to notify the merchant with the status of the order (i.e when an order is completed)
captureOnExpire - if there is an authorization for an order, should it be captured after authorization ends.
customer
firstName
lastName
email
phoneNumber - optional
locale - i.e “en-US”

Optional
billing - billing address. Contains address object from the shipping field above.
Expiration of the order on expiration - emerchant platform - if empty we set it to 1 week on our system.
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://redirectUrl/{orderId}
order - order data
orderId - Twig’s order unique id.
merchantOrderReference - Merchant’s order unique id.
amount - described above
customer - described above
lineItems - described above
shipping - described above
billing - described above
merchant - described above
expiration
dateCreated - Order creation date on Twig system
4XX BAD REQUEST - payload format incorrect
5XX SERVER ERROR - twig error
Authorization header
x-api-key askjdh209ausdjasdasdiasd9as
twig-api-version 2022-01-01
Example payload
{
"merchantOrderReference":"32123dsf",
"dateCreated":"2021-11-09T18:32:04.646+00:00",
"amount": {
"currencyCode": "USD",
"value": "1500.00",
"breakdown": {
"items": "1450.00",
"shipping":"30.00",
"tax": "20.00"
}
},
"customer":{
"firstName":"taulant",
"lastName":"taulant",
"email": "taulant@taulant.com"
},
"lineItems": [
{
"itemId":"123",
"name": "T-Shirt",
"description": "Green XL",
"imageUrl":"imageurl",
"amount": "90.0",
"tax": "10.00",
"quantity": "1",
"categoryHierarchy":["T-shirt","Polo","RED"],
"metadata":"some metadata",
"category": "PHYSICAL_GOODS"
},
{
"itemId":"321",
"name": "Shoes",
"description": "Running, Size 10.5",
"imageUrl":"imageurl",
"amount":"45.00",
"tax": "5.00",
"quantity": "2",
"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",
"country": "CA",
"postalCode": "94107",
"countryCode": "US"
}
},
"billing":{
"address":{
"firstName": "John",
"lastName": "Doe",
"addressLine1": "123 Townsend St",
"addressLine2": "Floor 6",
"city": "San Francisco",
"country": "CA",
"postalCode": "94107",
"countryCode": "US"
}
}
}
⁠
GET v1/operations/order/{orderId}

Retrieves an order.
Payload
Required:
orderId - Twig’s order unique id.
Returns:
200 OK
order object details
"orderId":"2asd213123asd",
"merchantOrderReference": "merchant_order_id",
"merchantDateCreated":"2021-04-20T18:32:04.646+00:00",
"dateCreated":"2021-04-20T18:32:04.646+00:00",
"status":"CAPTURED",
"reason":"",
"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",
"locale":"en-US"
},
"lineItems": [
{
"itemId":"123",
"name": "T-Shirt",
"description": "Green XL",
"amount": "90.0",
"tax": "10.00",
"quantity": "1",
"imageUrl":"https:///....",
"category": "PHYSICAL_GOODS",
"categoryHierarchy":"["PHYISCAL_GOODS"],
"metadata":<json object>
},
{
"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",n
"country":"Los Angeles",
"postalCode":"231212",
"countryCode:"US"
},
"billing": {
"address": {
"firstName": "John",
"lastName": "Doe",
"addressLine1": "123 Townsend St",
"addressLine2": "Floor 6",
"city": "San Francisco",
"country": "CA",
"postalCode": "94107",
"countryCode": "US"
}
},
"operations":[{type:"VOID"},{type:"CAPTURE"}],
"merchant":{
"confirmUrl":"merchant.confirm.redirect.url",
"cancelUrl":"merchant.cancel.redirect.url",
"validationUrl":"merchant.validate.order",
"pushUrl": "merchant.push.url",
"requiresValidateCallbackSuccess":true,
"captureOnExpire":false
}
4XX BAD REQUEST - payload format incorrect
5XX SERVER ERROR - twig error
Authorization header
x-api-key askjdh209ausdjasdasdiasd9as
twig-api-version 2022-01-01
⁠
PATCH v1/operations/order/

Merchant makes a PATCH request to /order/ to update parts of the order or as a whole. Updating requires a specific format.
NOTE: Twig does not recalculate values i.e when an item is deleted from the lineItems we expect all recalculation such as the whole amount , taxes, shipping to be updated from the merchant and be send together in the format specified below.
The value object should contain fields that are to be updated and be a string literal. Refer to examples below.
Objects that do not contain list of other objects
{
“operation”:”UPDATE”,
“field”:”amount”,
“value”:fields to be updated
}
2. Field that contains list of objects identifiable via id such as lineItems.
{
“operation”:”UPDATE”,
“field”:”lineItems”,
“id”:”itemId”,
“value”:fields to be updated
}
3. Delete operation works only for lineItems field.
{
“operation”:”DELETE”,
“field”:”lineItems”,
“id”:”itemId”,
}
Payload examples

orderId:Twig's orderId,
updateItems:[
{
"operation":"UPDATE",
"field":"amount",
"value":"{\"currencyCode\":\"USD\",\"value\":111,\"breakdown\":{\"items\":111,\"shipping\":111,\"tax\":111}}"
},
{
"operation":"UPDATE",
"field":"billing",
"value":"{\"address\":{\"country\":\"XK\",\"postalCode\":\"10000000000\",\"countryCode\":\"XK&AL\"}}"
},
{
"operation":"DELETE",
"field":"lineItems",
"id":"itemId"
}
]

Returns:
200 OK
order detail object with the new changes
"orderId":"2asd213123asd",
"merchantOrderReference": "merchant_order_id",
"merchantDateCreated":"2021-04-20T18:32:04.646+00:00",
"dateCreated":"2021-04-20T18:32:04.646+00:00",
"status":"CAPTURED",
"reason":"",
"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",
"locale":"en-US"
},
"lineItems": [
{
"itemId":"123",
"name": "T-Shirt",
"description": "Green XL",
"amount": "90.0",
"tax": "10.00",
"quantity": "1",
"imageUrl":"https:///....",
"category": "PHYSICAL_GOODS",
"categoryHierarchy":"["PHYISCAL_GOODS"],
"metadata":<json object>
},
{
"itemId":"321",
"name": "Shoes",
"description": "Running, Size 10.5",
"amount":"45.00",
"tax": "5.00",
"quantity": "2",
"imageUrl":"https:///....",
"category": "PHYSICAL_GOODS"
}
],
"operations":[{type:"VOID"},{type:"CAPTURE"}],
"shipping": {
"method": "United States Postal Service",
"amount":"20",
"address": {
"firstName": "John",
"lastName": "Doe",
"addressLine1": "123 Townsend St",
"addressLine2": "Floor 6",
"city": "San Francisco",n
"country":"Los Angeles",
"postalCode":"231212",
"countryCode:"US"
}
"merchant":{
"confirmUrl":"merchant.confirm.redirect.url",
"cancelUrl":"merchant.cancel.redirect.url",
"validationUrl":"merchant.validate.order",
"pushUrl": "merchant.push.url",
"requiresValidateCallbackSuccess":true,
"captureOnExpire":false
}

4XX BAD REQUEST - payload format incorrect
5XX SERVER ERROR - twig error
Authorization header
x-api-key askjdh209ausdjasdasdiasd9as
twig-api-version 2022-01-01
⁠
⁠
POST v1/payment/order/capture/

Requests Twig to capture the order.
Payload
Required:
orderId - Twig’s order unique id.
id - random UUID v4, will be used as idem-potency key.
amount - to be captured
currencyCode
dateCreated
message - merchant message for the capture
Returns:
200 or 202
4XX BAD REQUEST - payload format incorrect
5XX SERVER ERROR - twig error
Authorization header
x-api-key askjdh209ausdjasdasdiasd9as
twig-api-version 2022-01-01
⁠
POST v1/payment/order/refund

Refunds an order. An order can be refunded after it is completed or partial captures have been done.
Payload
Required:
orderId - Twig’s order unique id.
id - random UUID v4 to be used as idempotency key
amount - amount(number of type string) to be refunded
currencyCode
dateCreated
message
Returns:
200 or 202
4XX BAD REQUEST - payload format incorrect
5XX SERVER ERROR - twig error
Authorization header
x-api-key askjdh209ausdjasdasdiasd9as
twig-api-version 2022-01-01
⁠
POST v1/operations/order/cancel

Noted: order cannot be cancelled if already Cancelled or Captured(instead refund it)
Payload
Required:
orderId - Twig’s order unique id.
id - random UUID v4
dateCreated
message
Returns:
200 or 202
4XX BAD REQUEST - payload format incorrect
5XX SERVER ERROR - twig error
Authorization header
x-api-key askjdh209ausdjasdasdiasd9as
twig-api-version 2022-01-01
⁠
Merchant 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. This step happens just after user has authorized the order from the front-end.
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
4XX BAD REQUEST - payload format incorrect or the order was not correct
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
reason - reason incase of errors
updatedAt - date when status was updated
Expected result:
200 OK
5XX SERVER ERROR - merchant error

Before you respond to a webhook, you need to verify that the webhook was sent from Twig. You can verify the webhook by calculating a digital signature. Each webhook request contains a base64 encoded HMAC sent over headers: twig-hmac, signed by merchant’s API key.
Timestamp (UNIX time as string) is also included in the header to protect against reply attacks. Timestamp is set to now + 15 mins.
Headers
twig-hmac lksdf932jaskdjaskdj29akjsad92
timestamp 1312312323424
Example verifying the HMAC (Nodejs)
To construct the payload append timestamp to the body payload like in the example below.
const payload = `${JSON.stringify(msg)}{twig-timestamp}`
let hmac = crypto.createHmac('sha256', "apiKey").update(payload).digest("base64");
//test if twig-hmac === hmac
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.