Link your client's external bank account

In the Embedded Finance Payments API, a linked account is a type of recipient, and you use the recipients resource to add and manage them. 

A linked account is an external bank account that belongs to your client. This is a validated account associated with your client’s profile that you can use to make payments to your client from their Embedded Payments account.  Linked accounts are required for payout from a LIMITED_DDA and an optional recipient type that can be used to make payments from your client’s LIMITED_DDA_PAYMENTS account.

You can refer to Add third party payee as a recipient to understand how your client can make business payments to others using their LIMITED_DDA_PAYMENTS account.

About linked account validation

When you add a recipient of this type, the name and details are checked using an Account Validation Service (AVS). This means the account is checked to ensure it belongs to the named party, and that it can receive payments. In some cases, your client may be asked to complete a verification exercise, which is detailed in this guide. 

Add your client's linked account using partyId

You add a linked account using a POST /recipients request, referencing the partyId of the party who holds the external account. In your request: 

• The type property of the recipient must be LINKED_ACCOUNT
• Include the partyId of the party who owns this account. 

Sample request body:

Successful response showing that a linked account has been added and can be paid into using Embedded Payments: 

Add a linked account without partyId

If you don't know the partyId, you can use the account owner's name instead. This can be the first and last name of an individual or the business name as it appears on the account. The names provided must match the relevant names of the party details held by J.P. Morgan from your onboarding process:

Add multiple transaction methods

Validation of linked accounts sometimes requires microdeposits issued via ACH rails. To support this, your platform must ensure that all required information is provided to enable ACH payments when setting up a linked account for your client. This includes ACH routing numbers.

If you wish to use wire transfers or Real Time Payments (RTP) methods, you may need to include additional details about the recipient, as well as additional routing codes.  You can add wire transfers or RTP as optional methods of payment at time of linked account creation or update the linked account with the appropriate routing numbers for those payment methods once created.

At a glance, the minimum details of a linked account holder for each payment type are:

• Wire transfer:
  • Individual or business name. This name must exactly match the name of a business onboarded to Embedded Payments or its owners. 
  • Country code.
  • Address including City, State, Postal Code.
  • Routing and account numbers.
• ACH or direct payment:
  • Individual or business name. This name must exactly match the name of a business onboarded to Embedded Payments or its owners. 
  • Country code.
  • Routing and account numbers.
  • Account type (Checking or Savings).
• RTP:
  • Individual or business name. This name must exactly match the name of a business onboarded to Embedded Payments or its owners. 
  • Country code.
  • Routing and account numbers.

Table of mandatory fields for a linked account recipient

Routing Numbers

A linked account can have between 1-3 different routing numbers for ACH, Wire and RTP payments respectively. You can represent routing numbers and related information in the routingInformation object. Each routing number consists of:

• transactionType: the type of transaction. This can be RTP, ACH or WIRE
• routingCodeType: always USABA
• routingNumber: the routing number for this payment type

Verify a linked account with microdeposits

When you add a linked account for your client, a verification process is triggered. In most cases, this is a quick, automated check to make sure that the account is valid and that it belongs to your client.

The validation can be tracked in the status field of the response to a POST /recipients request. Most accounts are validated immediately, but sometimes you need to provide additional confirmation from your client.

In this case, two microdeposits (small undisclosed sums) are paid into the proposed linked account. Your client then needs to check the linked account and confirm the exact amount of each microdeposit. This confirms that your client has access to the linked account, and it can be validated.

Here's how the flow works from a user experience perspective:

1. Your client adds a new linked account, which you pass using POST /recipients with the type: "LINKED_ACCOUNT" as described in the sample payload above.

2. The 200 response contains status: "MICRODEPOSITS_INITIATED":

3. Two small deposits are made into your client's linked account, followed by one withdrawal (totaling the amount of the two deposits). This may take up to 3-5 business days to appear in your client's account.

4. The status of the linked account is updated to READY_FOR_VALIDATION, which can be checked with the GET /recipients/{id} endpoint.

5. You inform your client that the verification process has started. You explain that in 3-5 business days, they will be able to provide answers to verification questions about their account.

6. Through your UI, you advise your client that two microdeposits have been made into their account. For example, "Two low-value transactions have been made to your new linked account. Please check your account balance, and enter the value of each microdeposit here." Your client can then confirm the value of the two deposits for you to send via the API.

7. Your client's verification response must be sent within 20 business days after the microdeposits process has been initiated. You send your client's answer in the body of a POST /recipients/{id}/verify-microdeposit.request:

8. The response to POST /recipients/{id}/verify-microdeposit is returned with status: "VERIFIED":

9. You have completed the microdeposits verification. Your client can now make transactions to their linked account.

Linked account verification failure

If your client does not correctly answer the microdeposits verification question, the response to a POST /recipients/{id}/verify-microdeposit request is:

In this case, you can present your client with a user experience to try again.

They can have a maximum of 3 attempts.

After 3 attempts, if your client still fails to answer the question correctly, the response to: POST /recipients/{id}/verify-microdeposit request is:

If your client exceeds the maximum attempts and still answers incorrectly the recipient status will be updated to show as REJECTED in a request to GET /recipients/{id}: 

To resolve this, you must re-initiate the linked account process for your client. Your client can use the same account number or a different account number to link to their account.

Update routing information for an existing linked account

You may need to update details about a linked account to allow additional payment methods, such as wire or RTP transactions.

You can update details about a recipient using POST /recipients/{id}. In the payload, you  need to include all transaction type details in the account object you wish to add, including existing transaction type details.

In this example, a new wire and RTP routing numbers are added to a linked account:

Response: 

Remove a linked account

Your client can create one or multiple linked accounts at any given time. In order for your client to receive settlement from a LIMITED_DDA, your client must have at least one linked account operational. If your client wants to remove the external account, change the status of the linked account to "INACTIVE".

You can update the status of a linked account with a request to POST /recipients/{id}, with only the status field populated:

You can then add a new linked account in using the method described in this documentation. 

Reference

The following parameters are used in the recipients resource: 

Next steps

Now you can make a payout to your client's linked account.