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 must submit relevant documentation to support the validity of its new bank account information.
This guide provides an overview of Change Requests, their importance, and how they impact different user levels.
Change Request Capabilities
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 and Merchants can do the following:
Note: Referrers can submit Change Requests on behalf of Merchants. This includes the following:
Updating bank account information from the Banking tab of the Merchant’s Profile page.
While logged in as the Merchant, updating 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.
Prevent Funding to an Existing Bank Account
You can 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 might want to prevent funds from being disbursed to or withdrawn from a Merchant’s existing bank account include, but are not limited to, the following:
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 |
CODE
PUT /accounts/{id} HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: api-test.payrix.com
APIKEY: {private_api_key}
|
Path Parameter | {id} - The account ID for the bank account you want to deactivate.
|
Request Body Example
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.
CODE
{
"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, you might encounter instances where you 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 the Account Maintenance articles:
The processes below 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:
Click here to see steps to Submit a Change Request in the Portal
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:
Navigate to the Banking tab and click ADD NEW ACCOUNT using one of the Portal pages below:
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.”
Upload any supporting documents 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 the following:
A void check
A bank letter
A bank statement
After 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:
Step 1: Create a new account or update an existing account.
Visit the Payrix API Documentation for parameter descriptions and valid values.
Request URL & Headers
CODE
POST /accounts HTTP/1.1
Content-Type: application/json
Host: api-test.payrix.com
APIKEY:{{private_api_key}}
Alternatively, you can use the 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.
CODE
PUT /accounts/{id} HTTP/1.1
Content-Type: application/json
Host: api-test.payrix.com
APIKEY:{{private_api_key}}
Example Request Body
JSON
{
"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
JSON
{
"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."
]
}
}
Step 2 - Create a new note associated with the entity (Merchant).
Create a Note Resource to Associate with an Entity and Documents - Example Code Snippet
Visit the Payrix API Documentation for parameter descriptions and valid values.
Request URL & Header
CODE
POST /notes HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: api-test.payrix.com
APIKEY:{{private_api_key}}
Example Request Body
JSON
{
"login": "t1_log_xxxxxxxxxxxxxxxx"
"entity": "t1_ent_xxxxxxxxxxxxxxxx",
"type": "note",
"data": "ABC Company Bank Account Change Request",
"note": "Supporting documents for account change.",
}
Example Response
JSON
{
"id": "t1_not_xxxxxxxxxxxxxxxxxx",
"created": "2023-10-25T19:10:44.278Z",
"modified": "2024-10-25T19:10:44.278Z",
"creator": "t1_log_xxxxxxxxxxxxxxxx",
"modifier": "t1_log_xxxxxxxxxxxxxxxx",
"login": "t1_log_xxxxxxxxxxxxxxxx",
"entity": "t1_ent_xxxxxxxxxxxxxxxxx",
"type": "note",
"data": "ABC Company Bank Account Change Request",
"note": "Supporting documents for account change.",
"inactive": "0",
"frozen": "0"
}
Step 3 - Create a new document (noteDocument) associated with the new Note.
Create a Document Resource to Associate with the Note - Example Code Snippet
Visit the Payrix API Documentation for parameter descriptions and valid values.
Request URL & Header
CODE
POST /noteDocuments HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: api-test.payrix.com
APIKEY:{{private_api_key}}
Example Request Body
JSON
{
"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
(for example, submitting a bank letter when voidCheck
is selected) can cause significant delays in underwriting approval.
Example Response
JSON
{
"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"
}
Step 4 - Upload the document file to the associated new document (noteDocument).
Upload the Image or Document File Associated with the Entity’s Note - Example Code Snippet
Visit the Payrix API Documentation for parameter descriptions and valid values.
Request URL & Header
CODE
POST /files/noteDocuments/{id} HTTP/1.1
Accept: application/json
Content-Type: multipart/form-data
Body: form-data
Host: api-test.payrix.com
Example Request Body (form-data)
CODE
name: Document Name
filename: <Selected File>
Example Request Body (JSON)
JSON
{
"credential": "string",
"type": "png",
"integration": "PAYRIX",
"direction": "upload",
"status": "pending",
"retries": 0,
"name": "Voided Bank Check for ABC Company",
"inactive": 0,
"frozen": 0
}
Example Response
JSON
{
"id": "t1_fil_xxxxxxxxxxxx",
"created": "2023-10-25T19:10:44.278Z",
"modified": "2023-10-25T19:10:44.278Z",
"creator": "t1_log_xxxxxxxxxxxxx",
"modifier": "t1_log_xxxxxxxxxxxxx",
"credential": "string",
"integration": "PAYRIX",
"name": "Voided Bank Check for ABC Company",
"file": "string",
"type": "png",
"status": "pending",
"retries": 0,
"direction": "upload",
"inactive": 0,
"frozen": 0
}
After submitting your Change Request, Payrix risk analysts 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:
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
As a Referrer or Merchant, 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, the Pending Change Requests queue ensures you’re constantly informed about the status of your Change Request.
Click here to see steps to view or cancel your Pending Change Requests in the Portal.
Navigate to the Banking tab using one of the Portal pages below:
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 side of any Pending Change Request listing.
Click here to see steps to view or cancel your Pending Change Requests via API.
Use the following API call to retrieve a pre-existing Change Request and view its status:
URL & Method
CODE
GET https://apiv2.stage.payrix.com/changeRequests/
Search Query
CODE
entity[equals]=t1_ent_6465433f7c283cbc472a771&deleted[exact]=null&model[equals]=accounts&status[in]=pending,manualReview
Headers
CODE
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:
Click here to see steps for viewing your Change Request History.
Click the Profile tab on the Portal Dashboard.
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. |
Click here to see steps for viewing all of your Change Request History.
Use the following API call to retrieve a complete list of all Change Requests for your login:
URL & Method
CODE
GET https://apiv2.stage.payrix.com/changeRequests/
Search Query
CODE
entity[equals]=t1_ent_6465433f7c283cbc472a771&deleted[exact]=null&model[equals]=accounts
Headers
CODE
Content-Type:application/json
APIKEY:{{private_api_key}}
Click here to see steps for viewing all Change Requests associated with a specific Login.
URL & Method
CODE
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
?expand[analyzedChangeRequests][]
Headers
CODE
Content-Type:application/json
APIKEY:{{private_api_key}}
Test Bank Account Change Requests in the Sandbox Environment
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 |