Share
Explore

Twig checkout API documentation v1

NOTE: documentation has moved to another page: .

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.