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
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.
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.
{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
orVERIFY
- indicates whether this session is for Pay by Bank or AccountVerify. Defaults toPAY
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
{ "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>
<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.
{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.
{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.
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
orAUTHORIZED
orTERMINAL_FAILED
- indicates whether payment was initiated successfully
1{
2 "paymentId": "5914646d1-7ab5-9553-8389-db80c5c5dda",
3 "paymentStatus": "AUTHORIZED",
4 "clientReferenceId": "TXN-1234"
5}
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}
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
- 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
- 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