Implementation & Go-Live
To successfully integrate Smile into your process, we suggest doing so through 3 steps:
- Requirements gathering - explore your use case and what do you want to achieve with Smile data
- Design - design your user journey and integration with Smile.
- Implementation & Go-Live (this guide) - detailed steps to set up and get the integration launched
Step 1: Implement Smile Wink
If you want the users to connect their employment accounts while they are on your website or app, you need to integrate the Smile Wink Widget. See below an example configuration to start:
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="icon" href="smileicon32.webp" sizes="32x32">
<link rel="icon" href="smileicon192.webp" sizes="192x192">
<title>Smile Wink</title>
</head>
<body>
<script src="https://web.smileapi.io/v2/smile.v2.js"></script>
<script type="text/javascript">
const smileLinkModal = new SmileLinkModal({
/**
* The Link API URI. Note: Sandbox and Production modes use different API URIs.
*/
apiHost: 'https://link-sandbox.smileapi.io/v1',
/**
* User token(link token) passed from your backend service which is obtained from the Smile API.
*/
userToken: '<usertoken>',
/**
* Use the template ID to determine how your widget looks like embedded in your app or website.
* You can find and create the template ID in the Smile developer-portal.
* https://developer-portal.smileapi.io/link/template
*/
templateId: "<ID of wink template >",
/**
* Account login callback.
*/
onAccountCreated: ({ accountId, userId, providerId }) => {
console.log('Account created: ', accountId, ' User ID:', userId, ' Provider ID:', providerId)
},
/**
* Account login success callback.
*/
onAccountConnected: ({ accountId, userId, providerId }) => {
console.log('Account connected: ', accountId, ' User ID:', userId, ' Provider ID:', providerId)
},
/**
* Account revoke callback.
*/
onAccountRemoved: ({ accountId, userId, providerId }) => {
console.log('Account removed: ', accountId, ' User ID:', userId, ' Provider ID:', providerId)
},
/**
* Token expired callback.
*/
onTokenExpired: () => {
console.log('Token expired');
},
/**
* Smile link SDK close callback.If you want to know which button the user clicked to trigger the close event, you can pass parameters like this.
* onClose:({reason})=>{}
* If the value of reason is equal to "close", it means that the user clicked the close icon in the upper right corner of the page to close the SDK
* If the value of reason is equal to "exit", it means that the user clicked the DONE button on the connection page to close the SDK
*/
onClose: ({ reason }) => {
console.log('Link closed, reason:', reason)
},
/**
* Account connect error callback.
*/
onAccountError: ({ accountId, userId, providerId, errorCode }) => {
console.log('Account error: ', accountId, ' User ID:', userId, ' Provider ID:', providerId, 'Error Code:', errorCode)
},
/**
* Uploads submit callback.
*/
onUploadsCreated: ({ uploads, userId }) => {
console.log('Uploads: ', uploads, ' User ID:', userId);
},
/**
* Uploads revoke callback.
*/
onUploadsRemoved: ({ uploads, userId }) => {
console.log('Uploads: ', uploads, ' User ID:', userId);
},
/**
* User event callback is used to capture all the user activities from Smile Wink SDK
*/
onUIEvent: ({ eventName, eventTime, mode, userId, account, archive }) => {
console.log('eventName:', eventName,
"eventTime:", eventTime,
"mode:", mode,
"userId:", userId,
"account:", account,
"archive:", archive);
}
});
smileLinkModal.open()
</script>
</body>
</html>
Notice that the apiHost
configuration parameter in the example code points to https://link-sandbox.smileapi.io/v1
. This ensures that the plugin starts in a sandbox environment (the Sandbox Mode) where you can use the sandbox test credentials shown below to test the implementation.
User tokens (Link tokens)
User tokens are temporary (expires in 5 hours) access keys that allow you to start the Smile Linking process.
Link initialization for new user :
- Create a new Smile user by calling the
/users
endpoint with metadata, such as your user identifier in your product/system. You will receive a SmileuserId
. We recommend storing this SmileuserId
in your system for future reference and use - Create a new user token by calling the
/tokens
endpoint with theiruserId
. You will receive theiruserToken
- Provide the
userToken
in your Smile Wink initialization. Make sure the user tokens are requested server-side and yourclient_id
andclient_secret
are never exposed on the front-end.
Link initialization for a returning user or for refreshing the Link token
- Obtain a new user token by calling the
/tokens
endpoint with theiruserId
that you have previously stored. - Provide the
userToken
in your Smile Wink initialization. Make sure user tokens are requested server-side and yourclient_id
andclient_secret
are never exposed on the front-end.
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta http-equiv="X-UA-Compatible" content="IE=edge" />
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<link rel="icon" href="smileicon32.webp" sizes="32x32">
<link rel="icon" href="smileicon192.webp" sizes="192x192">
<title>Smile Wink</title>
</head>
<body>
<script src="https://web.smileapi.io/v2/smile.v2.js"></script>
<script type="text/javascript">
const smileLinkModal = new SmileLinkModal({
/**
* The Link API URI. Note: Sandbox and Production modes use different API URIs.
*/
apiHost: 'https://link-sandbox.smileapi.io/v1',
/**
* User token passed from your backend service which is obtained from the Smile API.
*/
userToken: '<usertoken>', // Put your user token here.
// .....
});
smileLinkModal.open()
</script>
</body>
</html>
Step 2: Connect test accounts
To use the Sandbox, you can use the following example credentials:
User Name | Full Name | Mobile Phone | Password | Verification Code | |
---|---|---|---|---|---|
George | George Palomero Jr. | [email protected] | (+63) 9559991234 | 123456 | 1234 |
Ryan | Ryan Ng | [email protected] | (+62) 8119994321 | 654321 | 1234 |
Christina | Christina Tan | [email protected] | (+65) 99996789 | YGUS1 | 1234 |
Anisha | Anisha Bhatia | [email protected] | (+91) 9511198765 | 123456 | 1234 |
Before proceeding to the next step, make sure to test your implementation. Click on one of the providers on the provider list, and use one of the sandbox credentials to connect the selected provider.
Step 3: Retrieve identity, employment and contribution data
For personal information verification, fetch the following fields from the /identities
endpoint:
- First name
- Last name
- Primary address
Issue a GET request to Smile OpenAPI:
GET https://https://open-sandbox.smileapi.io/v1/identities?sourceId=<accountId>
# insert your user's accountId in the request.
# this example uses the sandbox mode. Don't forget to switch to the production mode if you are testing in production.
Here is an example response:
{
"id": "i-123abc456def789abc123def456abc78",
"fullName": "George Cimafranca Palomero, Jr",
"firstName": "George",
"middleName": "Cimafranca",
"lastName": "Palomero",
"suffix": "Jr",
"gender": "Male",
"dob": "1970-08-24",
"maritalStatus": "Married",
"countryResidence": "PH",
"citizenship": "Citizen",
"photoUrl": "https://cdn.smileapi.io/image/avatar/v20211115191600/george.jpg",
"referenceId": null,
"profileUrl": null,
"emails": [
{
"address": "[email protected]",
"type": "Primary"
}
],
"phones": [
{
"number": "+639559991234",
"type": "Mobile"
}
],
"socialProfiles": [
{
"socialUrl": "https://www.facebook.com/gpalomero1234",
"type": "Facebook"
}
],
"addresses": [
{
"fullAddress": "12 Maybunga St, Barangay Paraiso, Pasig City, NCR, 1600, PH",
"line1": "12 Maybunga St",
"line2": "Barangay Paraiso",
"city": "Pasig City",
"region": "NCR",
"zip": "1600",
"country": "PH",
"latitude": "14.573454",
"longitude": "121.085042",
"type": "Primary"
}
],
"metadata": {
"createdAt": "2022-08-19T07:29:08Z",
"sourceId": "a-123abc456def789abc123def456abc78",
"sourceType": "ACCOUNT",
"userId": "tenantId-123abc456def789abc123def456abc78",
"providerId": "abccorp"
}
}
For employment information verification, fetch the following fields from the /employments
endpoint:
- Employer name
- Job title
- Start date
- End date
Issue a GET request to Smile OpenAPI:
GET https://https://open-sandbox.smileapi.io/v1/employments?sourceId=<accountId>
curl --request GET \
--url 'https://sandbox.smileapi.io/v1/identities?size=10&sourceId=<accountId>' \
--header 'accept: application/json' \
--header 'authorization: Basic <authorization>'
# insert your user's accountId in the request.
# this example uses the sandbox mode. Don't forget to switch to the production mode if you are testing in production.
Here is an example response:
[{
"id": "e-123abc456def789abc123def456abc78",
"startDate": "2022-07-01",
"name": "Security",
"description": null,
"jobTitle": "Security Guard",
"department": null,
"employeeNumber": "EMP-123456",
"employer": "ABC Corporation",
"status": "Permanent",
"endDate": "2022-07-31",
"metadata": {
"createdAt": "2022-09-01T01:44:18Z",
"sourceId": "a-123abc456def789abc123def456abc78",
"sourceType": "ACCOUNT",
"userId": "tenantId-123abc456def789abc123def456abc78",
"providerId": "abccorp",
"accountId": "a-123abc456def789abc123def456abc78"
}
}, {
"id": "e-123abc456def789abc123def456abc78",
"startDate": "2022-06-01",
"name": "Security",
"description": null,
"jobTitle": "Security Guard",
"department": null,
"employeeNumber": "CDE-98765",
"employer": "CDE Corporation",
"status": "Permanent",
"endDate": "2022-06-30",
"metadata": {
"createdAt": "2022-09-01T01:44:18Z",
"sourceId": "a-123abc456def789abc123def456abc78",
"sourceType": "ACCOUNT",
"userId": "tenantId-123abc456def789abc123def456abc78",
"providerId": "cdecorp",
"accountId": "a-123abc456def789abc123def456abc78"
}
}]
For contribution information verification, fetch the following fields from the /contributions
endpoint:
- Employer name
- Job title
- Start date
- End date
Issue a GET request to Smile OpenAPI:
GET https://https://open-sandbox.smileapi.io/v1/employments?sourceId=<accountId>
# insert your user's accountId in the request.
# this example uses the sandbox mode. Don't forget to switch to the production mode if you are testing in production.
Here is an example response:
[{
"id": "con-123abc456def789abc123def456abc78",
"date": "2022-06-30",
"currency": "PHP",
"amount": 2250,
"referenceId": null,
"metadata": {
"createdAt": "2022-08-24T05:14:37Z",
"sourceId": "a-123abc456def789abc123def456abc78",
"sourceType": "ACCOUNT",
"userId": "tenantId-123abc456def789abc123def456abc78",
"providerId": "sss_ph",
"accountId": "a-123abc456def789abc123def456abc78"
}
}, {
"id": "con-123abc456def789abc123def456abc78",
"date": "2022-05-31",
"currency": "PHP",
"amount": 2250,
"referenceId": null,
"metadata": {
"createdAt": "2022-08-24T05:14:37Z",
"sourceId": "a-123abc456def789abc123def456abc78",
"sourceType": "ACCOUNT",
"userId": "tenantId-123abc456def789abc123def456abc78",
"providerId": "sss_ph",
"accountId": "a-123abc456def789abc123def456abc78"
}
}, {
"id": "con-123abc456def789abc123def456abc78",
"date": "2022-04-30",
"currency": "PHP",
"amount": 2250,
"referenceId": null,
"metadata": {
"createdAt": "2022-08-24T05:14:37Z",
"sourceId": "a-123abc456def789abc123def456abc78",
"sourceType": "ACCOUNT",
"userId": "tenantId-123abc456def789abc123def456abc78",
"providerId": "sss_ph",
"accountId": "a-123abc456def789abc123def456abc78"
}
}]
For additional data fields, please refer to the Smile API reference.
Step 4: Setup webhooks
To receive regular updates on a user's accounts, identity, contribution and employment data, subscribe to webhooks.
Webhooks send notifications to your system every time something occurs, i.e., when an account is connected, removed, or updated.
To monitor changes to identity, contribution and employment data, Smile recommends subscribing to the following webhook events, then call the Smile OpenAPI to retrieve data accordingly.
Event | Event Type | Description |
---|---|---|
Task Started | TASK_STARTED | Sent when the data sync process for a user's account is started. |
Task Finished | TASK_FINISHED | Sent when the data sync task process for a user's account is finished, contains which datapoints have been synced |
Or you can subscribe to dedicated datapoint related events
Event | Event Type | Description |
---|---|---|
Contributions Data Added | CONTRIBUTIONS_ADDED | Sent when social security contributions data shared by a user is added. |
Estimated Incomes Data Added | EINCOMES_ADDED | Payload when estimated income data has been derived from data shared by a user. |
Transactions Data Added | TRANSACTIONS_ADDED | Sent when transactions data shared by a user is added. |
... | ... | ... |
Step 5: Go live and scale
After a successful implementation and multiple successful tests in Sandbox Mode, you can switch to the Production mode for your launch.
Change the apiHost
Firstly, change the apiHost
in your Wink configuration from:
https://link-sandbox.smileapi.io/v1
to:
https://link.smileapi.io/v1
The same logic applies to any Open API requests that you have previously used, so /employments
for example:
GET https://open-sandbox.smileapi.io/v1/employments?sourceId={accountId}
change to:
GET https://open.smileapi.io/v1/employments?sourceId={accountId}
Change the API Key pair
The API Key pair can be found in the API Keys section of the Developer Portal . Use a production key when switching to Production Mode.
Start slow
For your first Production accounts, you can test on yourself with your own accounts, or create an account with a freelance gig platform (i.e. Upwork) and connect that account.
Launch and scale
After testing with your personal accounts, you can test with your real users. We recommend starting with a small subset of your users to make sure that everything is working as expected. Then, advance the subset gradually to your full user base.
Updated 19 days ago