Skip to main content

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
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}

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. Since session keys are associated with a single customer's session, a new session key must be retrieved for each customer, each time they want to link a new account.

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

  • product

    enum - OPTIONAL

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

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	"product" : "PAY" 
10}'

Response Body

  • sessionKey

    string

    Your session key

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

This step can be found in the Authentication page.

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
<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
{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
{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
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
1{
2	"paymentId": "5914646d1-7ab5-9553-8389-db80c5c5dda",
3	"paymentStatus": "AUTHORIZED",
4	"clientReferenceId": "TXN-1234"
5}
TERMINAL_FAILED
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
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