.png)
Managing Bank Account Change Requests
Change Requests are vital to managing and updating your account information within the Payrix Portal. The term “Change Requests” refers to an entity adding or updating their bank account information. This entity is required to submit documentation to support the validity of its new bank account info.
As this process requires manual review from a Payrix or Facilitator-level risk analyst, it cannot be instantly approved, so submissions made to add or change a bank account have been compiled into a set of easy-to-use Portal pages for each level of user to keep track or take action on their bank account change requests.
Automation of “manual” review for approval is anticipated to be integrated in early 2024.
This guide will provide an overview of Change Requests, their importance, and how they impact different user levels.
For Referrers & Merchants
Referrers and Merchants often need to make changes to their bank account information. The Change Request process allows added or changed account information to be submitted with documentation to support the change during risk analysis.
Referrers & Merchants can:
Note: Referrers can submit Change Requests on behalf of Merchants. This includes:
Updating bank account information from the Banking tab of the Merchant’s Profile page.
While logged in as the Merchant, update bank account information from the Banking tab of the Merchant’s Portal Account Profile.
Submitting an API call to the
/changeRequestsendpoint associated with the Merchant’s Login ID.
For Facilitators
Facilitators play a crucial role in handling change requests. Since Facilitators take on the responsibility of managing and mitigating their own risk, the Change Request management process provides full visibility of changes happening to bank accounts within their portfolio, to prevent risk hazards, such as money laundering, due to unverified or unauthorized bank accounts being added without notification.
Facilitators can:
Front End User Interface for Facilitators & Referrers
We recommend that Facilitators and Referrers with whitelabeled Portals and custom sites take additional steps to map and configure their front-end user interface (UI) to maximize user (Merchant) transparency and minimize communication times. Read more about these specific tips below:
We recommend Facilitators that use the Change Requests workflow above with an API integration to incorporate the following into your front-end user interface development:
Tip: Display Change Request Messages
When you submit or receive a Change Request using our API, consider incorporating a user-friendly notification system on your front-end interface.
This system can display the important messages related to that user’s change, such as Change Request Creation, Approval, or Decline status update notifications. These messages help users understand the progress of their Change Request(s) and stay informed about potential required actions.
Tip: Real-Time Status Updates
Implement real-time status updates within your UI to enhance transparency and user confidence. When Change Requests undergo status changes, whether pending, approved, or declined, promptly reflect these updates in your front-end interface.
This allows your users to track the progress of their Change Request without manually checking or calling your API.
Tip: Communicate Decline Reasons
When Change Requests are declined, ensure that the reason and reason type are communicated to your users. Design UI elements that can display the Reason Type and Reason in a user-friendly manner.
This provides transparency and empowers the users to take corrective actions if needed.
We recommend you configure Web Alerts and Email Alerts to pass “Declined”, “Approved”, or “Pending Review” Change Request statuses to your front-end interface for whitelabeled end-user communication.
Learn more about setting up Web Alerts (Webhooks).
Learn more about setting up Email Alerts.
Prevent Funding to an Existing Bank Account
To prevent funds from being sent to an existing account while the change request is being reviewed and approved, either as an optional feature for merchants to choose when submitted the bank change or as the default process for your software
Reasons that a Referrer or Facilitator may want to prevent funds from being disbursed to or withdrawn from a Merchant’s existing bank account include but are not limited to:
The Merchant’s bank account being closed by their bank due to reported fraudulent activity.
The Merchant’s bank account was closed by the merchant prior to the change request being approved.
The Merchant added incorrect bank account information by mistake that they do not want to use.
Request URL & Headers |
CODE
|
Path Parameter |
|
The following example changes the bank account's status parameter from 3 - [Fully] Verified to 1 - Ready [for verification] to remove the verification required to fund a bank account. In addition, you can optionally choose to change the inactive parameter to 1 - Inactive to also achieve a similar result.
Note: All other previous bank account information will remain the same in the request body. If you are unsure about the information of an existing account, you can make an API call to GET /accounts/{id} endpoint using the same path parameter to return the needed information in the response.
{
"id": "p1_act_5a1ef5e55656698eefaf8b6,",
"name": "TD Bank"
"primary": "0",
"type": "all",
"reserved": "0",
"inactive": "1",
"frozen": "0",
"status": "1",
}Change Request Management Flow
See the flowchart below for a visual understanding of the Change Request Management process flow:
Submit a Change Request
As a Referrer or Merchant, there are instances where you may need to update your bank account information or add a new bank account.
To learn more about the specifics of adding or updating a bank account, see our Account Maintenance articles:
The processes outlined below will outline how to submit a Change Request to update your or your Merchant’s bank account information.
Using the Portal
Submitting a change request using the Portal can be completed in a few simple steps along with easy upload of the supporting documents in a single process:
While Merchants can submit their Change Requests, Referrers have the unique ability to log in as the Merchant and submit Change Requests on behalf of a Merchant.
Submit a Change Request for bank account information by following the steps below:
Step 1: Navigate to the Banking tab and click the ADD NEW ACCOUNT button using one of the Portal pages below:
Your primary Referrer or Merchant Portal Account Profile page (located on the Dashboard), or;
Your desired Merchant’s profile page.
Step 2: If Plaid is unavailable for any reason, click ADD ACCOUNT MANUALLY. This will display the message below. Then, click Continue.
“Adding a new bank account will take up to 5 business days to verify, you can continue to use your current bank account until your new account is confirmed.
You will be required to upload a void check, bank statement, or bank letter to verify your account. Thank you for helping to keep your account safe.”
Step 3: Upload any supporting document(s) and click Save.
The bank account change request process requires a valid document upload to add a new account or change account and routing numbers for existing accounts.
Valid supporting documents include:
A Void Check,
A Bank Letter, or;
A Bank Statement.
Step 4: Once the change is made the Merchant or Referrer is provided the below message. Click Done to finish submitting the Change Request.
“Your changes have been made.
Your changes are currently being validated for review.”
Using the API
Submitting a Change Request using the API is a multi-part process. Follow each expandable step below for each applicable step to submit a change request for a bank account with supporting documentation:
Visit our API Documentation for parameter descriptions and valid values.
Request URL & Headers
POST /accounts HTTP/1.1
Content-Type: application/json
Host: api-test.payrix.com
APIKEY:{{private_api_key}}Alternatively, you can use endpoint with a PUT request method using the Account ID as a path parameter to update an existing account's information using the same parameters below.
POST /accounts/{id} HTTP/1.1
Content-Type: application/json
Host: api-test.payrix.com
APIKEY:{{private_api_key}}Example Request Body
{
"primary": 1,
"type": "all",
"status": 1,
"reserved": 1,
"currency": "USD",
"inactive": "0",
"frozen": "0",
"entity": "string",
"name": "string",
"description": "string",
"checkStage": "createAccount",
"expiration": "0529"
}Note: The parameter descriptions above apply to the data object parameters in the response as well.
Example Response
{
"response": {
"data": [
{
"account": {
"method": 8,
"number": 2345,
"routing": 3924,
"payment": null
},
"id": "p1_act_5a1ef5e55656698eefaf8b6",
"created": "2017-11-28T01:02:57.000Z",
"modified": "2017-11-28T01:02:57.000Z",
"creator": "p1_log_5a1ef5e55653ed720159d53",
"modifier": "p1_log_5a1ef5e55653ed720159d53",
"entity": "p1_ent_5a1ef5e5565631155c95344",
"token": "ae1abb3aaa18e4c374ca83fa75a7fff6",
"name": "",
"description": "",
"primary": 1,
"status": 0,
"currency": "USD",
"inactive": 0,
"frozen": 0
}
],
"details": {
"requestId": 1
},
"errors": [],
"messages": [
"Change request p1_chr_6513a1e2144ac0c8219c231 was created. This request may need to be reviewed and approved before taking effect."
]
}
}Create a Document Resource to Associate with the Note - Example Code Snippet
Visit our API Documentation for parameter descriptions and valid values.
Request URL & Header
POST /noteDocuments HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: api-test.payrix.com
APIKEY:{{private_api_key}}Example Request Body
{
"note": "t1_not_xxxxxxxxxxxxxxxxxx",
"type": "png",
"documentType": "voidCheck",
"description": "Updating Existing Bank Account.",
"name": "Voided Bank Check for ABC Company",
"status": "created",
inactive: "0",
frozen: "0"
}voidCheck is used in the example above, but any of the following documents can be used in this process:
voidCheck- A voided check for bank account verification.bankStatement- A bank statement.bankLetter- A bank letter for verification.
Warning: Submitting the wrong documentType (i.e. submitting a bank letter when voidCheck is selected) may cause significant delays in underwriting approval.
Example Response
{
"id": "t1_ntd_xxxxxxxxxxxxxxxxxx",
"created": "2024-08-18 13:22:51.2252",
"modified": "2024-08-18 13:22:51.2252",
"creator": "t1_log_xxxxxxxxxxxxxxxxxx",
"modifier": "t1_log_xxxxxxxxxxxxxxxxxx",
"note": "t1_not_xxxxxxxxxxxxxxxxxx",
"type": "png",
"documentType": "voidCheck",
"name": "Voided Bank Check for ABC Company",
"description": "Updating Existing Bank Account",
"status": "created",
"inactive": "0",
"frozen": "0"
}After submitting your Change Request, risk analysts from the Payrix platform (or your associated platform Facilitator) will conduct a review of the submitted account information and supporting documentation.
This submission will be Approved, meaning a manual review was conducted and the information submitted was validated and accepted; or Declined, followed by:
a note added to the Referrer or Merchant account, and;
an email to the user that submitted the Change Request with more detail explaining the review result and reason.
Read more about Declines below.
View Your Pending Change Requests
As a Referrer or Merchant, we understand that having a validated and ready-to-use bank account is critical to the operations of any business.
When submitting a Change Request for your existing bank account (or adding a new bank account), the waiting period can take up to 5 business days.
To provide clarity into the risk analysis process, we’ve introduced the Pending Change Requests queue to make sure you’re constantly informed about the status of your Change Request.
Step 1: Navigate to the Banking tab using one of the Portal pages below:
Your primary Referrer or Merchant Portal Account Profile page, or;
Your desired Merchant’s Profile page.
Step 2: Look for your previously submitted Change Request to be listed under Pending Change Requests.
Pending Change Requests Column Name | Description |
|---|---|
Fields | The fields you’re changing. |
New Value | The updated field values you’re changing (account and routing numbers). |
Date | The date you requested the change. |
Status | The review status of your Change Request. |
The “Status” field will display the current risk analysis review step in the process.
Pending Change Request Status | Description |
|---|---|
Manual Review | Your Change Request has been submitted and is still under risk analysis review. |
Approved | Your Change Request was reviewed and approved. |
Declined | Your Change Request was reviewed and declined. \ |
Note: You can cancel your Change Request at any time while in “Manual Review” status by clicking the cancel button (red “X”) on the right-hand side of any Pending Change Request listing.
Use the following API call to retrieve a pre-existing Change Request and view its status:
URL & Method
GET https://apiv2.stage.payrix.com/changeRequests/Search Query
entity[equals]=t1_ent_6465433f7c283cbc472a771&deleted[exact]=null&model[equals]=accounts&status[in]=pending,manualReviewHeaders
Content-Type:application/json
APIKEY:{{private_api_key}}You can also cancel a change request using the same API call above, by changing the HTTP method from GET to DELETE.
View Your Change Request History
As a Referrer or Merchant, there may be scenarios where validating previously submitted Change Requests may be helpful for auditing purposes.
The processes outlined below will demonstrate how to view or retrieve information about your previous Change Requests:
Step 1: Click the Profile tab on the Portal Dashboard.
Step 2: Click the Change Request History tab to see all listed Change Requests.
The Change Request History tab will display a list of all Change Requests submitted, whether pending, approved, or declined.
Pending Change Requests Column Name | Description |
|---|---|
Fields | The fields you’re changing. |
New Value | The updated field values you’re changing (account and routing numbers). |
Date | The date you requested the change. |
Status | The review status of your Change Request. |
The “Status” field will display the current risk analysis review step in the process.
Pending Change Request Status | Description |
|---|---|
Manual Review | Your Change Request has been submitted and is still under risk analysis review. |
Approved | Your Change Request was reviewed and approved. |
Declined | Your Change Request was reviewed and declined. |
Enable the Change Management Queue
As a Facilitator, enabling (or disabling) Referrers' and Merchants' ability to submit Change Requests using this workflow is important for testing and troubleshooting.
The processes outlined below demonstrate how to enable the Change Request queue and API functionality from the Partition level (your entire portfolio) or Division Level (manually grouped sets of entities):
Use the following API call to enable the Change Request Queue:
URL & Method
PUT https://test-api.payrix.com/partitions/or
PUT https://test-api.payrix.com/divisions/Warning: /divisions updates override any Change Management Setup configurations at a /partitions level.
Headers
Content-Type:application/json
APIKEY:{{private_api_key}}Body Parameters
Parameter | Type | Required | Description | Valid Values |
|---|---|---|---|---|
| string | Required | The Partition or Division ID | |
| boolean | Required | Enable or disable the Change Management Queue |
|
Example Request Body
For Partition
{
"id": "p1_ptn_xxxxxxxxxxxx",
"changeManagementEnabled": 1,
}For Division
{
"id": "p1_div_xxxxxxxxxxxx",
"changeManagementEnabled": 1,
}Viewing Your Change Requests Queue
As a Facilitator, seeing high-level data about Change Requests submitted by business (entity) owners in your portfolio is crucial to observing and quickly responding the those requests. We’ve compiled all past and current Change Requests into an independent tab on the Risk Management page.
The Change Request Queue will allow you to filter through requests, quickly respond after risk review, and sort based on date to ensure you’re responding in the order of requests received.
The process below will outline how to access the Change Requests Queue in the Portal:
Navigate to the Risk Management page.
Click Change Requests in the page tabs (located directly below the “Risk Management” page title).
API-based users looking to retrieve a list of all Change Requests under their Partition or Division should make the following call:
Respond to a Change Request (Approve or Decline)
As a Facilitator, you’ll need to respond to Change Requests that appear in your queue to keep your Merchants running smoothly. This can be done easily by using the Change Requests Queue in the Portal or updating a resource on the API server. First, you’ll need to evaluate the submitted documentation for risk review, and then you can respond to the Change Request.
Before you Approve or Decline a Change Request, you’ll need to evaluate the submitted documentation for risk review:
Step 1: Navigate to the Risk Management page.
Step 2: Click Change Requests in the page tabs (located directly below the “Risk Management” page title).
Step 3: Click the listed Merchant whose submitted Change Request documents you’re trying to view to access their Merchant Risk Profile page.
Step 4: Click on the Documents tab (under the Account Overview menu) to see a list of all uploaded documents.
If the document was submitted with a note using the Portal or the Payrix API it will appear in this list.
Step 5: Find the supporting Change Request document.
If there is no note or description with the document, you can check the upload date for a date corresponding with the date the Change Request was submitted.
Step 6: Click the vertical ellipses ⋮ on the right of the document listing to Download.
Tip: If you need this document for any API calls in the future, you can use the Copy ID option to copy the document ID to your clipboard.
Step 7: Review the documentation for accuracy and validity (not expired, matches business/owner information, is readable, etc.). After you’ve completed your review, you’re ready to respond to the Change Request with the next set of steps below.
The process below will outline the workflow to submit a response to a Change Request:
Step 1: Navigate to the Risk Management page.
Step 2: Click Change Requests in the page tabs (located directly below the “Risk Management” page title).
Step 3: Locate the Change Request you’d like to respond to and click the vertical ellipses ⋮ on the right of that listing to reveal the Change Request actions.
Note: If you want to acknowledge that you have received the Change Request but are not ready to Approve or Decline the Change Request, we recommend using the Mark as Reviewed option so that the update can be seen from the Merchant and Referrer Pending Change Requests queue.
Approve a Change Request:
Click Approve from the listed action options. This will approve the submitted Change Request.
A Create Note box will appear with the original Change Request information. You can choose to add additional information or make the note public before clicking the ADD button to complete the approval.
Decline a Change Request:
Click Decline from the listed action options. This will deny the submitted Change Request.
After clicking Decline, you’ll be required to select a Reason Type and leave a Reason as a written description expressing why the Change Request was denied. (See More on Declines below).
A Create Note box will appear with the original Change Request information. You can choose to add additional information or make the note public before clicking the ADD button to complete the approval.
You can also view previously declined Change Requests by clicking the Declined filter on the Change Requests tab.