Creating a Lead
Lead creation is the initial step in onboarding a merchant with Tap. It involves gathering essential information about the business or brand and setting the groundwork for the merchant account. This guide explains the parameters and the process involved in creating a lead, providing a smooth start to the onboarding journey.
Lead Parameters
| Parameter | Description |
|---|---|
| id | The unique ID assigned to the lead. |
| brand | Information related to the business or brand. |
| operations | Details about sales operations, including the sales period, range, and currency. |
| terms | Terms and agreements, such as general terms, chargeback terms, and refund terms, with an indication of agreement. |
| name | The name of the brand in both Arabic and English. |
| channel_services | Information about the web channel services, including the channel name and address. |
| entity | Details related to the entity, such as country, license information, and tax number. |
| wallet | Information about the bank and its account, including the bank name, account number, IBAN, name, and SWIFT code. |
| user | User information, including the user's address, identification details, nationality, phone number, name, birthdate, and email. |
| platforms | An array of platform IDs that specify the platform types (e.g., retail or commerce) assigned to the merchant. You will receive these values from your Tap Account Manager |
| payment_provider | Information about the payment provider, including the technology ID and settlement method. You will receive these values from your Tap Account Manager |
| status | The status of the lead, whether it's "active" or not. |
| live_mode | Indicates whether the lead is in "live" mode or not. |
| api_version | The version of the API used for this lead. |
| feature_version | The version of the feature related to this lead. |
| business_id | The unique ID assigned to the business related to the lead. |
| is_licensed | Indicates if the business is licensed or not. |
| lead_by | Information about the entity that initiated the lead, including the business name and ID. |
| is_acknowledged | Indicates whether the lead has been acknowledged. |
| terms_conditions_accepted | Shows whether the terms and conditions have been accepted. |
| is_new_individual | Indicates if the lead belongs to a new individual. |
cURL Request
Here's a cURL request example for creating a lead:
curl --location 'https://api.tap.company/v3/connect/lead' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer sk_live_xxxxxxxxxx' \
--data-raw '{
"brand": {
"name": {
"en": "merchant name EN",
"ar": "merchant name AR"
},
"sector": [
"telecom",
"finance"
],
"logo": "file_656848322076980748",
"channel_services": [
{
"channel": "website",
"address": "https://www.website.company/"
},
{
"channel": "twitter",
"address": "https://twitter.com/twitter"
},
{
"channel": "instagram",
"address": "https://www.instagram.com/company/twitter"
},
{
"channel": "ios",
"address": "twitter ios app name"
},
{
"channel": "android",
"address": "twitter android app name"
}
],
"segment": {
"type": {
"code": "non_profit"
},
"team": {
"code": "small"
}
},
"operations": {
"sales": {
"period": "monthly",
"range": {
"from": "0",
"to": "20000"
},
"currency": "SAR"
}
},
"terms": [
{
"term": "general",
"agree": true
},
{
"term": "chargeback",
"agree": true
},
{
"term": "refund",
"agree": true
}
]
},
"entity": {
"country": "SA",
"is_licensed": true,
"license": {
"number": "1010000000",
"country": "SA",
"type": "commercial_registration",
"documents": [
{
"type": "commercial_registration",
"number": "101000000",
"issuing_country": "SA",
"issuing_date": "2020-04-01",
"expiry_date": "2024-04-01",
"images": [
"file_643320430437906816"
]
},
{
"type": "Memorandum of Association",
"number": "000000000",
"issuing_country": "SA",
"issuing_date": "2019-07-09",
"expiry_date": "2021-07-09",
"images": [
"file_643320430437906816"
]
}
]
},
"tax": {
"number": "000000000",
"issuing_date": "2023-01-20",
"expiry_date": "2023-01-20",
"documents": [
{
"type": "TAX Document",
"number": "000000000",
"issuing_country": "SA",
"issuing_date": "2019-07-09",
"expiry_date": "2021-07-09",
"images": [
"file_643320430437906816"
]
}
]
}
},
"wallet": {
"bank": {
"name": "Ryiadh Bank",
"account": {
"name": "ABC",
"number": "77777777777",
"swift": "77777777777",
"iban": "SA000000000000000009"
},
"documents": [
{
"type": "Bank Statement",
"number": "000000000",
"issuing_country": "SA",
"issuing_date": "2019-07-09",
"images": [
"file_643320430437906816"
]
}
]
}
},
"user": {
"name": {
"lang": "en",
"title": "Mr",
"first": "USER17",
"middle": "AL-",
"last": "MO"
},
"email": [
{
"type": "WORK",
"address": "[email protected]",
"primary": true
}
],
"phone": [
{
"type": "WORK",
"country_code": "966",
"number": "500000000",
"primary": true
}
],
"nationality": "SA",
"identification": {
"number": "000000000",
"type": "national_id",
"issuer": "SA",
"images": [
"file_1285888642519080960",
"file_1285888642519080960"
]
},
"birth": {
"country": "SA",
"city": "Riyadh",
"date": "1995-07-31"
},
"primary": true
},
"post": {
"url": "http://merchant.company/post_url"
},
"metadata": {
"mtd": "metadata"
},
"platforms": [
"commerce_platform_xxxxxxxxxx"
],
"payment_provider": {
"settlement_by": "payment_facilitator_xxxxxxxxxxx",
"technology_id": "technology_xxxxxxxxxxxx"
}
}'
Lead Response
Here's a sample response to a successful lead creation request:
{
"id": "led_xxxxxxxxxxxxxxxxxxxxx",
"brand": {
"operations": {
"sales": {
"period": "monthly",
"range": {
"from": "10000",
"to": "80000"
},
"currency": "AED"
}
},
"terms": [
{
"term": "general",
"agree": true
},
{
"term": "chargeback",
"agree": true
},
{
"term": "refund",
"agree": true
}
],
"name": {
"ar": "Company Name",
"en": "Company Name"
},
"channel_services": [
{
"channel": "website",
"address": "https://www.website.com"
}
]
},
"entity": {
"country": "AE",
"license": {
"number": "0000000000",
"country": "AE",
"city": "Dubai",
"type": "commercial_registration"
},
"is_licensed": true
},
"wallet": {
"bank": {
"name": "BANK NAME",
"account": {
"number": "00000000009",
"iban": "AE00000000000000000000009",
"name": "Company Name",
"swift": "SWIFTCODE"
}
}
},
"user": {
"address": [
{
"area": "",
"country": "AE",
"line4": "line4",
"city": "Dubai",
"type": "HOME",
"building": "",
"zip_code": "30003",
"street": "",
"avenue": "",
"state": "Dubai",
"line3": "line3",
"postal_code": "",
"line2": "test",
"line1": "test",
"apartment": ""
}
],
"identification": {
"number": "000000000",
"type": "national_id",
"issuer": "AE"
},
"nationality": "AE",
"phone": [
{
"country_code": "971",
"number": "500000000",
"type": "WORK",
"primary": true
}
],
"name": {
"middle": "Middle Name",
"last": "Last Name",
"lang": "en",
"title": "Mr",
"first": "First Name"
},
"birth": {
"country": "AE",
"city": "Dubai",
"date": "1982-02-22"
},
"email": [
{
"address": "[email protected]",
"type": "WORK",
"primary": true
}
],
"primary": true
},
"platforms": [
"platform_id_xxxxxxxxxxxxxxxxxxx"
],
"payment_provider": {
"technology_id": "technology_xxxxxxxxxxxx"
},
"reference_lead_id": "65435866cd8xxxxxxxxxxxxx"
}
Updated 10 days ago