Skip to main content

APIs & Webhooks

Here you will find instructions for communicating with Link Money's APIs, including making payments, finding information of interest, and subscribing to webhooks to be notified of events.

Making Requests​

Using the Right URL​

Visit the Integration page to fill in API_BASE_URL placeholders with appropriate values.

Request Body​

All parameters are required unless otherwise stated.

Authentication​

Ensure you have a valid auth token attached as a header to all API requests. Visit the authentication page for instructions to retrieve your auth token.

Headers​

The following headers should be added to each API request along with the auth token (see examples below).

Content-Type: application/json

Accept: application/json

Accepting Responses​

Format​

API responses are in JSON format.

HTTP Status Codes​

All API endpoints return the following status codes.

  • 200

    Success

  • 400

    Bad Request

  • 401

    Unauthorized

  • 500

    Internal Server Error

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. 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. The payment call is rejected if a payment record already exists in the system with the same payment ID.

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

    Merchant-generated payment-related ID

  • paymentId

    number

    Link Money-generated payment ID

  • paymentStatus

    enum

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

Response
1{ 
2	"clientReferenceId": "898-jdhf-83784-jfss", 
3	"paymentId": 763743
4	"paymentStatus": "AUTHORIZED", 
5}

Initiate Refunds​

Once your customer has linked their account, you can call the API's payments endpoint to make a refund. The auth token is required to make this request. The customerId returned by the account linking process is also required. This is a POST request.
Endpoint
{API_BASE_URL}/v1/payments

Request Body

  • destination

    object

    Your customer’s ID - type is always CUSTOMER.

  • source

    object

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

  • amount

    object

    Refund amount and currency. Refund 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 refund. This ID is stored along with the payment request.

  • softDescriptor

    string

    This is an optional freeform text field that will travel with the refund 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. The payment call is rejected if a payment record already exists in the system with the same payment ID.

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	"destination": { 
7		"id": "{CUSTOMER_ID}", 
8		"type": "CUSTOMER" 
9	}, 
10	"source": { 
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

    Merchant-generated payment-related ID

  • paymentId

    number

    Link Money-generated payment ID

  • paymentStatus

    enum

    AUTHORIZED or TERMINAL_FAILED - indicates whether payment was initiated successfully

Response
1{ 
2	"clientReferenceId": "898-jdhf-83784-jfss", 
3	"paymentId": 763743
4	"paymentStatus": "AUTHORIZED", 
5}

Find Accounts by Customer ID​

Use this endpoint to retrieve account information for a given customer. This is a GET request.

Endpoint
{API_BASE_URL}/v1/customers/{CUSTOMER_ID}/accounts

Query Parameters​

  • customerId

    string

    Customer ID returned by account-linking process

GET Request
1curl --location --request GET '{API_BASE_URL}/v1/customers/{CUSTOMER_ID}/accounts' \
2--header 'Content-Type: application/json' \
3--header 'Accept: application/json' \
4--header 'Authorization: Bearer {ACCESS_TOKEN}'

Response Body​

  • customerId

    string

    Your customer ID

  • accountDetails

    object

    Details of customer’s bank account

Response
1{ 
2	"customerId": "{CUSTOMER_ID}", 
3	"accountDetails": 
4		[{ "accountId": 0, 
5		"financialInstitutionId": 0, 
6		"financialInstitutionName": "string", 
7		"logoUrl": "string", 
8		"iconUrl": "string", 
9		"accountLastFourDigits": "string", 
10		"accountType": "string", 
11		"accountStatus": "string", 
12		"preferred": boolean, 
13		"routingNumber": "string", 
14		"creationDate": "2022-05-27T18:36:47.630Z" }] 
15}

Find Transaction by ID​

Use this endpoint to retrieve details of a given transaction. This is a GET request.

Endpoint
{API_BASE_URL}/v1/transactions/{TRANSACTION_ID}

Query Parameters​

  • transactionId

    string

    Transaction ID returned from Initiate Payment endpoint

GET Request
1curl --location --request GET '{API_BASE_URL}/v1/transactions/{TRANSACTION_ID}' \
2--header 'Content-Type: application/json' \
3--header 'Accept: application/json' \
4--header 'Authorization: Bearer {ACCESS_TOKEN}'

Response Body​

  • transactionId

    string

    Your transaction ID

  • transactionType

    enum

    DEBIT or CREDIT

  • customerId

    string

    Associated customer ID

  • amount

    object

    Value and currency of transaction

  • clientReferenceId

    string

    Merchant-generated payment-related ID

  • transactionStatus

    enum

    CREATED or PENDING or AUTHORIZED or SCHEDULED or INITIATED or SUCCEEDED or RETRYABLE_FAILED or TERMINAL_FAILED

  • accountDetails

    object

    Details of associated bank account

  • descriptor

    string

    softDescriptor value passed to Initiate Payment API - appears in customer’s bank statement

  • settlementDate

    Date

    Date when payment is expected to settle

  • creationDate

    Date

    Date when transaction was initiated

  • transactionFailureReason

    object

    If applicable - details why payment failed

Response
1{ 
2	"transactionId": "{TRANSACTION_ID}", 
3	"transactionType": "string", 
4	"customerId": "string", 
5	"amount": { 
6		"value": 1, 
7		"currency": "string" 
8	}, 
9	"clientReferenceId": "string", 
10	"transactionStatus": "string", 
11	"accountDetails": { 
12		"financialInstitutionName": "string", "string", 
13		"accountLastFourDigits": "string", 
14		"accountType": "string", 
15		"preferred": boolean
16	}, 
17	"descriptor": "string", 
18	"settlementDate": "2022-05-27T19:27:57.971Z", 
19	"creationDate": "2022-05-27T19:27:57.971Z", 
20	"transactionFailureReason": { 
21		"code": "string", 
22		"description": "string" 
23	} 
24}

Find Payout by ID​

Use this endpoint to retrieve details of a given payout, i.e. an aggregate of transactions sent from Link Money to your bank account. This is a GET request.

Endpoint
{API_BASE_URL}/v1/payouts/{PAYOUT_ID}

Query Parameters​

  • payoutId

    string

    Your payout ID

GET Request
1curl --location --request GET '{API_BASE_URL}/v1/payouts/{PAYOUT_ID}' \
2--header 'Content-Type: application/json' \
3--header 'Accept: application/json' \
4--header 'Authorization: Bearer {ACCESS_TOKEN}'

Response Body​

  • payoutId

    string

    Your payout ID

  • amount

    object

    Value and currency of payout

  • payoutStatus

    enum

    CREATED or AUTHORIZED or SCHEDULED or INITIATED or DISBURSED

  • descriptor

    string

    Appears in your bank statement

  • creationDate

    Date

    Date when payout was initiated

Response
1{ 
2	"payoutId": "{PAYOUT_ID}", 
3	"clientReferenceId": "string", 
4	"amount": { 
5		"value": 1, 
6		"currency": "string" 
7	}, 
8	"payoutStatus": "string", 
9	"descriptor": "string", 
10	"creationDate": "2022-05-27T19:39:22.859Z" 
11}

Find Customer by ID​

Use this endpoint to retrieve details of a given customer. This is a GET request.

Endpoint
{API_BASE_URL}/v1/customers/{CUSTOMER_ID}

Query Parameters​

  • customerId

    string

    Customer ID returned by account-linking process

GET Request
1curl --location --request GET '{API_BASE_URL}/v1/customers/{CUSTOMER_ID}' \
2--header 'Content-Type: application/json' \
3--header 'Accept: application/json' \
4--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

Response Body​

  • id

    string

    Your customer ID

  • firstName

    string

    Customer’s first name

  • lastName

    string

    Customer’s last name

  • email

    string

    Customer’s email

  • customerStatus

    enum

    ACTIVE or CREATED or INACTIVE

  • accountDetails

    object

    Details of customer’s bank account

Response
1{ 
2	"id": "string", 
3	"firstName": "string", 
4	"lastName": "string", 
5	"email": "string", 
6	"customerStatus": "string", 
7	"accountDetails": { 
8		"financialInstitutionName": "string", 
9		"accountLastFourDigits": "string", 
10		"accountType": "string", 
11		"accountStatus": "string", 
12		"preferred": boolean, 
13		"creationDate": "2022-05-27T19:46:24.548Z" 
14	}, 
15	"creationDate": "2022-05-27T19:46:24.548Z" 
16}

Retrieve Account Data (AccountVerify)​

Once your customer has approved the sharing of account verification data with you, you can use this API to retrieve the account details for the customer.

Endpoint
{API_BASE_URL}/v1/customers/{CUSTOMER_ID}/account-verifications/accounts

Query Parameters​

  • customerId

    string

    Customer ID returned by the account verification request process

GET Request
1curl --location --request GET '{API_BASE_URL}/v1/customers/{CUSTOMER_ID}/account-verifications/accounts' \
2--header 'Content-Type: application/json' \
3--header 'Accept: application/json' \
4--header 'Authorization: Bearer {ACCESS_TOKEN}'

Response Body​

  • accounts

    array

    The list of accounts that have been verified for the specified customer ID

  • accountId

    string

    Unique identifier for the account

  • accountNumberDisplay

    string

    Displays the last four digits of the account number

  • bankId

    string

    Displays the routing number for the account

  • identifier

    string

    Displays the account number for the account

  • type

    string

    Displays the payment network type for which the bankId and identifier are used in delivery

Response
1{ 
2	"accounts": [ 
3		{ 
4			"depositAccount": {
5				"accountId": "11111111-1fff-1111-1111-000111111111", 
6				"accountNumberDisplay": "0001" 
7			}, 
8			"paymentNetworks": [{
9				"bankId": "000000000", 
10				"identifier": "00000000001", 
11				"type": "US_ACH" 
12			}], 
13		}, 
14		{ 
15			"depositAccount": {
16				"accountId": "22222222-2eee-2222-2222-2e2e2e2e2e2e", 
17				"accountNumberDisplay": "0002" 
18			}, 
19			"paymentNetworks": [{
20				"bankId": "000000000", 
21				"identifier": "00000000002", 
22				"type": "US_ACH" 
23			}], 
24		}, 
25	] 
26}

Get Session Key​

Linking customer bank accounts through Link Money's SDK requires a session key. Visit the authentication page for more details.

Webhooks​

Webhooks will help you stay updated on events happening within Link Money. Simply call Link Money's webhook endpoint with your URL included in the body, and Link Money will use that URL to notify you of all events of interest. Check out best practices to learn what actions to take for each event type.

In this section:

Subscribing to Webhooks​

Calling this endpoint will allow you to receive notifications for the events or categories of events you specify. This is a POST request.

Endpoint
{API_BASE_URL}/v1/webhook/subscribe

Request Body​

  • url

    URL

    Your URL where webhook notifications will be delivered

  • secretKey

    string

    A secret key, to be provided by Merchant, which will be used later to validate the authenticity of the webhook request

  • type

    enum

    EVENT or CATEGORY or ALL

  • details

    string

    If type is CATEGORY, this should be a list of ACCOUNT, CUSTOMER and/or PAYMENT. If type is EVENT, this should be a list of events from the events table below. If type is ALL, this value is irrelevant

POST Request
1curl --location --request POST '{API_BASE_URL}/v1/webhook/subscribe' \
2--header 'Content-Type: application/json' \
3--header 'Authorization: Bearer {ACCESS_TOKEN}' \
4--data-raw '{ 
5	"url":"{URL}", 
6	"secretKey":"{SECRET_KEY}", 
7	"subscriptionDetails" : { 
8		"type" : "CATEGORY", 
9		"details" : ["CUSTOMER","ACCOUNT","PAYMENT"] 
10	} 
11}'

Response Body​

  • subscriptionKey

    string

    Used to unsubscribe from webhooks

Response
1{ "subscriptionKey" : "4fa54dcce-32b9-8c8c-7344-1e8f4b41826" }

Unsubscribing from Webhooks​

Calling this endpoint will cause you to stop receiving notifications for the events or categories of events you specify. This is a PUT request.

Endpoint
{API_BASE_URL}/v1/webhook/unsubscribe

Request Body​

  • details

    array

    If type is CATEGORY, this should be a list of ACCOUNT, CUSTOMER and/or PAYMENT. If type is EVENT, this should be a list of events from the events table below. If type is ALL, this value is irrelevant

  • subscriptionId

    string

    Subscription key received when subscribing to webhook

  • type

    enum

    EVENT or CATEGORY or ALL

PUT Request
1curl --location --request PUT '{API_BASE_URL}/v1/webhook/unsubscribe' \
2--header 'Content-Type: application/json' \
3--header 'Accept: application/json' \
4--header 'Authorization: Bearer {ACCESS_TOKEN}' \
5--data-raw '{ 
6	"subscriptionId": "4fa54dcce-32b9-8c8c-7344-1e8f4b41826", 
7	"subscriptionDetails": { 
8		"type" : "CATEGORY", 
9		"details" : ["CUSTOMER","ACCOUNT","PAYMENT"] 
10	} 
11}'

Webhook Payload​

This is what will be included in webhook notifications sent to your specified URL.

  • id

    Webhook unique identifier

  • creationTime

    Webhook creation date and time

  • eventType

    Webhook event type / topic

  • clientReferenceId

    For payment events - only included if specified by merchant

  • resourceId

    Link Money resource ID i.e. customerId or paymentId

  • resourceType

    Resource type i.e. customer or payment

Payload Body
1{ 
2	"id": "97a4fcdf-9a08-4a59-a0c0-69bfd7e1d59d", 
3	"creationTime": "2017-09-14T17:14:39.688+0200", 
4	"eventType": "payment.authorized", 
5	"metadata" : { 
6		"clientReferenceId": "898-jdhf-83784-jfss", 
7		"resourceId": "83289-3299329-3299838934", 
8		"resourceType": "payment" 
9	} 
10}

Event Types​

  • customer.created

    Customer was created in Link Money Backend

    Occurs when user initiates account linking. Does not necessarily mean that customer account is linked or ready for payments

  • customer.activated

    Customer is ready for payments

    Occurs when a customer has linked a financial institution and selected a preferred account. Customer is ready for payments at this point

  • customer.deactivated

    Customer account is deactivated

    Occurs when a customer can no longer initiate payments, typically because customer revoked authentication to the linked account. Customer must re-link with a financial institution to be able to initiate payments again. See #relink# for more information about re-linking accounts

  • customer.account.linked

    Customer account has been selected as the preferred account for payment by the customer

    Occurs when a customer has successfully linked with a financial institution and selected an account as preferred account for payments

  • customer.account.deactivated

    Customer account is no longer available for payments

    An account can be deactivated for many reasons such as customer revoking access, authentication expiring or user MFA changing

  • payment.created

    Payment request was received

    Occurs when a payment request was received and recorded in Link Money Backend

  • payment.pending

    Payment is waiting for authorized or failed status

    Occurs when a payment request is awaiting Link Money Intelligence decision; usually followed by payment.authorized, the final decision is returned within 15 minutes. This may result in a payment.failed

  • payment.authorized

    Payment will be scheduled with Link Money’s payment provider

    Occurs when the Link Money Backend has determined that a payment will be scheduled with the payment provider

  • payment.scheduled

    Payment provider has been informed to schedule the payment

    Occurs when a payment request is scheduled to be processed, T+1 Day or T+2 Days. This schedule is determined based on the time when the payment was submitted. If the payment was submitted within the cutoff time, T+1 Day. If the payment was submitted after the cutoff time, T+2 Days

  • payment.initiated

    Payment was successfully initiated

    Occurs when the payment is scheduled with Link Money's payment provider

  • payment.succeeded

    Customer account was successfully debited to satisfy the payment request

    Occurs when the payment amount has been successfully debited from customer account. The amount will be disbursed to merchant according to the normal schedule

  • payment.disbursed

    Payment has been made whole

    Occurs when the given payment has been disbursed to the merchant as part of the normal disbursement schedule

  • payment.failed

    Payment has failed

    Occurs when the payment that was previously initiated has failed. To view the failure reason call Find Transaction by ID.