diff --git a/assets/images/add-locations.png b/assets/images/add-locations.png index 2b0573ae..fb0ab16b 100644 Binary files a/assets/images/add-locations.png and b/assets/images/add-locations.png differ diff --git a/assets/images/api-keys@2x.png b/assets/images/api-keys.png similarity index 100% rename from assets/images/api-keys@2x.png rename to assets/images/api-keys.png diff --git a/assets/images/create-card.png b/assets/images/create-card.png index 053a2b01..53f35d46 100644 Binary files a/assets/images/create-card.png and b/assets/images/create-card.png differ diff --git a/assets/images/create-program.png b/assets/images/create-program.png index b5802057..43d2d190 100644 Binary files a/assets/images/create-program.png and b/assets/images/create-program.png differ diff --git a/assets/images/create-transaction.png b/assets/images/create-transaction.png index 51077fb6..c488d7f5 100644 Binary files a/assets/images/create-transaction.png and b/assets/images/create-transaction.png differ diff --git a/assets/images/icon-desktop.svg b/assets/images/icon-desktop.svg new file mode 100644 index 00000000..5eae5fca --- /dev/null +++ b/assets/images/icon-desktop.svg @@ -0,0 +1,28 @@ + + + + + + + + + + + + + + + + + + diff --git a/assets/images/icon-mobile.svg b/assets/images/icon-mobile.svg new file mode 100644 index 00000000..1baa086e --- /dev/null +++ b/assets/images/icon-mobile.svg @@ -0,0 +1,26 @@ + + + + + + + + + + + + + + + + + + diff --git a/assets/images/intro-demo.png b/assets/images/intro-demo.png index 134ae81e..a55b9ea5 100644 Binary files a/assets/images/intro-demo.png and b/assets/images/intro-demo.png differ diff --git a/assets/images/web-form.png b/assets/images/web-form.png index 4ec810c8..e1bf5331 100644 Binary files a/assets/images/web-form.png and b/assets/images/web-form.png differ diff --git a/assets/images/webhooks-diagram.png b/assets/images/webhooks-diagram.png index 8d77e1a2..b5e291e3 100644 Binary files a/assets/images/webhooks-diagram.png and b/assets/images/webhooks-diagram.png differ diff --git a/cards/README.md b/cards/README.md index 1335c2e0..66adc6d6 100644 --- a/cards/README.md +++ b/cards/README.md @@ -1,17 +1,19 @@ ## Cards -The Card object holds information about the card details submitted by the user using the web form or the mobile SDKs. One user can link multiple cards, debit or credit under the same account. +The Card object holds information about the card details submitted by the user using the web or mobile SDKs. One user can link multiple cards, debit or credit under the same account. -The details required to link a card are the 16-digit card number, expiry date and the programId of the Program you want to link this card to. The card number is validated using the Luhn algorithm and then tokenised before being submitted to Visa and MasterCard networks. This way, your servers are never exposed to sensitive information, removing all PCI compliance requirements from your side. +The details required to link a card to a program are the 16-digit card number, expiry date, country code and the `programId` of the Program you want to link this card to. The card number is tokenised and transmitted directly from our secure pre-built iFrame to FIDEL API. This way, your servers are never exposed to sensitive information, removing all PCI compliance requirements from your side. -FIDEL never stores the 16-digit PAN (Primary Account Number) entered by the user. It is tokenised instantly and submitted to the card schemes. After this point only the card token is exchanged between your servers, the card schemes and FIDEL API. +FIDEL never stores the 16-digit PAN (Primary Account Number) entered by the user. To identify the user in a transaction object you should the use the `cardId` property. After this point only the `cardId` is exchanged between your servers, the card schemes and FIDEL API. -After the card is linked successfully, we will monitor any purchase made by this card on any of the program’s locations and send the transaction object to a specified webhook. +After the card is linked successfully, we will monitor any purchase made by this card on any of the program’s physical or online locations and send the transaction object to a webhook URL specified by you.
# Add Card -To add a new card, go to the **API Playground** on the dashboard, choose **Add Card** from the left menu. The method will be set to POST and the endpoint to _/cards_. An editable sample JSON object like the following one will be used to create the card. In order to add a card from the Playground, you’ll need to use one of the available ~testing card numbers~ shown below. Also, provide an expiry date in the future and the **programId** you want to link this card to. +To add a new card, go to the **API Playground** on the dashboard, choose **Add Card** from the left menu endpoints. The method will be set to POST and the endpoint to **_/cards_**. An editable sample JSON object like the one displayed below will be used to create the card. In order to add a card from the Playground, you’ll need to use one of the available testing card numbers displayed below. Also, provide an expiry date in the future and the `programId` you want to link this card to. + +You can use the dropdown menus to automatically set the ids in the request body or copy them to use in your application code without leaving the playground.
Create sample cards in test mode using the API Playground.
@@ -19,11 +21,7 @@ To add a new card, go to the **API Playground** on the dashboard, choose **Add C
-If the card is successfully linked, the newly created card object is returned in JSON format with the properties shown below. You can also be notified in real-time by creating a webhook with the event `card.link.success`. If the card linking fails we use the event `card.link.error`. - -When linking real Visa cards in live mode, if the card number and expiry date are successfully validated, the `card.link.success` event is triggered in real-time by FIDEL API despite the confirmation from Visa only being available in the next 24 hours. For this reason, we assume that all Visa cards that pass validation are successfully linked and we run a daily schedule at 11:00am UTC that triggers `card.link.error` events in case of any errors. - -This process is not required for Mastercard cards since we get successful card linking confirmation in real-time. +If the card is successfully linked, the newly created card object is returned in JSON and displayed in the response body box. You can also use the [Web SDK](/web) to create cards in the test environment using your test API key. If an error occurs on the card creation, you can verify the error message in the HTTP response body.
JSON Card object
@@ -32,10 +30,10 @@ fileName:card.json { "items": [ { - "id": "6b9d11af-cd1e-4bc9-8000-78f6bfcd3db3", - "accountId": "a3de60c3-849a-4faa-8447-bcd16efb148c", - "programId": "60b4f64e-c6f2-4c0b-a00e-b60192632dfd", - "cardId": "42b8eb31-3cb9-4171-8077-c6669d9aa7a2", + "id": "e3fff00f-ab85-4a0a-b572-08b464ebf67a", + "accountId": "a30e933f-cde1-4ac1-9a5e-acd329497a48", + "programId": "e3fff00f-ab85-4a0a-b572-08b464ebf67a", + "cardId": "e9784e02-6b67-428f-b321-62d9bcdcd9bf", "provider": "mastercard", "type": "master-card", "lastNumbers": "3183", @@ -58,37 +56,37 @@ fileName:card.json
# Testing Card Numbers -Note that you can only add cards in test mode. In live mode new cards can only be created using the SDKs and be real issued card numbers. Use the following test card numbers to test card linking in test mode: +Note that on the Playground you can only create cards in test mode. In live mode new cards can only be linked to programs using the SDKs. Use the following test card numbers to test card linking in test mode, either in the Playground or using the SDKs with the live API key.
Visa testing card numbers
```json visa: [ - '4444000000000001', - '4444000000000002', - '4444000000000003', - '4444000000000004', - '4444000000000005', - '4444000000000006', - '4444000000000007', - '4444000000000008', - '4444000000000009', - '4444000000000010' + '4444000000004001', + '4444000000004002', + '4444000000004003', + '4444000000004004', + '4444000000004005', + '4444000000004006', + '4444000000004007', + '4444000000004008', + '4444000000004009', + '4444000000004010' ] ```
Mastercard testing card numbers
```json mastercard: [ - '5555000000000001', - '5555000000000002', - '5555000000000003', - '5555000000000004', - '5555000000000005', - '5555000000000006', - '5555000000000007', - '5555000000000008', - '5555000000000009', - '5555000000000010' + '5555000000005001', + '5555000000005002', + '5555000000005003', + '5555000000005004', + '5555000000005005', + '5555000000005006', + '5555000000005007', + '5555000000005008', + '5555000000005009', + '5555000000005010' ] ``` diff --git a/gettingstarted/README.md b/gettingstarted/README.md index fc9683bb..a8d61a54 100644 --- a/gettingstarted/README.md +++ b/gettingstarted/README.md @@ -1,22 +1,22 @@ ## Getting Started -**FIDEL API** helps you collect payment card details in minutes on iOS, Android and Web by using native SDKs. We developed customizable UI using iFrames so you don't have to handle sensitive information on your servers. +**FIDEL API** helps you collect payment card details in minutes on iOS, Android and Web with the help of native SDKs. We developed customizable UI using an iFrame so you don't have to handle sensitive information on your servers. -Card numbers are instantly tokenised and we return to you a unique token that identify each successfully linked card on your database. +Card numbers are instantly tokenised and we return to you a unique token that identifies each successfully linked card on your database. You should save the `id` of the card object that is returned inside your user's object. Every transaction we will send to you will have a `cardId` that you can use to identify the user that made that transaction.
# Step 1: Create Account -Before getting started with the integration you need to **create a FIDEL API account** that will give you access to the dashboard, card-linked program configuration, playground environment and API keys. +Before getting started with the integration you need to **create a FIDEL API account** that will give you access to the dashboard, card-linked program configuration, playground environment and API keys. You can create a new account by clicking [here](https://dashboard.fidel.uk/sign-up).
# Step 2: Get API Key -Your test API Key is available on the FIDEL dashboard on your account page. You should start by copying the test key that will allow you to test your integration on mobile or web code and create test transactions from the **API Playground**. +Your test API Key is available on account page of your dashboard. You should start by copying the test key that will allow you to test your integration on a sandbox environment and create test transactions using the **API Playground**. -
Your API keys are shown in your account page.
+
Your API keys are displayed in your account page
-![API keys](https://docs.fidel.uk/assets/images/api-keys@2x.png "API keys") +![API keys](https://docs.fidel.uk/assets/images/api-keys.png "API keys")
@@ -25,29 +25,29 @@ When you're ready to go live with your integration and test with plastic credit/
# Step 3: Install SDKs -You can find the open-source Web SDK on our [Github page](https://github.com/FidelLimited) and contribute to improve documentation and SDK functionality. Use our pre-built web UI to collect user's card number and link their card to your program without the need of additional security implementations on your server-side code. +You can use our pre-built web UI to collect user's card number and link cards to your program without the need of additional security implementations on your server-side code. We are working on two native SDKs for mobile, iOS and Android, that will be available in the next few weeks.
+
+ + +

Web

+

Use our pre-built UI to link cards on your website

+ +
- +

Mobile

-

Coming soon... We are working on iOS and Android native SDKs

- -
-
- - -

Web

-

Easily link cards on your website using the Javascript SDK

+

Coming soon... We are working on native SDKs for iOS and Android

-Please follow the specific [Web SDK](/web) integration guide to learn how to configure and customize the web form to collect card number and expiry date on your website. +Please follow the specific [Web SDK](/web) integration guide to learn how to configure and customize the pre-built UI to collect card details securely on your website. You should visit the [Programs](/programs), [Cards](/cards), [Transactions](/transactions) and [Webhooks](/webhooks) sections to get an overview of the FIDEL API object structure and description. diff --git a/home/README.md b/home/README.md index 453aca2f..c22762c6 100644 --- a/home/README.md +++ b/home/README.md @@ -4,15 +4,15 @@

Get Started

-

Integrate card-linked loyalty with our quickstart guide

+

Start building card-linked applications with our quickstart guide
-
- -

Mobile SDKs

-

Coming soon... We are working on iOS and Android native SDKs

-
+ + +

Web SDK

+

Use our pre-built UI to link cards on your website

+
@@ -24,18 +24,18 @@
- - -

Web SDK

-

Easily link cards on your website using the Javascript SDK

- +
+ +

Mobile SDKs

+

Coming soon... We are working on native SDKs for iOS and Android

+

-FIDEL API is in closed beta under active development . Expect breaking changes and documentation updates before public release. +FIDEL API is in public beta under active development. Expect breaking changes and documentation updates before final release.

@@ -61,27 +61,33 @@ Join our developers' Slack channel for API discussions, documentation, roadmap a
# Demo -The iOS, Android and Javascript SDKs provide you with simple UI to collect your user’s card details securely on the web or in your mobile apps. +The iOS, Android and Web SDKs provide you with pre-built UI to collect your user’s card details securely on the web or in your mobile apps. -
Preview of web and mobile FIDEL card linking iFrame.
+
Preview of web and mobile FIDEL card linking UI
![Intro demo](https://docs.fidel.uk/assets/images/intro-demo.png "Intro demo") -
Web SDK integration code
+To see the Web SDK working, please click the the 'Link Card' button below: + + + + +
Web SDK integration script
```html fileName:index.html - diff --git a/programs/README.md b/programs/README.md index 235d8e73..9864a406 100644 --- a/programs/README.md +++ b/programs/README.md @@ -1,6 +1,6 @@ ## Programs -After creating a FIDEL API account and have access to the dashboard, the next step is to create a program so you can add locations, cards and webhooks in order to generate and receive transactional data. +After creating a FIDEL API account and have access to the dashboard, the next step is to create a test program so you can add locations, cards and webhooks in order to generate and receive sample transaction data.
Hierarchy diagram of the FIDEL API object structure.
@@ -9,7 +9,7 @@ After creating a FIDEL API account and have access to the dashboard, the next st # Create Program A **Program** represents a set of locations or merchantsIds that uniquely identify an offline or online store where transactions from linked cards will be monitored. A new program should be created for each independent loyalty or rewards scheme. -To create a new program, go to **Programs** using the top menu of the dashboard, click **Create Program** and enter a name. The program will be created with the name provided without any initial locations. +To create a new program, go to the **Programs** page on the dashboard, click **Create Program** and enter a name. The program will be created with the name provided without any initial locations.
Go to the Programs page on the dashboard to create a new program.
@@ -17,12 +17,12 @@ To create a new program, go to **Programs** using the top menu of the dashboard,
-A `programId` will be generated and must be passed as a data property when linking cards to this program. +A `programId` will be generated and must be passed as a data property when using the SDKs to link cards to this program.
# Add Locations -To add locations to a program, select a program from the *Programs* page, click *Add Locations* and enter the requested info. You will need to provide `name`, `address` and `merchantId` to add a location to an existing program. +To add locations to a program, select a program from the **Programs** page, click **Add Locations** and enter the requested info. To add a location you need to enter a name, address, postcode, city and merchantId.
After creating a program, you can add locations.
@@ -32,4 +32,4 @@ To add locations to a program, select a program from the *Programs* page, click The `merchantId` is an unique identifier for a retail location that can be found on the receipt printed by any card machine in that location. It is usually referred as MID on the receipt. On an online store the `merchantId` can be requested from the payment service provider used by the e-commerce platform. -In test mode, a new location is automatically approved and set to active status. On live environment, new locations added will require 1-2 weeks processing before becoming active. +In test mode, a new location is automatically approved and set to active status. On live environment, new locations added will require 1-2 weeks processing before becoming active. During that time they will be with pending status. diff --git a/transactions/README.md b/transactions/README.md index 882a6c54..4675b5db 100644 --- a/transactions/README.md +++ b/transactions/README.md @@ -1,10 +1,13 @@ ## Transactions +The transaction object is the central piece of data of your card-linked application. When a user makes a purchase with a linked card in any of the linked program's locations, FIDEL API spots the transaction and sends it to your server as a webhook event. -The transaction object is the central piece of data of your card-linked application. When a consumer makes a purchase with a linked card at a program's location, FIDEL API spots the transaction and sends it to your server using the `transaction.auth` webhook event. +There are two types of transactions depending on the time of processing and clearing state: authorization transactions and cleared transactions. Authorization transactions are processed in real-time, when the user pays in-store (only available on MasterCard. Please email [developer@fidel.uk](mailto:developer@fidel.uk) for VISA availability). You can use the `transaction.auth` webhook event to notify or reward the user in your application in real-time. -Application logic can be implemented in real-time, when the user pays in-store (only available on MasterCard. Please email [developer@fidel.uk](mailto:developer@fidel.uk) for VISA availability) or when the transaction is cleared usually 24-48 hours after the purchase. +All transactions are cleared usually 24-48 hours after the purchase by Visa and Mastercard and for consistency, FIDEL API processes cleared transactions and triggers the `transaction.clearing` webhook events daily at 12:00 UTC. -Transaction objects are sent to specified webhooks in JSON format. If you’re using MasterCard real-time transaction notifications, you will receive them as the customer pays in-store. All Visa and Mastercard settled transactions are processed and sent daily at 12:00pm UTC to your servers through `transaction.clearing.success` webhook events. +For Mastercard linked cards you will receive both `transaction.auth` events in real-time and `transaction.clearing` events. We suggest that you use the auth event to notify the user that you registered the transaction and will fulfill the reward when the transaction clears, since the clearing is the confirmation that the transaction was successfully completed. + +After you received a Mastercard authorisation transaction in real-time, you will also receive the cleared transaction in the next 24-48 hours. At 12:00 UTC daily when we process the clearing transactions, we match every cleared transaction and if an authorization transaction exists we update the `cleared` property from `false` to `true`.
@@ -12,11 +15,11 @@ Transaction objects are sent to specified webhooks in JSON format. If you’re u For testing purposes, you can use the **API Playground** to create transactions and test your application logic. -To create a transaction you will need a test program, at least one location where the transaction can be originated from and a webhook where the transaction object will be sent to at creation time. Also a test card will need to be created and linked to the test program. +To create a transaction you will need a test program, at least one location and a webhook event to receive the transaction object. Also, you will need a test card linked to your test program. -On the dashboard, go to **API Playground** and click on **Create transaction** on the left menu. The method will be set to POST and the endpoint to _/transactions/test_. An editable sample JSON object like the following one will be use to create the transaction. +On the dashboard, go to **API Playground** and click on **Create transaction** from the endpoints menu. The method will be set to POST and the endpoint to **_/transactions/test_**. An editable sample JSON object like the following one will be use to create the transaction. -To create a test transaction you only need to submit three properties, the `cardId`, `locationId` and the `amount` of the transaction you want to create. +To create a test transaction you only need to submit three properties, the `cardId`, `locationId` and the `amount` of the transaction you want to create. You can use the dropdown menus to set these properties. If the transaction is created successfully you will see the transaction object in the response body box.
@@ -26,7 +29,7 @@ To create a test transaction you only need to submit three properties, the `card
-Click **Send** and a test transaction will be created and sent to the webhook URL created for this program with the event property set to `transaction.auth`. An example of the returned transaction object is represented below. +Click **Send** and a test transaction will be created and sent to the webhook URL created for this program with the event property set to `transaction.auth`. An example of the returned transaction object is displayed below.
@@ -35,24 +38,33 @@ Click **Send** and a test transaction will be created and sent to the webhook UR ```json fileName:transaction.json { - "items": [ - { - "id": "6b9d11af-cd1e-4bc9-8000-78f6bfcd3db3", - "accountId": "a3de60c3-849a-4faa-8447-bcd16efb148c", - "programId": "60b4f64e-c6f2-4c0b-a00e-b60192632dfd", - "cardId": "42b8eb31-3cb9-4171-8077-c6669d9aa7a2", - "locationId": "7398177f-e2c1-4055-b27e-ba106483c08f", - "amount": 133, - "currency": "GBP", - "countryCode": "GB", - "card": "mastercard", - "created": "2017-02-13T17:02:12.535Z", - "updated": "2017-02-13T17:17:02.833Z", - "metadata": {}, - } - ], - "resource": "/v1d/transactions/test", - "status": 201, - "execution": 2803.465225 + "items": [ + { + "id": "7fdfd5d8-9589-402f-8477-4a727ad239a2", + "accountId": "4ed4b62b-aa4c-43a1-8064-da6d1368e17a", + "programId": "6e38aa0c-b7ef-46bd-b1bd-c07c648d9cba", + "locationId": "7a916fbd-70a0-462f-8dbc-bd7dbfbea160", + "cardId": "bc538b71-31c5-4699-840a-6d4a08693314", + "mapId": "82c5a9ed-5301-46ab-8599-6bcb0d017cc5", + "amount": 100, + "currency": "GBP", + "countryCode": "GBR", + "scheme": "visa", + "lastNumbers": "4001", + "address": "2 Soho Square", + "postcode": "W1D3PX", + "city": "London", + "merchantId": "12345", + "live": false, + "cleared": false, + "time": "2017-03-02T19:12:01.743Z", + "date": "2017-03-02T19:12:01.743Z", + "created": "2017-03-02T19:12:01.744Z", + "updated": "2017-03-02T19:12:01.744Z" + } + ], + "resource": "/v1d/transactions/test", + "status": 201, + "execution": 180.642048 } ``` diff --git a/web/README.md b/web/README.md index dc347daf..1c3b877a 100644 --- a/web/README.md +++ b/web/README.md @@ -1,5 +1,5 @@ ## Web SDK -**FIDEL Web SDK** is a secure HTML iFrame with customisable pre-built UI that allows you to easily collect credit card details, tokenise and link credit/debit cards with loyalty services from your website or e-commerce platform. By using FIDEL Web SDK, card details are sent directly to Fidel through a secure connection without exposing your servers to sensitive information taking care of all PCI compliance requirements for you. +**FIDEL Web SDK** is a secure HTML iFrame with customisable pre-built UI that allows you to easily collect credit card details, tokenise and link credit/debit cards with rewards services from your website, e-commerce platform or mobile apps. By using FIDEL Web SDK, card details are sent directly to Fidel API through a secure connection without exposing your servers to sensitive information taking care of all PCI compliance requirements for you.
Preview of FIDEL card-linking Web SDK
@@ -7,50 +7,94 @@
-After successfully tokenising and linking the card on Visa or MasterCard networks, Fidel returns a unique token that you use to link each unique card and transaction to your user’s account. You can now create card-linked web applications with online-to-offline marketing capabilities in a matter of minutes. +After successfully tokenising and linking the card on Visa or MasterCard networks, FIDEL API returns the created card object with a unique `id` that you must use to link each unique card and transaction to your user’s account. The `id` of each linked card is present on the transaction object as `cardId`. You can now create card-linked web and mobile applications with online and offline transactional data visibility in a matter of minutes. All modern desktop and mobile browsers are supported, including Chrome, Firefox, Safari, Microsoft IE and Edge. Please contact us at [developer@fidel.uk](mailto:developer@fidel.uk) if you experience any browser issues.
# Integrating Web SDK -You can easily integrate FIDEL Web SDK in your website with only a few lines (or one) of code. +You can easily integrate FIDEL Web SDK in your website or mobile app with only a few lines (or one) of code. -
FIDEL card-linking Web SDK integration code.
+
FIDEL Web SDK script.
```html fileName:index.html - ``` +
-To connect **FIDEL Web SDK** to your **FIDEL API** account and Program you will need to add your test API Key to the `data-api-key` property and add a **programId** to the `data-program-id` property. When you want to go live a link real cards on Visa and Mastercard networks you will need to replace the test key for your live key. +To integrate **FIDEL Web SDK** in your website or mobile app, you need to add the script above in your website or mobile web view. We are working on native mobile SDKs for iOS and Android that will simplify the mobile integration. -The FIDEL Web SDK can be customised to better fit your website. You can provide a title, subtitle and logo by using the properties `data-title`, `data-subtitle` and `data-logo`. Also, the action button can be customised by changing it's background color, title, and title color by using the properties `data-button-color`, `data-button-title` and `data-button-title-color`. +Most of the data properties in the script are self explanatory but you can check the description of each property below. + +
+ +- **data-auto-open**: whether the web form auto opens on page load. + +- **data-callback**: name of the global callback function. + +- **data-key**: a valid API key. + +- **data-program-id**: the id of the program to link the card to. + +- **data-company-name**: the name of the company using card-linked services. + +- **data-title**: the title of the web form. _Max 25 chars._ + +- **data-subtitle**: the subtitle of the web form. _Max 110 chars._ + +- **data-logo**: the logo URL of the company using card-linked services. _Recommended height 35px. Extensions jpg, jpeg, png._ + +- **data-lang**: the localization language to be used. + +- **data-button-color**: the hex color code of the button background. + +- **data-button-title**: the button title. _Max 35 chars._ -The `data-auto-open` property allows you to open the web form automatically on page load if set to _true_. To receive the callback after the form submission you must pass a Javascript global function name reference on the `data-callback` property that will return the response and error objects. Please see an example below: +- **data-button-title-color**: the hex color code of the button title. -
Web form callback global function example.
+
+ +The `data-auto-open` property allows you to open the web form automatically on page load if set to `true`. After adding the Web SDK script on your website a global variable `Fidel` is created with two methods that you can use to open and close the web form manually, `Fidel.openForm()` and `Fidel.closeForm()`. See an example below: + +
Fidel.openForm() global function.
+ +```html + +``` + +
-```javascript +To receive the callback after the form submission you must pass a Javascript global function name reference on the `data-callback` property that will return the response and error objects. Please see an example below: + +
Web SDK callback global function example.
+ +```html fileName:index.html ``` + +
+ +The FIDEL Web SDK can be customised to better fit your website. You can provide a title, subtitle and logo by using the properties `data-title`, `data-subtitle` and `data-logo`. Also, the action button can be customised by changing it's background color, title, and title color by using the properties `data-button-color`, `data-button-title` and `data-button-title-color`. diff --git a/webhooks/README.md b/webhooks/README.md index 19fe65eb..12a354bd 100644 --- a/webhooks/README.md +++ b/webhooks/README.md @@ -1,8 +1,7 @@ ## Webhooks -**FIDEL API** uses webhooks to send transactional data and other relevant events to your server. For example, when a customer successfully links a card through the web form or mobile SDKs, we create a `card.link.success` event and send a POST request with the newly created card object to each of the URLs you provide. -Currently, we have two groups of events, transaction and card related events. Under transactions events we have authorisation and clearing. +**FIDEL API** uses webhooks to send transactional data and other relevant events to your server. For example, when a customer makes a payment with a linked Mastercard, a `transaction.auth` is sent in real-time to the specified webhooks linked to that program. Currently, there are two groups of events, transaction and card related events. -
Webhooks event structure.
+
Webhooks events
![Webhooks diagram](https://docs.fidel.uk/assets/images/webhooks-diagram.png "Webhooks diagram") @@ -12,24 +11,20 @@ Currently, we have two groups of events, transaction and card related events. Un #### Authorisation -**Authorisation events** are triggered while the customer is making the payment in-store in real-time (currently authorisation events only available on MasterCard). When a customer makes a payment with a linked MasterCard debit/credit card in a program location, a `transaction.auth` event is triggered and the transaction object sent to your specified URL in real-time. +**Authorisation events** are triggered while the customer is making the payment in-store in real-time (currently authorisation events are only available on MasterCard). When a customer makes a payment with a linked MasterCard debit/credit card in a program location, a `transaction.auth` event is triggered and the transaction object sent to your specified URL in real-time.
#### Clearing -**Clearing events** are triggered when the transaction is settled, usually happens 24-48 hours after the payment has been made. - -Under clearing there are two separate events, `transaction.clearing.success` and `transaction.clearing.update`. The success event is triggered when the transaction is successfully settled (e.g. an authorisation was sent to charge the card for £5 and the same amount was successfully charged from the card). On the other hand, the update event is triggered when the clearing amount does not match the authorisation amount (e.g. the card was authorised for £5 but it was only charged £2). In this case, a `transaction.clearing.update` is triggered upon receiving the settled transaction with the final amount charged. +**Clearing events** are triggered when the transaction is settled, usually happens 24-48 hours after the payment has been made. For consistency, FIDEL API processes Visa and Mastercard cleared transactions triggering the `transaction.clearing` webhook events daily at 12:00 UTC.
# Card Events -There are four card related events that you can be notified about. Two are triggered when the customer is linking the card on the web or mobile. The other two when a linked card is about to expire or is already expired. - -When the user links the card by sending the card number and expiry date, FIDEL API tokenises and sends this information directly to Visa or MasterCard depending on the card type. If the card is successfully linked, a `card.link.success` event is triggered and the newly created card object sent to the specified URL. If an error occurs, a `card.link.error` event is sent instead. +In the next weeks, there will be two card related events that you will be able to use. -You can be notified when a card is one month from expiring by creating a `card.link.expiring` webhook. Also, you can be notified of all linked card that have expired by creating a `card.link.expired` webhook. The expiry webhooks are scheduled to run daily at 12:00pm UTC. +You can be notified when a card is one month from expiring by creating a `card.link.expiring` webhook. Also, you can be notified of all expired cards by creating a `card.link.expired` webhook. These events will be triggered monthly on the first day of the month so you can notify your users to update their cards to continue to receive rewards. We are looking to extend the list of events in the future. If you require any specific event that is not available yet please speak with us on the [Slack channel](https://fidel-developers-slack-invites.herokuapp.com/) or email us at [developer@fidel.uk](mailto:developer@fidel.uk). @@ -37,6 +32,4 @@ We are looking to extend the list of events in the future. If you require any s # Create Webhook -To create a new webhook, go to **Webhooks** using the top menu of the dashboard, click **Add Webhook**, select the program, select the event and enter the URL where you want to receive this event's payload. From the **Webhhoks** page you can also delete and edit any of the existing webhooks. - -
+To create a new webhook, go to **Webhooks** page on the dashboard, click **Add Webhook**, enter the URL where you want to receive the event's payload, select the program and the event. From the **Webhhoks** page you can also delete and edit any of the existing webhooks.