This section will describe the Intents API overview, the request and response example.
Overview
To directly initiate an intent, submit a request to create an intent using the Create an Intent endpoint. All intents are identified by unique intent_ids. You can also retrieve an intent, cancel an intent, or retrieve a list of intents.
Intent Payment Request
Sample
curl --request POST \
--url https://api.tap.company/v2/intent/ \
--header 'accept: application/json' \
--header 'authorization: Bearer sk_test_XKokxxxg5sLPjhJ' \
--header 'content-type: application/json' \
--data '
{
"scope": "CHARGE",
"present_payments": "true",
"idempotent": "xxx",
"merchant": {
"id": "merchant_gfxxx6EP4b733",
"terminal": {
"id": "terminal_Zxxx62Q11H982",
"terminal_device": {
"id": "terminal_device_scTwK252xxx6rt11t883",
"serial_number": "564xxx888"
}
}
},
"order": {
"amount": "1",
"currency": "KWD",
"reference": "xxx",
"items": {
"count": "1",
"list": [
{
"id": "xxx",
"quantity": "1",
"pickup": "false",
"product": {
"id": "xxx",
"amount": "2",
"category": "PHYSICAL_GOODS",
"metadata": {
"cycle": "1"
},
"reference": {
"sku": "stock keeping unit",
"gtin": "global trade item number",
"code": "00dfd",
"financial_code": "0022343"
},
"name": [
{
"text": "Laptop",
"lang": "en"
}
]
}
}
]
},
"discount": {
"type": "F",
"value": "1"
},
"shipping": {
"amount": "1",
"address": {
"type": "home",
"line1": "line1",
"line2": "line2",
"line3": "line3",
"line4": "line4",
"city": "salmyia",
"state": "kuwait",
"country": "kw",
"zip_code": "30003",
"postal_code": "30003"
},
"provider": {
"id": "prov_FFSFAGGAHAAJAJ"
},
"description": [
{
"text": "description",
"lang": "en"
}
],
"recipient_name": [
{
"text": "Name",
"lang": "en"
}
]
},
"metadata": {
"cycle": "1"
},
"description": [
{
"text": "name",
"lang": "en"
}
],
"tax": [
{
"name": "VAT",
"description": "test",
"type": "F",
"value": "1"
}
]
},
"customer": {
"name_on_card": {
"content": "test card",
"editable": "true"
},
"contact": {
"email": "[email protected]",
"phone": {
"country_code": "965",
"number": "650000000"
}
},
"address": {
"type": "home",
"line1": "line1",
"line2": "line2",
"line3": "line3",
"line4": "line4",
"city": "salmyia",
"state": "kuwait",
"country": "kw",
"zip_code": "30003"
},
"name": [
{
"first": "test",
"last": "test",
"middle": "test",
"title": "MR"
}
]
},
"post": {
"url": "https://post-url"
}
}
'Expected Response
Sample
{
"id": "intent_9jLs49261338SeXM160s199",
"created": 1771249129009,
"updated": 1771249133609,
"object": "intent",
"live_mode": "true",
"api_version": "v2",
"feature_version": "v1",
"status": "INITIATED",
"scope": "CHARGE",
"initiator": "POS",
"present_payments": true,
"customer_initiated": true,
"response": {
"code": "100",
"message": "Initiated"
},
"merchant": {
"id": "merchant_RTTwK1726831gdOO11rM1B552",
"name": "terminal testing account terminal testing account KW",
"legacy_id": "68020459",
"terminal": {
"id": "terminal_V6TwK29267453QZY16WW1j510",
"terminal_device": {
"id": "terminal_device_1qTwK2726745xZ6L16PY15383",
"serial_number": "1853590675"
}
},
"payment_provider": {
"technology": {
"id": "technology_EqJf46231515pLzg7GN84113"
},
"institution": {
"id": "payment_facilitator_tlG13723844En8426VA9143"
}
}
},
"authenticate": {
"id": "",
"required": true
},
"charge": {
"save_card": false,
"threeDSecure": true
},
"destinations": {},
"topup": {},
"transaction": {
"card_holder_login": {
"type": "",
"timestamp": ""
},
"reference": "",
"payment_agreement": {
"id": "",
"contract": {
"id": ""
}
}
},
"order": {
"id": "ord_zxQu48261338mtGy16CC14887",
"amount": 10,
"currency": "KWD",
"items": {
"count": 1,
"list": [
{
"id": "itm_8kSQ48261338LJ1x163K1Z888",
"quantity": 1,
"pickup": false,
"product": {
"id": "prd_lJE5482613388P9f16Zg1p888",
"name": [],
"description": [],
"category": "PHYSICAL_GOODS"
}
}
]
},
"metadata": {
"cycle": "1"
}
},
"customer": {
"id": "cus_LV07H4920261638Ru2h1602652",
"name": [
{
"title": "MS",
"first": "Test",
"middle": "",
"last": "Test",
"lang": "EN"
}
],
"name_on_card": {
"content": "Test Test",
"editable": true
},
"contact": {
"email": "[email protected]",
"phone": {
"country_code": "965",
"number": "00000000"
}
},
"address": {
"type": "home",
"line1": "sdfghjk",
"line2": "oiuytr",
"line3": "line3",
"line4": "line4",
"city": "salmyia",
"state": "kuwait",
"country": "kw",
"zip_code": "30003"
}
},
"post": {
"url": "https://webhook.site/2b4d63d3-5da1-45c7-b038-1c065130e4a1"
},
"metadata": {
"terminal_transaction_id": "terminal_transaction_LV4i1c492613387PFd16Eu1t59"
},
"track": {
"id": "trk_2tFp49261338ePX7169Y1c9",
"status": "INTENT_INITIATED",
"activities": [
{
"id": "act_NIfi49261338bIVR16VT1U9",
"action": "INTENT_INITIATED",
"comment": "Intent created",
"created": "2026-02-16T13:38:49.009947344"
}
]
}
}Webhook Response
Sample
{
"id": "intent_8j8750251315D0oR16Mg11U284",
"created": 1765890950285,
"updated": 1765891022759,
"object": "intent",
"live_mode": "false",
"api_version": "v2",
"feature_version": "v1",
"status": "PROCESSED",
"scope": "CHARGE",
"initiator": "POS",
"present_payments": true,
"customer_initiated": true,
"merchant": {
"id": "merchant_gfTwK172593lak526EP4b733",
"name": "Terminal Testing Account for Ahmad Kandel QA",
"legacy_id": "66485316",
"terminal": {
"id": "terminal_ZSTwK2725139feuE162Q11H982",
"terminal_device": {
"id": "terminal_device_scTwK2525139GVVP16rt11t883",
"serial_number": "SM_5641895888"
}
},
"payment_provider": {
"technology": {
"id": "technology_EqJf46231515pLzg7GN84113"
}
}
},
"authenticate": {
"id": "",
"required": true
},
"charge": {
"save_card": false,
"threeDSecure": false,
"charges": [
{
"id": "chg_TS04A5720251316Bo271612422",
"live_mode": false,
"customer_initiated": true,
"api_version": "V2",
"method": "POST",
"status": "CAPTURED",
"amount": 1.65,
"currency": "KWD",
"threeDSecure": false,
"card_threeDSecure": false,
"save_card": false,
"product": "",
"metadata": {
"aid": "A0000000031010",
"creation_time": "2025-12-16T16:16:36",
"provider_terminal_id": "02011685",
"provider_merchant_id": "050001013"
},
"transaction": {
"timezone": "UTC+03:00",
"created": "1765890996000",
"expiry": {
"period": 30,
"type": "MINUTE"
},
"asynchronous": false,
"amount": 1.65,
"currency": "KWD"
},
"card": {
"object": "card",
"first_six": "409054",
"first_eight": "409054xx",
"last_four": "3240",
"brand": "Visa",
"scheme": "KNET"
},
"reference": {
"transaction": "terminal_transaction_mwrl50251315A70Y16t811C478",
"order": "40",
"track": "tck_TS05A5720251316Hk141612770",
"payment": "57162513161277088294"
},
"response": {
"code": "000",
"message": "Captured"
},
"receipt": {
"id": "205716251316121575",
"email": false,
"sms": false
},
"merchant": {
"country": "KW",
"currency": "KWD",
"id": "66485316"
},
"source": {
"id": "src_knet_terminal",
"object": "source",
"on_file": false,
"payment_method": "KNET"
},
"post": {},
"activities": [
{
"id": "activity_TS04A5920251316Rq7x1612512",
"object": "activity",
"created": "1765890996000",
"status": "INITIATED",
"currency": "KWD",
"remarks": "charge - created",
"txn_id": "chg_TS04A5720251316Bo271612422"
},
{
"id": "activity_TS04A5920251316g2R51612522",
"object": "activity",
"created": "1765890996000",
"status": "CAPTURED",
"currency": "KWD",
"remarks": "charge - captured",
"txn_id": "chg_TS04A5720251316Bo271612422"
}
],
"auto_reversed": false,
"intent": {
"id": "intent_8j8750251315D0oR16Mg11U284"
},
"object": "charge"
}
]
},
"destinations": {},
"topup": {},
"transaction": {
"card_holder_login": {
"type": "",
"timestamp": ""
},
"reference": "",
"payment_agreement": {
"id": "",
"contract": {
"id": ""
}
}
},
"order": {
"id": "ord_DAx650251315v18H16Ci11x10",
"amount": 1.65,
"currency": "KWD",
"items": {
"count": 1,
"list": [
{
"id": "itm_VvSU502513156nFG16s711111",
"quantity": 1,
"pickup": false,
"product": {
"id": "prd_e6N6502513155ZbQ16pU11311",
"name": [],
"description": [],
"category": "PHYSICAL_GOODS"
}
}
]
},
"metadata": {
"cycle": "1"
}
},
"customer": {
"id": "cus_TS04A4920251315Fx641612200",
"name": [
{
"title": "MS",
"first": "Test",
"middle": "",
"last": "Test",
"lang": "EN"
}
],
"name_on_card": {
"content": "Test Test",
"editable": true
},
"contact": {
"email": "[email protected]",
"phone": {
"country_code": "965",
"number": "62200000"
}
},
"address": {
"type": "home",
"line1": "sdfghjk",
"line2": "oiuytr",
"line3": "line3",
"line4": "line4",
"city": "salmyia",
"state": "kuwait",
"country": "kw",
"zip_code": "30003"
}
},
"post": {
"url": "https://webhook.site/8cbdac91-08fa-40a8-8016-cd4cfabce2af"
},
"metadata": {
"terminal_transaction_id": "terminal_transaction_mwrl50251315A70Y16t811C478"
},
"track": {
"id": "trk_I9vh502513159cSo164211a285",
"status": "PROCESSED",
"activities": [
{
"id": "act_H0As50251315jhIF16i611B285",
"action": "INTENT_INITIATED",
"comment": "Intent created",
"created": "2025-12-16T13:15:50.285020297"
},
{
"id": "act_4Vkn2251317d8WE167N11B759",
"action": "INTENT_PROCESSED",
"comment": "Intent processed successfully.",
"created": "2025-12-16T13:17:02.759249898"
}
]
}
}Response Codes
| Code | Message |
|---|---|
| 100 | Initiated |
| 101 | Processing |
| 000 | Processed |
| 302 | Cancelled |