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, manually (without using Plaid), that is required to submit . This entity must submit relevant documentation to support the validity of their 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 manually 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.
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 information.
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 manually 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
/changeRequests
endpoint associated with the Merchant’s Login ID.
Referrers & Merchants can:
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.
...
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:
Expand | ||
---|---|---|
| ||
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
Real-Time Status Updates
Communicate Decline Reasons
|
...
As a Referrer or Merchant, there are instances where you may need to update your bank account information or add a new bank account.
Info |
---|
To learn more about the specifics of adding or updating a bank account, see our Account Maintanence articles: |
The processes outlined below will outline how to submit a Change Request to update your or your Merchant’s bank account information:
Expand | ||||
---|---|---|---|---|
| ||||
While Merchants can submit their own 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:
Step 2: If Plaid is unavailable for any reason, click ADD ACCOUNT MANUALLY. This will display the message below. Then, click Continue.
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:
Step 4: Once the change is made the Merchant or Referrer is provided the below message. Click Done to finish submitting the Change Request.
|
Expand | |||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||
Step 1: Create the Change Request URL & Method
Headers
Example Request Body
Example Response
Step 2: Upload Supporting Documentation URL & Method
Path Parameters | |||||||||||||
Parameter | Description | Valid Values | |||||||||||
| The type of entity adding a new bank account or editing an existing one. |
| |||||||||||
| The entity ID of the for the business submitting the Change Request. | ID’s beginning with |
Code Block |
---|
Content-Type:application/json
APIKEY:{{private_api_key}} |
Body Parameters
Parameter
Type
Required
Description
Valid Values
name
string
Required
Custom name for your document upload.
description
string
Custom string description for your document upload.
type
string
Required
Drivers License
Bank Document
Citizenship Document
documentType
string
Required
image/jpeg
image/gif
image/png
application/pdf
image/tiff
Example Request Body
Code Block | ||
---|---|---|
| ||
Tip | ||
Tip: 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.
|
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 submitting 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 has been closed by their bank due to reported fraudulent activity.
The Merchant’s bank account was closed by the merchant before the change request being approved.
The Merchant added incorrect bank account information by mistake that they do not want to use.
Request URL & Headers |
| ||
Path Parameter |
|
Expand | ||
---|---|---|
| ||
The following example changes the bank account's 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
|
...
Change Request Management Flow
See the flowchart below for a visual understanding of the Change Request Management process flow:
Lucidchart | ||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
...
Submit a Change Request
Anchor | ||||
---|---|---|---|---|
|
As a Referrer or Merchant, there are instances where you may need to update your bank account information or add a new bank account.
Info |
---|
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.
Tip |
---|
See Test Bank Account Change Requests in the Sandbox Environment for parameters that can be used to review the outcome of various Change Request results. |
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:
Expand | ||||
---|---|---|---|---|
| ||||
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:
Step 2: If Plaid is unavailable for any reason, click ADD ACCOUNT MANUALLY. This will display the message below. Then, click Continue.
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:
Step 4: Once the change is made the Merchant or Referrer is provided the below message. Click Done to finish submitting the Change Request.
|
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:
Expand | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||
Visit our API Documentation for parameter descriptions and valid values. Request URL & Headers
Example Request Body
Note: The parameter descriptions above apply to the Example Response
|
Expand | ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||
Create a Note Resource to Associate with an Entity and Documents - Example Code SnippetVisit our API Documentation for parameter descriptions and valid values. Request URL & Header
Example Request Body
Example Response
|
Expand | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||
Create a Document Resource to Associate with the Note - Example Code SnippetVisit our API Documentation for parameter descriptions and valid values. Request URL & Header
Example Request Body
Example Response
|
Expand | ||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||
Upload the Image or Document File Associated with the Entity’s Note - Example Code SnippetVisit our API Documentation for parameter descriptions and valid values. Request URL & Header
Example Request Body (form-data)
Example Request Body (JSON)
Example Response
Response Parameters | ||||||||||||||
Parameter | Type | Required | Description | |||||||||||
uuid | string | Required | Unique identifier of the document | |||||||||||
name | string | Required | The name of the document | description | string | A random description of the document | ||||||||
type | string | Required | The document type (Driver License, etc) | |||||||||||
ownership | string | Required | The owner of the document (facilitator, referrer or merchant) | |||||||||||
status | Enum | Required | Reviewed / Not reviewed | |||||||||||
CreatedAt | number | Required | Timestamp of when the Document is created | ExpiresAt | number | Timestamp for the S3 Upload URL and the database item TTL |
Code Block | ||
---|---|---|
| ||
{
"uuid": "{{UUID}}",
"name": "Void Check",
"description": "Void Check for bank account change - 9/30/23",
"type": "Bank Document",
"status": "Not Reviewed",
"ownership": "referrer",
"createdAt": "createdAt",
"downloadUrl": "<<Presigned Download URL>>"
} |
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.
...
title | More on Declines |
---|
Declines can occur for one of the following reasons:
...
Decline Reason
...
Description
...
Unable to validate
...
The information provided doesn't allow risk analysts to validate your information.
...
No Response
...
Analysts have followed up with additional questions and received no response.
...
Invalid Document
...
The document provided for review was not sufficient.
...
Unable to read
...
The document provided was unreadable.
...
Expired Document
...
The document provided has expired.
...
Other
...
Custom reason, filled out by reviewing Risk Analyst as needed.
These declines will be accompanied by a note added to your account from the reviewer.
...
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 manually adding a new bank account), the waiting period can take up to 5 business days.
...
|
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.
Decline Responses
When a submission is Declined, a reason and accompanying note will be added to your entity account by the reviewer. Declines can occur for one of the following reasons:
Decline Reason | Description |
---|---|
Unable to validate | The information provided doesn't allow risk analysts to validate your information. |
No Response | Analysts have followed up with additional questions and received no response. |
Invalid Document | The document provided for review was not sufficient. |
Unable to read | The document provided was unreadable. |
Expired Document | The document provided has expired. |
Other | Custom reason, filled out by reviewing Risk Analyst as needed. |
...
View Your Pending Change Requests
Anchor | ||||
---|---|---|---|---|
|
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.
Expand | ||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||||||||||||||
Step 1: Navigate to the Banking tab using one of the Portal pages below:
Step 2: Look for your previously submitted Change Request to be listed under Pending Change Requests.
|
Expand | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
Use the following API call to retrieve a pre-existing Change Request and view its status: URL & Method
Search Query
Headers
|
...
View Your Change Request History
Anchor | ||||
---|---|---|---|---|
|
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:
Expand | |||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||
Step 1: Navigate to Click the Banking Profile tab using one of the Portal pages below: Your primary Referrer or Merchant Portal Account Profile page, or; on the Portal Dashboard. Step 2: Look for your previously submitted Change Request to be listed under Pending Change RequestsClick 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.
|
Expand | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
Use the following API call to retrieve a pre-existing Change Request and view its status: URL & Method
Search Query
Headers
|
...
As a Referrer or Merchant, there may be scenarios where validating previously submitted Change Requests may be helpful for auditing purposes.
...
complete list of all Change Requests for your Login: URL & Method
Search Query
Headers
|
Expand | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
| ||||||||||
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. |
Info |
---|
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
viewing all Change Requests associated with a specific Login. |
URL & Method
Code Block |
---|
GET https://apiv2.stage.payrix.com/logins/{id} |
Path Parameters
Parameter | Description |
---|---|
{id} | The Login (User) ID of the business owner for the entity. |
Search Query
Code Block |
---|
?expand[analyzedChangeRequests][] |
Headers
Code Block |
---|
Content-Type:application/json
APIKEY:{{private_api_key}} |
...
Enable the Change Management Queue
Anchor | ||||
---|---|---|---|---|
|
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):
Expand | |||||||||
---|---|---|---|---|---|---|---|---|---|
|
Code Block |
---|
GET https://apiv2.stage.payrix.com/changeRequests/ |
Search Query
Code Block |
---|
entity[equals]=t1_ent_6465433f7c283cbc472a771&deleted[exact]=null&model[equals]=accounts |
Headers
Enabling the Change Management Queue using the Portal. |
Step 1: Navigate to one of the following pages below and click the Change Management Setup tab:
Partition Profile (only available to Facilitator users with an Admin user role.)
Division Profile (accessible by clicking on a listing from the Divisions page)
Step 2: Toggle the Change Management switch to “Enabled” to complete the Change Management Queue for your desired Partition or Division.
Expand | |||||
---|---|---|---|---|---|
| |||||
Code Block |
| ||||
Use the following API call to enable the Change Request Queue: URL & Method
or
Path Parameters | |||||
Parameter | Description | ||||
{id} | The Login (User) ID of the business owner for the entity. |
Code Block |
---|
?expand[analyzedChangeRequests][] |
Note |
---|
Warning: |
Headers
Code Block |
---|
Content-Type:application/json APIKEY:{{private_api_key}} |
...
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):
Expand | ||
---|---|---|
| ||
Step 1: Navigate to one of the following pages below and click the Change Management Setup tab:
Step 2: Toggle the Change Management switch to “Enabled” to complete the Change Management Queue for your desired Partition or Division. |
...
title | Click here to see steps for Enabling the Change Management Queue using the Payrix API. |
---|
Use the following API call to enable the Change Request Queue:
URL & Method
Code Block |
---|
PUT https://test-api.payrix.com/partitions/ |
or
Code Block |
---|
PUT https://test-api.payrix.com/divisions/ |
Note |
---|
Warning: |
Headers
Code Block |
---|
Content-Type:application/json
APIKEY:{{private_api_key}} |
Body Parameters
...
Parameter
...
Type
...
Required
...
Description
...
Valid Values
...
id
...
string
...
Required
...
The Partition or Division ID
...
changemanagementEnabled
...
boolean
...
Required
...
Enable or disable the Change Management Queue
...
1
- Enabled2
- Disablednull
- Disabled, not yet activated.
Example Request Body
For Partition
Code Block | ||
---|---|---|
| ||
{
"id": "p1_ptn_xxxxxxxxxxxx",
"changeManagementEnabled": 1,
} |
For Division
Code Block | ||
---|---|---|
| ||
{
"id": "p1_div_xxxxxxxxxxxx",
"changeManagementEnabled": 1,
} |
...
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 of the Risk Management page.
...
Body Parameters
Example Request Body For Partition
For Division
|
...
Viewing Your Change Requests Queue
Anchor | ||||
---|---|---|---|---|
|
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.
Expand | ||
---|---|---|
| ||
From the Change Requests Queue, you can:
|
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:
Expand | ||
---|---|---|
| ||
From the Change Requests Queue, you can:
|
The process below will outline how to access the Change Requests Queue in the Portal:
...
Navigate to the Risk Management page.
| ||||||||||||
URL & Method
Path Parameters
Headers
|
...
Respond to a Change Request (Approve or Decline)
Anchor | ||||
---|---|---|---|---|
|
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.
Expand | ||
---|---|---|
| ||
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). |
API-based users looking to retrieve a list of all Change Requests under their Partition or Division should make the following call:
...
title | Click here to see the details for retrieving all Change Requests using the API. |
---|
URL & Method
Code Block |
---|
GET https://apiv2.stage.payrix.com/changeRequests/{id} |
Path Parameters
...
Parameter
...
Type
...
Required
...
Description
...
id
...
string
...
Required
...
The Partition or Division ID
Headers
Code Block |
---|
Content-Type:application/json
APIKEY:{{private_api_key}} |
...
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.
...
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.
Step 5: Find the supporting Change Request document.
Step 6: Click the vertical ellipses ⋮ on the right of the document listing to Download.
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. |
Expand | ||
---|---|---|
| ||
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 verticle vertical ellipses ⋮ on the right of that listing to reveal the Change Request actions.
ApprovalApprove a Change Request:
Decline a Change Request:
|
Info | ||
---|---|---|
You can also view previously declined Change Requests by clicking the Declined filter on the Change Requests tab. | ||
Expand | ||
| ||
Declines can occur for one of the following reasons: | ||
Decline Reason | Description | |
Unable to validate | The information provided doesn't allow risk analysts to validate your information. | |
No Response | Analysts have followed up with additional questions and received no response. | |
Invalid Document | The document provided for review was not sufficient. | |
Unable to read | The document provided was unreadable. | |
Expired Document | The document provided has expired. | |
Other | Custom reason, filled out by reviewing Risk Analyst as needed. |
...
Test Bank Account Change Requests in the Sandbox Environment
Anchor | ||||
---|---|---|---|---|
|
Using the following bank account information, you can submit a manual change request that will be treated as a sandbox test when submitted in the Sandbox environment.
The routing numbers provided below will generate a specific automated risk decision for each type of Change Request result to help you better understand the process.
Note: You can use any 10 to 12-digit account number for US-based entities and 8 to 12-digit account number for Canada-based entities.
US-Based Entity Routing Number | Canada-Based Entity Routing Number | Change Request Decision Result |
---|---|---|
061000227 | 021000021 | Approved |
061092387 | 000281349 | Manual Review |
067014822 | 071025661 | Declined |