NAV Navbar
Identiway260x50@2x 1

Identity

Overview

Identity service allows Donors to share their customer data with Merchants in a unified and dynamic manner. In Identitrade system user data is called attributes and can be dynamically configured both from the Donor and Merchant sides.

Getting started

In order to integrate Identity service you will need to accomplish the following steps:

  1. Register for account at Identitrade
  2. Get Unique Id
  3. Get Recipient Id
  4. Get API credentials
  5. Embed idt.js to your website (Donor discovery)
  6. Implement server side (data retrieval)
  7. Add identity conversion tracking to site
  8. Add purchase conversion tracking to site (optional)

Recipient Id

Can be found in Control Panel:

API credentials

API credentials can be found in Control Panel:

Identity Attributes

Merchants can configure which user attributes they want to receive and which of them are required. If the required attribute is missing in the Donor system, this donor will not be shown to the user.

List of all attributes:

Name Type Description
first_name string First name
last_name string Last name
personal_number string User personal number
country string Full country name
city string Full city name
address string Full address
phone string User phone number
email string User email
age string User age in years

Client integration (idt.js)

Embed idt.js into your website

Donor discovery

Render donor list with plain JavaScript:

document.addEventListener( "DOMContentLoaded", function(){
  IDT.identity.init();
  IDT.identity.render('idt-container');
});

Render donor list with jQuery:

$(function() {
  IDT.identity.init();
  IDT.identity.render('idt-container');
});

In order to show list of available donors call render method and provide div container where to render list.

Donor list customization

Example of rendering select with donors:

$(function() {
  IDT.identity.init();
  var $idtDonorSelect = $('#idt-donor-select');
  IDT.identity.getDonors(function(donors) { 
      $.each(donors.toArray(), function (key, value) {
          $('<option>', {
            'value' : value.getId(),
            'data-logo' : value.getLogo(),
            'data-legal' : value.getLegal(),
            'text': value.getName()
            }).appendTo($idtDonorSelect);
          });
          $idtDonorSelect.on('change', function () {
            var value = $(this).val();
            if (value !== "") {
              IDT.identity.select($(this).val());
            }
          });
      });
});

If you want to customize donor list, you can call getDonors which gives you list of available donors.

init(options)

IDT.identity.init({'recipient_id': 'xxx', 'css':false, 'popup':true, 'redirect_uri' : 'https://example.com'});

Initializes library and sets configuration values.

Parameter Type Required Description
recipient_id string True Identifies recipient. See Recipient ID
css boolean false Indicates whether to apply css for the donor list. Set false if you want to use custom style. Default true.
popup boolean false Specifies if user authorization should open in popup window. If specified false user will be redirected to authorization in the main page. Default true.
redirect_uri string false Custom redirect url where to return user after authorization. If not specified value from the Control Panel will be used

render(containerId)

IDT.identity.init();
IDT.identity.render('idt-container');

Renders list of donors to specified container

getDonors(callback)

IDT.identity.init();
IDT.identity.getDonors(function(donors) { 
    console.log(donors);
});

Performs donor discovery and returns list of found donors to callback function. Donors are returned as array of Donor object:

Property Type Description
id integer ID of the donor. Pass this value to select method
name string Name of the donor
logo string URL to donor logo
legal string Donor legal text which must be presented together with the Donor logo

select(id, callback)

IDT.identity.init();
IDT.identity.select(donorId, function() { 
    // Perform actions...
    // Reload page
    window.location.reload();
});

Performs donor selection. Behaviour of select method depends on popup parameter:

  1. true - popup will be opened and user will authenticate in popup. After successful authentication callback function will be called if specified, otherwise whole page will be refreshed.
  2. false - whole page will be redirected to Identitrade authentication page.

trackIdentity()

IDT.identity.init();
IDT.identity.trackIdentity();

Method tracks identity conversions. Identitrade system uses it for calculating identity conversions using Identity service

trackPurchase()

IDT.identity.init();
IDT.identity.trackPurchase();

Method tracks purchase conversions. Identitrade system uses it for calculating purchase conversions using Identity service

Client integration (App)

  1. Merchant app calls Donor Discovery API
  2. Discovery API tries to identifies user
  3. Discovery API returns list of available donors
  4. Depending on the auth_type (redirect, request), app opens webview (redirect) or performs request with curl (request)
  5. Merchant app must extract auth_code from redirected url
  6. Merchant app then calls Merchant server with auth_code
  7. Merchant server exchanges auth_code to token with Data API
  8. Merchant server calls Data API to get user data
  9. Merchant server returns user data to app

Donor discovery API

Replace RECIPIENT_ID with the value from the Control Panel. See Recipient ID

curl https://discovery.identitrade.com/api/v1/discovery
    -X POST
    -d unique_id=RECIPIENT_ID
    -d lang="en"
    -d data[msisdn]="370600000"

Example response:

[
    {
        "name": "Tele2",
        "legal": "I agree that Tele2 will share my personal data",
        "logo": "https://d1rm8cylvu9qly.cloudfront.net/donors/05f078abae46519ec6d0e24f621f40a61acfc63c.png",
        "auth_type": "request",
        "auth_link": "https://cp.identitrade.com/oauth/v2/auth/?
client_id=1_x1234567890y&response_type=code&donor_id=1234567890abcdefghijklmnopqrstuv&redirect_uri=https%3A%2F%2Fmerchant.com%2Fauth"
    }
]

API allows to call Donor discovery manually from client side

Request parameters:

Parameter Type Required Description
unique_id string Yes Identifies recipient. See Recipient ID
lang string No 2 character language code in ISO 639-1 format
data.msisdn string No Phone number in E.164 format

Response parameters:

Parameter Type Description
name string Name of the donor
logo string Link to donor logo
legal string Donor legal text which must be presented together with the Donor logo
auth_link string Link to the user authorization
auth_type string request - Merchant can call auth_link without user interaction (e.g. curl) and follow redirects. Merchant must extract auth_code from the final url.
redirect - Merchant must open a browser page (webview) and load auth_link. After successful authorization merchant must close page and extract auth_code from the url

Server side integration

In order to get user data from selected donor Merchants must do server side implementation.

Authentication

Make sure to replace YOUR_CLIENT_ID and YOUR_CLIENT_SECRET with your API credentials from Control Panel. AUTH_CODE must be replaced with code returned to redirect url.

curl https://cp.identitrade.com/oauth/v2/token \
    -X POST \
    -u YOUR_CLIENT_ID:YOUR_CLIENT_SECRET \
    -d grant_type=authorization_code
    -d code=AUTH_CODE
    -d redirect_uri=http://example.com

Example access token response:

{
    "access_token": "MmZmY2RmZDM1NDY3YTQ2ODRiMTg1MTUxNDUzMjk5M2I2MTM3MGM4NDA1OTQxZThmO GQ5NDQ3MWEyMjk5OGY4Nw", 
    "expires_in": 3600, 
    "token_type": "bearer",
    "scope": null
}

After click on donor button user is redirected to Authentication page.

Identity service uses OAuth 2.0 Authorization Code flow for authentication.

After success or failed authorization user is redirected back to Merchant’s redirect uri. Redirect uri can be set in Control Panel or passed to idt.js.

Data retrieval

Replace TOKEN with access token received from Authentication

curl https://cp.identitrade.com/api/v1/data
    -X GET
    -H "Authorization: Bearer TOKEN"

Example response:

{               
    "success": true,
    "id": 1000,
    "data": {
        "personal_number": "123465789",
        "first_name": "Philip",
        "last_name": "Hallenborg",
        "email": "philip@identitrade.com",
        "phone": 7307406945,
        "address": "Regeringsgatan 65, 3tr SUP46",
        "city": "Stockholm",
        "postcode": "182 66"
    }
}

Merchant must call Data API after receiving access token.

See Identity Attributes for list of all data fields

Affiliate

Overview

  1. Advertiser creates campaign with landing page url and commissions (Commissions can be fixed or percentage based on value)
  2. Publisher applies for a campaign
  3. Advertiser approves application of publisher
  4. Publisher inserts campaign link to his page
  5. When user clicks on campaign link in a publisher site, campaign lead is saved
  6. User is redirected to a campaign landing page
  7. If user successfully finishes campaign (can be purchase, registration etc), publisher calls identitrade campaign finish function and completes campaign lead.

For detail information visit Affiliate guide

Campaign conversion tracking

Conversion finish example:

<script type="text/javascript">
  $(function() {
    IDT.affiliate.finish(
      {
        'id': 'CAMPAIGN_ID',
        'reference': 'ORDER_ID',
        'amount': 8025
      }
    );
  });
</script>

Add idt.js to your website where user finishes campaign (e.g. purchases item)

Finish method parameters:

Name Type Required Description
id string Yes ID of campaign. Can be found in the Control Panel
amount integer No Order amount in smallest currency unit (e.g. cents). Will be used for calculating commissions
reference string No Order reference number

Payments

Overview

Identitrade Payment Gateway (PGW) enables merchants to add charging functionality to their websites and apps. PGW follows RESTful principles and provides responses in JSON format.

Accounts can have test and production keys. Test workflow is identical to production with the clause that user is not actually charged.

Getting started

In order to integrate PGW you will need to accomplish the following steps:

  1. Get test API key pair (CLIENT_ID and CLIENT_SECRET) from Identitrade.
  2. Install suitable OAuth 2.0 authentication library, compatible with your chosen platform or implement OAuth2 client manually
  3. Integrate Discovery API for finding possible payment methods
  4. Initiate Payment creation

Server integration

  1. Client opens checkout page
  2. Merchant calls Discovery API
  3. PGW finds available payment methods and returns it to Merchant
  4. Merchant presents buttons with payment methods to Client
  5. Client clicks payment method button
  6. Merchant calls PGW authentication for getting access token
  7. PGW validates merchant credentials and issues access token
  8. Merchant calls payment creation endpoint providing user data
  9. If all the the data is valid PGW creates payment and returns JSON with payment details and HATEOAS links for further actions
  10. Merchant checks if there is approval_url and redirects user to approval_url. If no authentication is required merchant can call payment execution (step 13.)
  11. Client is redirected to approval_url
  12. PGW initiates Client authentication 12.1. If user cancels authentication user is redirected to merchant cancel_url 12.2. If user cannot be authenticated user is redirected to merchant error_url 12.3. On successful authentication user is redirected to merchant sucess_url
  13. Merchant calls payment execution endpoint
  14. Client is charged
  15. Merchant shows success page

Web App integration

  1. Client loads payment screen
  2. Merchant app calls Discovery API
  3. PGW finds available payment methods and returns to Merchant app
  4. Merchant app presents payment option to Client
  5. Client clicks payment method button
  6. Merchant app calls Merchant Server for payment creation and provides selected payment method
  7. Merchant server authenticates at PGW and calls payment createion endpoint
  8. If all the the data is valid PGW creates payment and returns JSON with payment details and HATEOAS links for further actions.
  9. Merchant checks if there is approval_url and returns approval_url to app
  10. Merchant app opens webview with approval_url
  11. Client sees authentication page
  12. Client performs authentication (optional) 13.1. If user cancels authentication user is redirected to merchant server cancel_url 13.2. If user cannot be authenticated user is redirected to merchant server error_url 13.3. On successful authentication user is redirected to merchant server sucess_url
  13. Merchant server calls payment execution endpoint
  14. PGW returns payment object
  15. Merchant server redirects user to success / error page
  16. Merchant app catches success / error page and closes webview
  17. Merchant app shows success / error screen

Authentication

To get access token, use the code below. Make sure to replace YOUR_CLIENT_ID and YOUR_CLIENT_SECRET with your API credentials.

curl https://pgw.identitrade.com/oauth/v2/token \
    -X POST \
    -u YOUR_CLIENT_ID:YOUR_CLIENT_SECRET \
    -d grant_type=client_credentials

Example access token response:

{
    "access_token": "MmZmY2RmZDM1NDY3YTQ2ODRiMTg1MTUxNDUzMjk5M2I2MTM3MGM4NDA1OTQxZThmO GQ5NDQ3MWEyMjk5OGY4Nw", 
    "expires_in": 3600, 
    "token_type": "bearer"
}

PGW uses OAuth 2.0 client_credentials grant flow to authenticate requests.

Each request must include access token in authorization header:

Authorization: Bearer TOKEN

List of HATEOAS links are returned together with payment object:

Rel Authorization Meaning
self Access token By calling this url you will get the same response as after successful creation of Payment. It is useful for checking the status of payment.
approval_url None User must be redirected to this URL for authorization.
execute_url Access token When payment status becomes approved merchant can call this API endpoint for performing user charge (capture) or reservation
capture_url Access token Uncaptured payments can be captured with this API call for actual user charge
refund_url Access token completed payments can be refunded with this API call

Errors

PGW API uses the following error codes:

Error Code Meaning
400 Bad Request – Provided request is invalid
401 Unauthorized – Your API key is not valid
403 Forbidden – Request is not allowed
404 Not Found – Requested resource not found
405 Method Not Allowed – You tried to access resource with invalid method
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarily offline for maintenance. Please try again later.

Payment

Object

Name Type Description
id UUID
amount integer Positive unit in smallest currency unit (e.g. cents)
currency string Three-letter ISO 4217 currency code
payment_method string Can be on of: lt.tele2.charge
description string Description for the payment
order_id string Order id in the merchant system
status string Payment status
captured boolean Indicates whether payment is captured (charged). Uncaptured payments can be captured in 7 days. After this period, payment cannot be captured.
refunded_amount integer Total refunded amount of the payment.
refunded boolean Indicates if the payment is fully refunded
success_url string Link where to redirect user after successful authorization
cancel_url string Link where to redirect user when user cancels authorization
error_url string Link where to redirect user when user authorization fails
links collection List of HATEOAS links
payer Payer object Depends on the payment method
update_time DateTime Update date and time in ISO 8601 format
create_time DateTime Creation date and time in ISO 8601 format

Statuses

Status Description
created Payment is created and must be approved by user
approving User has started payment approval
approved User approved payment
canceled User has canceled payment approval
failed Payment execution failed
completed Payment is completed (user is charged)
reserved Payment amount is reserved
expired Payment reservation has expired and payment can not be captured

Create Payment

curl https://pgw.identitrade.com/api/v1/payment \
    -X POST \
    -H "Authorization: Bearer TOKEN" \
    -d payment[amount]=1000 \
    -d payment[currency]="EUR" \
    -d payment[payment_method]="lt.tele2.charge" \
    -d payment[description]="Good name" \
    -d payment[order_id]="1234" \
    -d payment[success_url]="http://example.com/success" \
    -d payment[cancel_url]="http://example.com/canceled" \
    -d payment[error_url]="http://example.com/failed" \
    -d payer[phone]="+37060000000"

Example response:

{
    "payment": {
        "id": "1869f89a-18e5-11e6-8829-c6df0a92c110",
        "create_time": "2016-05-13T08:31:31+0000",
        "update_time": "2016-05-13T08:31:31+0000",
        "payment_method": "lt.tele2.charge",
        "description": "Good name",
        "order_id": "1234",
        "status": "created",
        "amount": 1000,
        "currency": "EUR",
        "captured": true,
        "refunded_amount": 0,
        "refunded": false,
        "success_url": "http://example.com/success",
        "error_url": "http://example.com/failed",
        "cancel_url": "http://example.com/canceled"
    },
    "payer": {
        "phone": "+37060012345"
    },
    "links": [
        {
            "href": "https://pgw.identitrade.com/api/v1/payment/1869f89a-18e5-11e6-8829-c6df0a92c110/",
            "rel": "self",
            "method": "GET"
        },
        {
            "href": "https://pgw.identitrade.com/pm/lt/tele2_charge/v1/payments/approve/1869f89a-18e5-11e6-8829-c6df0a92c110/1463128291/ea2fcc26c0ef8b47c2d559e71355fb82894f64d8",
            "rel": "approval_url",
            "method": "REDIRECT"
        }
    ]
}

This endpoint creates new payment.

HTTP Request

POST https://pgw.identitrade.com/api/v1/payment

Request Parameters

Parameter Type Required Description
amount integer Yes Positive unit in smallest currency unit (e.g. cents)
currency string Yes Three-letter ISO 4217 currency code
payment_method string Yes Can be on of: lt.tele2.charge
description string Yes Description for the payment
order_id string Yes Order id in the merchant system
success_url string Yes Link where to redirect user after successful authorization
cancel_url string Yes Link where to redirect user when user cancels authorization
error_url string Yes Link where to redirect user when user authorization fails
payer Payer object Yes Depends on the payment method

Get Payment

curl https://pgw.identitrade.com/api/v1/payment/1869f89a-18e5-11e6-8829-c6df0a92c110/ \
     -X GET \
     -H "Authorization: Bearer TOKEN"

Example response:

{
    "payment": {
        "id": "1869f89a-18e5-11e6-8829-c6df0a92c110",
        "create_time": "2016-05-13T08:31:31+0000",
        "update_time": "2016-05-13T08:31:31+0000",
        "payment_method": "lt.tele2.charge",
        "description": "Good name",
        "order_id": "1234",
        "status": "created",
        "amount": 1000,
        "currency": "EUR",
        "captured": true,
        "refunded_amount": 0,
        "refunded": false,
        "success_url": "http://example.com/success",
        "error_url": "http://example.com/failed",
        "cancel_url": "http://example.com/canceled"
    },
    "payer": {
        "phone": "+37060012345"
    },
    "links": [
        {
            "href": "https://pgw.identitrade.com/api/v1/payment/1869f89a-18e5-11e6-8829-c6df0a92c110/",
            "rel": "self",
            "method": "GET"
        },
        {
            "href": "https://pgw.identitrade.com/pm/lt/tele2_charge/v1/payments/approve/1869f89a-18e5-11e6-8829-c6df0a92c110/1463128291/ea2fcc26c0ef8b47c2d559e71355fb82894f64d8",
            "rel": "approval_url",
            "method": "REDIRECT"
        }
    ]
}

This endpoint retrieves existing payment.

HTTP Request

GET https://pgw.identitrade.com/api/v1/payment/<ID>/

Execute Payment

curl https://pgw.identitrade.com/api/v1/payment/1869f89a-18e5-11e6-8829-c6df0a92c110/execute
    -X POST \
    -H "Authorization: Bearer TOKEN"
    -d amount=1000

Example response:

{
    "payment": {
        "id": "1869f89a-18e5-11e6-8829-c6df0a92c110",
        "create_time": "2016-05-13T08:31:31+0000",
        "update_time": "2016-05-13T08:31:31+0000",
        "payment_method": "lt.tele2.charge",
        "description": "Good name",
        "order_id": "1234",
        "status": "completed",
        "amount": 1000,
        "currency": "EUR",
        "refunded_amount": 0,
        "refunded": false,
        "captured": true,
        "success_url": "http://example.com/success",
        "error_url": "http://example.com/failed",
        "cancel_url": "http://example.com/canceled"
    },
    "payer": {
        "phone": "+37060012345"
    },
    "links": [
        {
            "href": "https://pgw.identitrade.com/api/v1/payment/1869f89a-18e5-11e6-8829-c6df0a92c110/",
            "rel": "self",
            "method": "GET"
        },
        {
            "href": "https://pgw.identitrade.com/api/v1/payment/1869f89a-18e5-11e6-8829-c6df0a92c110/refund",
            "rel": "refund_url",
            "method": "POST"
        }
    ]
}

Endpoint initiates payment execution. If flag capture is set to true, user is charged immediately. Otherwise payment amount will be reserved and can be captured (charged) within 7 days of payment creation date.

HTTP Request

POST https://pgw.identitrade.com/api/v1/payment/<ID>/execute

Request Parameters

Parameter Type Required Description
amount integer Yes Cannot be higher than the amount provided when creating payment
capture boolean No Indicates whether to capture (charge) payment. Default true.
description string No Payment description
order_id string No Order id in the merchant system

Capture Payment

curl https://pgw.identitrade.com/api/v1/payment/1869f89a-18e5-11e6-8829-c6df0a92c110/capture
    -X POST \
    -H "Authorization: Bearer TOKEN" \
    -d amount=1000

Example response:

{
    "payment": {
        "id": "1869f89a-18e5-11e6-8829-c6df0a92c110",
        "create_time": "2016-05-13T08:31:31+0000",
        "update_time": "2016-05-13T08:31:31+0000",
        "payment_method": "lt.tele2.charge",
        "description": "Good name",
        "order_id": "1234",
        "status": "completed",
        "amount": 1000,
        "currency": "EUR",
        "refunded_amount": 0,
        "refunded": false,
        "captured": true,
        "success_url": "http://example.com/success",
        "error_url": "http://example.com/failed",
        "cancel_url": "http://example.com/canceled"
    },
    "payer": {
        "phone": "+37060012345"
    },
    "links": [
        {
            "href": "https://pgw.identitrade.com/api/v1/payment/1869f89a-18e5-11e6-8829-c6df0a92c110/",
            "rel": "self",
            "method": "GET"
        },
        {
            "href": "https://pgw.identitrade.com/api/v1/payment/1869f89a-18e5-11e6-8829-c6df0a92c110/refund",
            "rel": "refund_url",
            "method": "POST"
        }
    ]
}

Endpoint initiates capture (charging) of the user. The difference between initial and capture amount is refunded.

HTTP Request

POST https://pgw.identitrade.com/api/v1/payment/<ID>/capture

Request Parameters

Parameter Type Required Description
amount integer No Amount to capture. Must be less or equal to initial payment amount. If not specified initial amount will be captured
description string No Payment description
order_id string No Order id in the merchant system

Refund

Object

Name Type Description
id UUID
amount integer Positive unit in smallest currency unit (e.g. cents)
currency string Three-letter ISO 4217 currency code
payment Payment object
description string Description of the refund
reason string Can be one of: duplicate, fraudulent, customer
status string Can be one of: pending, success, failed
update_time DateTime Update date and time in ISO 8601 format
create_time DateTime Creation date and time in ISO 8601 format

Create Refund

curl https://pgw.identitrade.com/api/v1/payment/1869f89a-18e5-11e6-8829-c6df0a92c110/refund \
    -X POST \
    -H "Authorization: Bearer TOKEN" \
    -d amount=1000 \
    -d currency="EUR" \
    -d reason="fraudulent"

Example response:

{
    "id": "1869f89a-18e5-11e6-8829-c6df0a92c110",
    "amount": 1000,
    "currency": "EUR",
    "description": null,
    "reason": "fraudulent",
    "status": "success",
    "create_time": "2016-05-13T08:31:31+0000",
    "update_time": "2016-05-13T08:31:31+0000"
}

This endpoint refunds completed payment. Total amount of all refunds cannot exceed payment amount

HTTP Request

POST https://pgw.identitrade.com/api/v1/payment/<ID>/refund

Request Parameters

Parameter Type Required Description
amount integer Yes Positive unit in smallest currency unit (e.g. cents)
currency string Yes Three-letter ISO 4217 currency code
reason string Yes Can be one of: duplicate, fraudulent, customer
description string No Description of the refund

Payment methods

Tele2 Lithuania carrier

Payment method allows to charge Lithuanian Tele2 accounts by phone number.

Payer object

Parameter Type Required Description
phone string No Phone number in E.164 format

Discovery API

curl https://pgw.identitrade.com/api/v1/payment/discover
    -X POST \
    -d client_id=xxx \
    -d amount=1000 \
    -d currency="EUR"

Example response:

[
    {
      "name": "Tele2 Charge",
      "alias": "lt.tele2.charge",
      "logo": "https://d3k5djgzkq5py9.cloudfront.net/pm/lt.tele2.charge.png",
    }
]

Merchants can call Discovery API in order to get list of available payment methods.

HTTP Request

POST https://pgw.identitrade.com/api/v1/payment/discover

Request Parameters

Parameter Type Required Description
client_id string Yes client_id from API credentials
amount integer Yes Total amount to be charged. Positive unit in smallest currency unit (e.g. cents)
currency string Yes Three-letter ISO 4217 currency code
phone string No Phone number in E.164 format

idt.js

idt.js allows merchants to integrate Identitrade into websites in a quick and flexible way.

Embed

Replace UNIQUE_ID with the value from the Control Panel.

<script type="text/javascript" 
src="https://discovery.identitrade.com/js/v1/UNIQUE_ID/idt.js?scope=identity"></script>

Add idt.js this code to head of a page where you want to use identity service.

idt.js supports the following url parameters:

Name Required Description
scope Yes List of scopes separated by coma. Supported scopes: identity, affiliate, payment
env No Environment eg: prod, test. Default prod
lang No Language of the texts. Default en.

Unique ID

Can be found in Control Panel: