# JPMC-PDP Documentation from https://developer.payments.jpmorgan.com # Link your client's bank account 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 payouts 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 your client’s LIMITED_DDA_PAYMENTS account. It is also required for a platform to pull funds via direct debit into the LIMITED_DDA or LIMITED_DDA_PAYMENTS account. You can refer to [Add third party payee as a recipient](/docs/embedded-finance-solutions/embedded-payments/capabilities/external-accounts/third-party-recipient) to understand how your client can make business payments to others using their LIMITED_DDA_PAYMENTS account. ## Account Validation Service (AVS) 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 party ID 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: ```json { "partyId": "2000000111", "account": { "number": "0182119492", "type": "CHECKING", "routingInformation": [ { "routingNumber": "122199983", "transactionType": "ACH", "routingCodeType": "USABA" } ], "countryCode": "US" }, "type": "LINKED_ACCOUNT", "clientId": "1000010400" } ``` Successful response showing that a linked account has been added and can be paid into using Embedded Payments: ```json { "clientId": "1000010400", "partyId": "2000000111", "id": "d9dab78e-e366-4dde-ac9d-fb3f9d48437b", "partyDetails": { "address": { "addressLine1": "90 Bedford Street", "addressLine2": "Apt 2E", "city": "New York", "countryCode": "US", "state": "NY", "postalCode": "10014" }, "firstName": "Monica", "lastName": "Gellar", "type": "INDIVIDUAL", "contacts": [ { "contactType": "PHONE", "countryCode": "+1", "value": "6316215110" } ] }, "account": { "number": "0182119492", "type": "CHECKING", "routingCodeType": "USABA", "routingNumber": "122199983", "countryCode": "US" }, "recipientType": "LINKED_ACCOUNT", "status": "ACTIVE", "createdAt": "2023-02-22T15:05:46.952+0000" } ``` ### Add a linked account without party ID 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: ```json { "partyDetails": { "type": "INDIVIDUAL", "firstName": "Monica", "lastName": "Gellar" }, "account": { "number": "0182119492", "type": "CHECKING", "routingInformation": [ { "routingNumber": "541798298", "transactionType": "ACH", "routingCodeType": "USABA" } ], "countryCode": "US" }, "type": "LINKED_ACCOUNT", "clientId": "1000010400" } ``` ## Account Confidence Score (ACS) Account Confidence Score (ACS) is an extension to Account Validation Service (AVS). When AVS validates an account, it can also return an ACS risk score that indicates the likelihood of fraud or compromise for the beneficiary account. ACS is available for both settlement accounts and third-party recipients. ACS is an optional, chargeable add-on feature. To implement the ACS feature, contact your implementation team. When you add a recipient and the account is validated using AVS, the response also includes an ACS fields. The ACS is a risk score. An AI-based machine learning model generates the score. It indicates the likelihood of fraud on a beneficiary account. The score uses billions of historical J.P. Morgan payment transaction records. It evaluates the account across multiple dimensions such as age, activity, location, payment history, known fraud, frequency and linkages. The ACS helps you assess fraud risk before you initiate a payment. The score is a value between zero and 1,000. It is mapped to a RAG (red, amber, green) status and description. The following table shows the score, status and description: **Understanding account confidence score response** | Score | RAG Status | Description | | --- | --- | --- | | 0 | Red | The account is associated with past activity that is indicative of potential fraud or compromise. | | Between 1 and 199 | Red | The account is in a low confidence score range. | | Between 200 and 599 | Amber | The account is in a medium confidence score range. | | Between 600 and 999 | Green | The account is in a high confidence score range. | | 1000 | Green | The account is in a high confidence score range. | The ACS score is included in the response when you add a recipient via a `POST /recipients` request, returned alongside the standard AVS validation result: Sample response: ```json { "accountScore": { "code": 750, "message": "GREEN", "description": "The account is in a high-confidence score range." } } ``` ## 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. ### Mandatory fields for a linked account recipient The following table outlines the mandatory recipient fields required to set up a linked account: **Mandatory fields by payment type** | Mandatory recipient fields | Required by payment types | | --- | --- | | Recipient type (Individual or Business) | All | | First name | All if recipient is an individual | | Last name | All if recipient is an individual | | Business name | All if recipient is a business | | Address line 1 | Wire only | | City | Wire only | | State | Wire only | | County | Wire only | | Country code | All | | Account type (checkings or savings) | ACH only | ### 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".

2. The 200 response contains `status: "MICRODEPOSITS_INITIATED"`: ```json { "id": "1051cd27-1957-4619-9ab5-c6f6dcb31d31", "partyDetails": { "type": "INDIVIDUAL", "firstName": "Monica", "lastName": "Gellar", "businessName": null, "contacts": null }, "partyId": "2000000111", "account": { "number": "93991289052", "type": "CHECKING", "routingInformation": [ { "routingNumber": "122199983", "transactionType": "ACH", "routingCodeType": "USABA" } ], "countryCode": "US" }, "type": "LINKED_ACCOUNT", "status": "MICRODEPOSITS_INITIATED", "clientId": "1000010400", "createdAt": "2024-08-27T16:50:50.870205533Z", "updatedAt": "2024-08-27T16:50:50.870210024Z", "accountValidationResponse": null } ```

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: ```json { "amounts": [ 0.51, 0.75 ] } ```

8. The response to `POST /recipients/{id}/verify-microdeposit` is returned with status: `"VERIFIED"`: ```json { "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: ```json { "status": "FAILED" } ``` 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: ```json { "status": "FAILED_MAX_ATTEMPTS_EXCEEDED" } ``` 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}`: ```json { "id": "1051cd27-1957-4619-9ab5-c6f6dcb31d31", "partyDetails": { "type": "INDIVIDUAL", "firstName": "Monica", "lastName": "Gellar", "businessName": null, "contacts": null }, "partyId": "2000000111", "account": { "number": "93991289052", "type": "CHECKING", "routingInformation": [ { "routingNumber": "122199983", "transactionType": "ACH", "routingCodeType": "USABA" } ], "countryCode": "US" }, "type": "LINKED_ACCOUNT", "status": "REJECTED", "clientId": "1000010400", "createdAt": "2024-08-27T16:50:50.870205533Z", "updatedAt": "2024-08-27T16:50:50.870210024Z", "accountValidationResponse": null } ``` 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: ```json { "account": { "number": "0182119492", "type": "CHECKING", "routingInformation": [ { "routingNumber": "021000021", "transactionType": "ACH", "routingCodeType": "USABA" }, { "routingNumber": "021000021", "transactionType": "WIRE", "routingCodeType": "USABA" }, { "routingNumber": "021000021", "transactionType": "RTP", "routingCodeType": "USABA" } ], "countryCode": "US" } } ``` Sample response: ```json { "id": "d9dab78e-e366-4dde-ac9d-fb3f9d48437b", "partyDetails": { "address": { "addressType": null, "addressLine1": "90 Bedford Street", "addressLine2": "Apt 2E", "addressLine3": null, "city": "New York", "state": "NY", "postalCode": "10014", "countryCode": "US" }, "type": "ORGANIZATION", "firstName": null, "lastName": null, "businessName": "Central Park Getaways", "contacts": [ { "contactType": "EMAIL", "countryCode": null, "value": "monica@cpgetaways.com" }, { "contactType": "PHONE", "countryCode": "+1", "value": "6316215110" } ] }, "partyId": "2000000111", "account": { "number": "122199983", "type": "CHECKING", "routingInformation": [ { "routingNumber": "021000021", "transactionType": "RTP", "routingCodeType": "USABA" }, { "routingNumber": "021000021", "transactionType": "WIRE", "routingCodeType": "USABA" }, { "routingNumber": "021000021", "transactionType": "ACH", "routingCodeType": "USABA" } ], "countryCode": "US" }, "type": "LINKED_ACCOUNT", "status": "ACTIVE", "clientId": "1000010400", "createdAt": "2024-11-20T14:17:34.664478Z", "updatedAt": "2024-11-20T14:18:29.856377Z", "accountValidationResponse": null } ``` ## 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: ```json { "status": "INACTIVE" } ``` You can now add a new linked account in using the method described in this documentation. ## Reference The following parameters are used in the `recipients` resource: **Parameter used in Recipients resource** | Field name | Description | Format | Example | | --- | --- | --- | --- | | clientId | Unique client identifier | <= 10 characters | 0030000132 | | type | Recipient type to return | Enum: "LINKED_ACCOUNT" | LINKED_ACCOUNT | | limit | Number of records per page (defaults to 25) | [1 .. 25] | 25 | | page | Page number (defaults to 0) | >=0 | 2 | | number | Demand deposit account number | <=35 characters | 0182119492 | | type | Type of bank account (checking or savings). Only required for ACH payments. Exclude field from payload completely if not needed | Enum: "CHECKING" / "SAVINGS" | CHECKING | | countryCode | Two letter country code (only US is supported at this time) | "US" | US | | id | A unique identifier for a recipient | 32 characters | 5e64a59d650842cfbabd4efd1f4d1556 | | routingCodeType | Type of routing code (only USABA is currently supported) | "USABA" | USABA | | routingNumber | Routing number corresponding to the routing code (only USABA compliant routing numbers are currently supported) | 9 digits | 541798298 | | addressType | Type of address (e.g. 'Primary Residence' | 'Principal place of business') | | Primary Residence | | addressLine 1 | Must not be a PO Box and must begin with a number | <=34 characters | 90 Bedford Street | | addressLine 2 | | <=34 characters | Apt 2E | | addressLine 3 | | <=34 characters | | | city | | <=34 characters | New York | | state | State code in alpha-2 format | <=30 characters | NY | | postalCode | Postal/ZIP code | <=10 characters | 10014 | | countryCode | Two letter country code based on ISO 3166 standard (only US is currently supported) | | US | | type | | Enum: "INDIVIDUAL" / "ORGANIZATION" | INDIVIDUAL | | firstName | Recipient's first name. Mandatory for recipient type INDIVIDUAL | <=70 characters | Monica | | lastName | Recipient's last name. Mandatory for recipient type INDIVIDUAL | <=70 characters | Gellar | | businessName | Recipient company name. Mandatory for recipient type ORGANIZATION | <=140 characters | Company Inc | | contactType | Type of contact information being provided | Enum: "EMAIL" / "WEBSITE" / PHONE" | PHONE | | countryCode | E.164 format compatible telephone country code | <=3 digits | +1 | | value | Contact information corresponding to contactType: PHONE (E.164-compliant telephone number (excluding country code)) EMAIL (addr-spec in Section 3.4 of RFC 5322), WEBSITE (URL starting with http:// or https://) | [ 1 .. 2048 ] characters | 6316215110 | | recipientId | A unique identifier for a recipient | 32 characters | 5e64a59d650842cfbabd4efd1f4d1556 | ## Next steps ### Link your client's external bank account Initiate a payout to your client's linked account to complete the transaction.