Quickstart

This Quickstart guide will take you through the process of retrieving necessary tokens for authentication, linking a customer’s bank accounts to Link Money’s services, and initiating payments from that customer’s account. By the end of it, you will be familiar with all of the requests needed to take your customers through Link Money’s entire user experience.

After following these steps, you will have successfully integrated with Link Money’s payment services! All that is left to do is to subscribe to our webhooks to be notified of events of interest, and follow our best practices guidelines to react to each webhook’s event.

NOTE: Visit the Integration page to fill in API_BASE_URL placeholders with the appropriate value.

1. Get 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

Copied!

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

Copied!

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

This step can be found in the Authentication page.

---

2. Get a Session Key

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

Copied!

{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

Copied!

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

Copied!

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

This step can be found in the Authentication page.

---

3. Use the SDK to link customer bank accounts

Now that you are authorized and have access to the SDK, you can use the SDK to link customer bank accounts. Note that the session key, not the auth token, is required to make this request. You will also need the URL which your customer will be redirected to by Link Money after the success or failure of linking their account. The production redirect URL must be pre-approved by Link Money to avoid malicious exploitations.

HTML Script

Copied!

<html>
<body>
	<button id="link-btn">Pay by Bank</button>
	<script type="module">
	import Link from 'https://static.link.money/linkmoney-web/v1/latest/linkmoney-web.min.js';

	document.addEventListener( 
		'DOMContentLoaded', 
		() => { 
			document 
				.getElementById('link-btn') 
				.addEventListener('click', async function () { 
					const config = { 
						sessionKey: '{SESSION_KEY}', 
						redirect: '{REDIRECT_URL}', 
						environment: 'production' | 'sandbox' 
					}; 

					const link = Link.LinkInstance(config); 
					link.action(); 
				}); 
			}, 
		false 
	);
	</script>
</body>
</html>

This step can be found in the JavaScript SDK page along with other ways of integrating the products functionality.

action() Method

Calling link.action() will redirect your customer to Link Money’s account-linking flow. After either success or failure, Link Money will redirect your customer back to your redirect URL provided in the Config with the following parameters.

Example

Copied!

{REDIRECT_URL}/?status=200&customerId={CUSTOMER_ID}

Status codes

• 200

  Payments can be made

  Successfully linked bank account

• 204

  Payments can NOT be made

  Customer exited voluntarily

• 500

  Payments can NOT be made

  Error occurred

For more details, as well as how to integrate with our mobile SDKs, visit the SDKs page.

---

4. Use the API to initiate payments

Once your customer has linked their account, you can call the API's payments endpoint to make a payment. The auth token is required to make this request. The customerId returned by the account linking process is also required. Note that the customerId should be stored in your backend systems for this and future payments requests.

This is a POST request.

Endpoint

Copied!

{API_BASE_URL}/v1/payments

Request Body

• source

  object

  Your customer’s ID - type is always CUSTOMER.

• destination

  object

  Your ID (provided by Link Money during onboarding process) - type is always MERCHANT.

• amount

  object

  Payment amount and currency. Payment amount must be a decimal number with a maximum of two decimal digits after decimal separator. “USD” is the only currency supported.

• clientReferenceId

  string *OPTIONAL

  Unique merchant-generated ID that identifies this payment. This ID is stored along with the payment request.

• softDescriptor

  string

  This is an optional freeform text field that will travel with the payment instruction to the RDFI. Please note that this information may or may not be displayed to the customer, based on the bank’s capabilities, and method of access (i.e., online banking, statement, etc.) - 80 Alphanumeric Character Limit.

• requestKey

  string

  Merchant-generated unique key for this specific payment call. This is used to avoid duplicate payment calls (idempotency). The payment call is rejected if a payment record already exists in the system with the same request key.

POST Request

Copied!

1curl --location --request POST '{API_BASE_URL}/v1/payments' \
2--header 'Content-Type: application/json' \
3--header 'Accept: application/json' \
4--header 'Authorization: Bearer {ACCESS_TOKEN}' \
5--data-raw '{ 
6	"source": { 
7		"id": "{CUSTOMER_ID}", 
8		"type": "CUSTOMER" 
9	}, 
10	"destination": { 
11		"id": "{MERCHANT_ID}", 
12		"type": "MERCHANT" 
13	}, 
14	"amount": { 
15		"currency": "USD", 
16		"value": 1.00 
17	}, 
18	"clientReferenceId": "{PAYMENT-RELATED_ID}", 
19	"softDescriptor": "{ENTRY_IN_CUSTOMER_BANK_STATEMENT}", 
20	"requestKey": "{UNIQUE_KEY}" 
21}'

Response Body

• clientReferenceId

  string *OPTIONAL

  Unique merchant-generated ID that identifies this payment. This ID is stored along with the payment request.

• paymentId

  string

  Link Money-generated payment-related ID

• paymentStatus

  enum

  PENDING or AUTHORIZED or TERMINAL_FAILED - indicates whether payment was initiated successfully

AUTHORIZED

Copied!

1{
2	"paymentId": "5914646d1-7ab5-9553-8389-db80c5c5dda",
3	"paymentStatus": "AUTHORIZED",
4	"clientReferenceId": "TXN-1234"
5}

TERMINAL_FAILED

Copied!

1{
2	"paymentId": "5914646d1-7ab5-9553-8389-db80c5c5dda",
3	"paymentStatus": "TERMINAL_FAILED",
4	"clientReferenceId": "TXN-1234",
5	"errorDetails": {
6		"errorCode": "PAYMENT_DECLINED",
7		"errorMessage": "Transaction amount is greater than the limit."
8	}
9}

PENDING

Copied!

1{
2	"paymentId": "5914646d1-7ab5-9553-8389-db80c5c5dda",
3	"paymentStatus": "PENDING",
4	"clientReferenceId": "TXN-1234"
5}

This step can be found in the APIs page.

---

5. Putting It All Together

• Please review the Integration section to identify various ways your integration can be tested. You will also find base URLs needed for invoking API calls.
• Link Money recommends that you obtain authorization tokens and session keys on your backend. Your client ID and client secret provided by Link Money should not be exposed outside of your backend. All authorization tokens should be confined to your backend as well.
• It is expected that you will implement an API endpoint for your frontend to obtain a session key to pass on to Link Money’s SDK
• Your session key endpoint must be an authenticated endpoint, i.e. your frontend must pass whatever authentication you use to verify the request
• It is also important that your session key endpoint only allows obtaining a session key for a specific customer
• You can initiate a payment in one of two ways depending on your desired user experience
  1. If the payment is initiated by the customer through your UI, you may want to implement a payment initiation endpoint with authorization on your backend which in turn calls Link Money’s payment API
  2. If payment is initiated by a backend process, such as a scheduled or recurring payment, your backend can directly invoke Link Money’s payment API