# Account Payment Details source: https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-money-transfer/index.md Tip: Account Payment Details supports [Feedback Loop Batch](https://developer.mastercard.com/open-finance-us/documentation/products/pay/feedback-loop/batch/index.md), which reduces payment failures by securely sharing payment outcome data with Mastercard, enabling us to identify and correct data quality issues. Contact your Customer Success Manager to participate. Retrieve a customer's account payment details for use in money transfers via ACH (Automated Clearing House) or other applicable rails. This is a premium endpoint - each successful call to this API results in a billable event. Account Payment Details provides the account number and routing number for use in an ACH transfer. This product is only supported for specific account types: checking, savings and money market accounts. If available, additional payment instruction types supported on the account are returned, indicating whether Real Time Payments (RTP) or FedNow Payments (Federal Reserve) are supported, and whether or not a [Tokenized Account Number](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-money-transfer/index.md#tokenized-account-numbers-tan) (TAN) was provided. Warning: While savings accounts are generally supported by this product, Chime does not allow external transfers to or from their savings accounts. Originating a payment from or sending funds into such an account will result in an ACH return. The `ach`, `rtp` and `fedNow` type details can be retrieved to initiate a payment for funds transfer: * The RTP type details indicate if the account can receive and/or send RTPs. It does not indicate if the account or financial institution is Request for Payment (RFP) enabled. * The FedNow type details indicate if the account can receive and/or send instant FedNow payments. It does not indicate if the account or financial institution is Request for Payment (RFP) enabled. * The "TAN enabled" flag indicates if the financial institution leverages a Tokenized Account Number (TAN) for payment initiation through that `paymentInstruction` type. * Note, if an account is verified manually using our instant or microdeposit solution, [Account Validation Assistant (AVA)](https://developer.mastercard.com/open-finance-us/documentation/products/pay/account-validation-assistant/index.md), the account is using the real account number and will never be represented by a TAN. ## How It Works {#how-it-works} 1. Generate the required credentials to call the API. See [Generate Your Credentials](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#generate-your-credentials) in the Quick Start Guide. 2. Generate an Access Token. See [Create Access Token](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#step-1---create-access-token) in the Quick Start Guide. 3. Create a customer and link them to at least one account. See [Welcome Your First Customer](https://developer.mastercard.com/open-finance-us/documentation/quick-start-guide/index.md#welcome-your-first-customer) in the Quick Start Guide (you will need to connect a checking and savings account using "Finbank" with the username and password "demo_rtn2"). 4. Call [Get Account Payment Details](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-money-transfer/index.md#api---get-account-payment-details) with a `customerId` and `accountId` to return the payment instruction details (ACH and, if applicable, RTP/FedNow money transfer details). Tip: To minimize risk of fraud, we highly recommend [verifying ownership](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-account-owner/index.md) and [checking the live balance](https://developer.mastercard.com/open-finance-us/documentation/products/pay/account-balance/index.md) of an account before originating a payment or funds transfer. Diagram account-ach Note: Before calling any Account Opening endpoints you should verify the FI concerned supports the service by checking our [Certified Institutions](https://developer.mastercard.com/open-finance-us/documentation/financial-institution/index.md#certified-institutions) list. ## API - Get Account Payment Details {#api---get-account-payment-details} API Reference: `GET /aggregation/v3/customers/{customerId}/accounts/{accountId}/details` Tip: Some FIs will return a tokenized version of the account number (this is indicated in the response by the `tanEnabled` flag). For details see [Tokenized Account Numbers (TAN)](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-money-transfer/index.md#tokenized-account-numbers-tan). ## Tokenized Account Numbers (TAN) {#tokenized-account-numbers-tan} A TAN is a tokenized version of the account number in the response to the Get Account ACH details call. Multiple institutions including Chase, PNC and US Bank will return a Tokenized Account Number (TAN) in place of the real account number. In the API response, a `tanEnabled` value of `true` indicates when a TAN was provided by the financial institution. TANs are specific to each application and therefore provide extra security for the customer. The variances of the TANs returned by Chase, PNC, and US Bank are explained in this table: | Scenario | Chase | PNC | US Bank | |------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | What actions should be taken to keep the TAN valid? | Ensure that the `customerId` is **not** deleted from the Mastercard Open Finance database. Proactively educate end users to avoid revoking data sharing consent from within their Chase banking portal. Accounts with an `aggregationStatusCode` of "0" can be assumed to have valid TANs as this status code indicates that the token has not been revoked. | Ensure that the `customerId` is **not** deleted from the Mastercard Open Finance production platform. Proactively educate end users to avoid revoking data sharing consent (see **"How is a TAN revoked?"** ). Accounts with an `aggregationStatusCode` of "0" can be assumed to have valid TANs as this status code indicates that the token has not been revoked. | No actions are required by data recipients to keep TANs valid for US Bank. | | Do TANs expire? | TANs issued by Chase do not expire. | TANs issued by PNC do not expire. This policy may change in the future. | TANs do not expire or get revoked for reasons other than fraud. | | When does a TAN become invalid? | The TAN becomes invalid when the user explicitly revokes data sharing consent or if the `customerId` or `institutionLoginId` are deleted via the delete customer endpoint. Invalid TANs will cause any new or pending payments using the TAN to fail. | The validity of the TAN is tied to the user's data sharing authorization. Only TANs issued against valid authorizations are eligible for payment. Invalid TANs will cause any new or pending payments using the TAN to fail. | TANs are only revoked when fraud is detected/reported. | | Does a user need to reconsent to maintain the validity of an existing TAN? | Reconsent for the purpose of maintaining the validity of an existing TAN is not required. | Reconsent for the purpose of maintaining the validity of an existing TAN is not required. | No. | | What is the TAN activation schedule? | TANs are activated and available for use in money movement immediately after generation. | PNC uses a batch activation schedule for TANs. Therefore, TANs are activated approximately 15-30 minutes post generation. Mastercard recommends waiting for 45 minutes after the TAN is generated before attempting money movement with PNC TANs. | ACH payments: May take between 15 to 35 minutes for activation. RTP/FedNow payments: Available immediately. | | How is a TAN revoked? | When the user explicitly revokes data sharing consent, or if the `customerId` or `institutionLoginId` is deleted from the Mastercard Open Finance database. If the TAN has been revoked, the user must reconsent to receive a new TAN. | PNC TANs are only valid if the user's data sharing authorization is valid. Any revocation or expiry of data sharing authorization will revoke a TAN. This includes when a `customerId` or `institutionLoginId` is deleted. PNC may operationally revoke a TAN for reasons including end user request or account fraud concerns. If the TAN has been revoked, the user must reconsent to receive a new TAN. | TANs are only revoked when fraud is detected/reported. Revocation by customers is not currently supported (US Bank may add this in future). If data sharing is revoked, expired, or broken, the TAN remains active if in good standing. | | Is there a way to know if a TAN is valid? | An `aggregationStatusCode` of "947" indicates that a token has been revoked. Accounts with an `aggregationStatusCode` of "0" can be assumed to have valid TANs as this status code indicates that the token has not been revoked. | An `aggregationStatusCode` of "947" indicates a token has been revoked. Accounts with an `aggregationStatusCode` of "0" can be assumed to have valid TANs as this status code indicates that the token has not been revoked. | This will be added in 2026, but given limited revocation of TANs at US Bank, this should not be an issue in the intermediate term. | | Are customers issued a new TAN if consent sharing was revoked but is later reauthorized? | Yes. Chase will issue a new TAN if consent was explicitly revoked and the user later reauthorized. Conversely, Chase will reissue the existing (same) TAN if the data sharing token expired due to non-usage and the user later reauthorized sharing. This occurs because token expiration does not lead to TAN revocation. | Yes. PNC will issue a new TAN if consent was explicitly revoked and the user later reauthorizes data sharing (and the 45-minute window has passed). If a TAN is operationally revoked by PNC (see **"How is a TAN revoked?"**), a new TAN will be issued once the customer reauthorizes. | If a customer has their account TAN revoked for a fraud use case, and they choose to re-authorize data sharing, a new TAN will be issued. | | What is the best practice for keeping TANs valid? | Educating the end user to avoid proactive consent revocation within their account portal is essential for TAN validity. | Once issued and activated, TANs will remain valid unless the `customerId` or `institutionLoginId` are deleted from the Mastercard Open Finance production platform or operationally revoked by PNC (see **"How is a TAN revoked?"**). | No actions are required by data recipients to keep TANs valid for US Bank. | ## Testing {#testing} In addition to the test data provided below, we have multiple [test banking profiles](https://developer.mastercard.com/open-finance-us/documentation/integration-and-testing/test-the-apis/index.md#account-opening-profiles) available to users to validate a wide range of different scenarios. If your specific integration requires more specific test cases, please contact your implementation specialist. ### Test Profiles {#test-profiles} | Username / Password | Finbank Types | Account Type(s) | |---------------------|---------------|-----------------------------------------------| | profile_03 | OAuth, Legacy | Checking, Savings | | profile_09 | OAuth, Legacy | Checking 1, Checkings 2, Savings | | profile_301 | OAuth, Legacy | Savings, Money Market, CD | | profile_2607 | OAuth, Legacy | Checking, Savings, Money Market | | profile_6203 | OAuth, Legacy | Business Checking, Business Savings, Checking | | profile_7002 | OAuth | Savings | | profile_7003 | OAuth | Checking | | profile_7093 | OAuth | Checking 1, Checkings 2, Savings 1, Savings 2 | | profile_8002 | OAuth | Savings 1, Savings 2 | ### Test Institutions {#test-institutions} | Institution Name | Connection Type | Customer Type | Use Case | |------------------------|-----------------|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Finbank OAuth Consent | OAuth | Testing | Direct hosted connection experience with account selection | | Finbank OAuth | OAuth | Testing | Direct hosted connection experience with automatic account selection | | Finbank OAuth TAN | OAuth | Testing | Direct hosted connection experience with a tokenized account number (TAN) | | Finbank OAuth Billable | OAuth | Active | Direct hosted connection experience for `active` customer testing (production) | | Finbank Profiles - A | Legacy | Testing | Mastercard hosted connection experience | | Finbank Profiles - B | Legacy | Testing | Mastercard hosted connection experience | | Finbank Billable | Legacy | Active | Mastercard hosted connection experience for `active` customer testing (production) | | Finbank Decertified | Legacy | Testing | Mastercard hosted connection experience to test [AVA](https://developer.mastercard.com/open-finance-us/documentation/products/pay/account-validation-assistant/index.md) flow | ## Common Errors {#common-errors} In the event that we encounter an issue at any point while requesting Account Payment Details, you will be informed by a response containing the error `code` and corresponding `message` explaining the issue and any possible resolution steps. While some commonly encountered errors are listed below, be sure to refer to our [Error Code](https://developer.mastercard.com/open-finance-us/documentation/errors/error-list/index.md) documentation page for an exhaustive list of potential errors and click on the link to review documentation for a specific code. | Code | HTTP Status | Brief Description | |-----------------------------------------------------------------------------------------------------------|-------------|---------------------------------------------------------------------------------------------| | [102](https://developer.mastercard.com/open-finance-us/documentation/errors/error-codes/102/index.md) | 500 | We are unable to establish a connection to the financial institution. | | [103](https://developer.mastercard.com/open-finance-us/documentation/errors/error-codes/103/index.md) | 500 | Invalid login credentials. | | [170](https://developer.mastercard.com/open-finance-us/documentation/errors/error-codes/170/index.md) | 500 | An error occurred in the financial institution connection. | | [325](https://developer.mastercard.com/open-finance-us/documentation/errors/error-codes/325/index.md) | 500 | The account is currently being aggregated. Retry later. | | [947](https://developer.mastercard.com/open-finance-us/documentation/errors/error-codes/947/index.md) | 500 | Token is invalid or has expired. Please have the user re-authenticate. | | [973](https://developer.mastercard.com/open-finance-us/documentation/errors/error-codes/973/index.md) | 500 | The user is not authorized for the requested resource or online access. | | [976](https://developer.mastercard.com/open-finance-us/documentation/errors/error-codes/976/index.md) | 500 | Requested resource does not exist. or is not supported. | | [978](https://developer.mastercard.com/open-finance-us/documentation/errors/error-codes/982/index.md) | 500 | An error occurred in the financial institution connection. | | [14006](https://developer.mastercard.com/open-finance-us/documentation/errors/error-codes/14006/index.md) | 404 | Institution not found or is not supported​ | | [14020](https://developer.mastercard.com/open-finance-us/documentation/errors/error-codes/14020/index.md) | 400 | Account type​ not supported. | | [20000](https://developer.mastercard.com/open-finance-us/documentation/errors/error-codes/20000/index.md) | 500 | Account Routing Number not found. | | [20001](https://developer.mastercard.com/open-finance-us/documentation/errors/error-codes/20001/index.md) | 500 | Real account number not found​.​ | | [20027](https://developer.mastercard.com/open-finance-us/documentation/errors/error-codes/20027/index.md) | 500 | Real account number and Routing Number not found. | | [38003](https://developer.mastercard.com/open-finance-us/documentation/errors/error-codes/38003/index.md) | 404 | The customer does not have the given account. This may be due to the account being deleted. | | [38057](https://developer.mastercard.com/open-finance-us/documentation/errors/error-codes/38057/index.md) | 404 | Payment details not found. | | [44000](https://developer.mastercard.com/open-finance-us/documentation/errors/error-codes/44000/index.md) | 202 | Service timeed out while attempting to aggregate information. | ## Fast ACH {#fast-ach} Fast ACH is our optimized Account Payment Details solution that enables a faster response to [Account Payment Details](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-money-transfer/index.md#api---get-account-payment-details) requests When Fast ACH is enabled, we proactively fetch the account and routing number details during the account linking process. is is advantageous if you have a time-sensitive use case, as in most cases, the data will be available before the user completes the account linking process. Fast AOV is offered at no additional charge. By default, we enable Fast AOV when you create a new production project and you are using account owner verification services. Fast AOV may not be right for all projects and is not supported by all institutions. Speak with your Account Manager about enabling or opting out of Fast AOV. Enabling the service for your project can take 2 to 5 business days. The following sequence diagram shows how Fast ACH, when available, allows the routing data to be fetched and cached during the account linking process: Diagram ach-cached ### Get Account ACH Details v1 (To Be Deprecated in 2027) {#get-account-ach-details-v1-to-be-deprecated-in-2027} This is a historical version of the Get Account ACH Details endpoint; new features and enhancements are being added to the [Get Account Payment Details](https://developer.mastercard.com/open-finance-us/documentation/products/pay/verification-money-transfer/index.md#api---get-account-payment-details) endpoint. API Reference: `GET /aggregation/v1/customers/{customerId}/accounts/{accountId}/details`