Skip to main content

Authentication

All API and SDK requests require authentication. API calls require an authorization token, and calls to the SDK require a session key. Follow along this page to learn how to retrieve and use your authorization token and session key.

Making API Requests​

All API requests require your auth token to be included as a header.

Getting Your Auth Token​

Calls to Link Money's APIs are authenticated with an authorization token. This token can be retrieved by making a call to our authentication servers as in the following example. The two pieces of information needed to get an authorization token are your Client ID and Client Secret. See later steps in this tutorial for examples of how to use your auth token.


Retrieving Your Auth Token

Client ID and Secret

Your Client ID and Secret can be retrieved from Link Money's merchant portal. Use the following links for sandbox and production. Navigate to the Accounts page and look for the tile pictured below. Enter these values in the template in the next step.


Auth Token Request

This is an example of retrieving an auth token in bash. Ensure that a POST method is being used, you have the correct URL, you include the content-type header with the value given in the following example, fill in your client ID and secret in the appropriate fields, and include the appropriate scope for the request you are making.

Scope types

  • Link-Payment

    string

    Used for Payments, Refunds, Credits, and Cancelations

  • Link-Core

    string

    For all other requests

POST Request
1curl --location --request POST '{API_BASE_URL}/v1/tokens' \
2--header 'Content-Type: application/x-www-form-urlencoded' \
3--data-urlencode 'client_id={CLIENT_ID}' \
4--data-urlencode 'client_secret={CLIENT_SECRET}' \
5--data-urlencode 'scope=Link-Core' \
6--data-urlencode 'grant_type=client_credentials'

Response Body

The two key values returned are the expires_in field which denotes the number of seconds that the token will be valid, and the access_token field which is the token itself.

Response
1{ 
2	 "token_type": "Bearer", 
3	 "expires_in": 3600, 
4	 "access_token": "{ACCESS_TOKEN}", 
5	 "scope": "Link-Core" 
6}

Making SDK Requests​

Linking customer bank accounts through Link Money's SDK requires a session key. To retrieve a session key, call the following endpoint with the appropriate customer details. Your auth token from step (1) must be included as a header to the API sessions endpoint or a 401 error will be returned.

This endpoint returns a session key to be used for SDK requests. Session keys are uniquely associated with each customer's session. When a customer wants to link a new account, a session key must be retrieved for them. The only mandatory fields in the session request are email, firstName and lastName. Additional data provided through the session API enables us to more accurately decision payments and enhance the user experience. Check out best practices to learn more about the data requested.

Endpoint
{API_BASE_URL}/v1/sessions

Request Body

  • email

    string

    Your customer’s email

  • firstName

    string

    Your customer’s first name

  • lastName

    string

    Your customer’s last name

  • phoneNumber

    string

    Your customer’s phone number

  • billingAddress

    object

    Your customer’s billing address. Max length of streetAddress is 200, city and stateOrProvince is 50; postalCode is 11.

  • shippingAddress

    object

    This field is a part of orderDetails. It is your customer’s shipping address. Max length of streetAddress is 200, city and stateOrProvince is 50; postalCode is 11.

  • items

    array of objects

    Each item should have a description (string), amount (object) and goodType (enum). The values for goodType are DIGITAL or PHYSICAL.

  • amount

    object

    This is the item’s cost and is part of the object passed in the items array.

  • totalAmount, subtotalAmount, discountAmount, shippingAmount, taxAmount

    object

    These fields are are part of order details and represent your customer’s transaction cost breakdown. These fields will only be accepted if the totalAmount field is provided, and subtotalAmount must be provided to include discountAmount, shippingAmount and taxAmount.

  • product

    enum

    PAY or VERIFY - indicates whether this session is for Pay by Bank or AccountVerify. Defaults to PAY

The following fields are part of the customerProfile object and are meant to collect customer information to provide the best experience possible by mitigating fraud, increasing authorization rate and maximizing risk decisioning accuracy

  • guestCheckout

    boolean

    Whether this is a registered or guest checkout.

  • accountCreationDate

    string

    Timestamp in ISO-8601 format e.g. "2023-12-30T07:00:00-04:00" and "2023-12-30T07:00:00.1234-04:00"

  • firstTransactionDate

    string

    Timestamp in ISO-8601 format e.g. "2023-12-30T07:00:00-04:00" and "2023-12-30T07:00:00.1234-04:00"

  • transactionCount

    integer

    The number of transactions a customer has previously made with the merchant.

  • verifiedEmail

    boolean

    Whether the customer’s email has been verified.

  • verifiedPhone

    boolean

    Whether the customer’s phone has been verified.

POST Request
1curl --location --request POST '{API_BASE_URL}/v1/sessions'
2--header 'Content-Type: application/json'
3--header 'Accept: application/json'
4--header 'Authorization: Bearer {ACCESS_TOKEN}'
5--data-raw '{
6  "firstName" : "{CUSTOMER_FIRST_NAME}",
7  "lastName" : "{CUSTOMER_LAST_NAME}",
8  "email" : "{CUSTOMER_EMAIL}",
9  "phoneNumber" : "{CUSTOMER_PHONE_NUMBER}",
10  "billingAddress" : {
11    "streetAddress": string,
12    "city": string,
13    "stateOrProvince": string
14    "postalCode": string,
15    "country": string 
16  },
17  "orderDetails": {
18    "items": [
19      {
20        "description": string,
21        "goodType": enum
22        "amount": { "value": float, "currency": "USD" }
23      },
24      {
25        "description": string,
26        "goodType": enum
27        "amount": { "value": float, "currency": "USD" }
28      }
29    ],
30    "subtotalAmount": { "value": float, "currency": "USD" },
31    "discountAmount": { "value": float, "currency": "USD" },
32    "shippingAmount": { "value": float, "currency": "USD" },
33    "taxAmount": { "value": float, "currency": "USD" },
34    "totalAmount": { "value": float, "currency": "USD" },
35    "shippingAddress": {
36      "streetAddress": string,
37      "city": string,
38      "stateOrProvince": string
39      "postalCode": string,
40      "country": string
41    },
42  },
43  "customerProfile":{
44    "guestCheckout": boolean,
45    "accountCreationDate": timestamp,
46    "transactionCount": integer,
47    "firstTransactionDate": timestamp,
48    "verifiedEmail": boolean,
49    "verifiedPhone": boolean
50  },
51  "product": "PAY" 
52}'
53

Response Body

  • sessionKey

    string

    Your session key

Response
{ "sessionKey" : "a5292de413e-2626d8244239-879a9-ffbdfa2" }