Managing Bank Account Change Requests

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.

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.

Step 3: Upload any supporting document(s) and click Save.

Step 4: Once the change is made the Merchant or Referrer is provided the below message. Click Done to finish submitting the Change Request.

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}}

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"
}

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 Note Resource to Associate with an Entity and Documents - Example Code Snippet

Visit our API Documentation for parameter descriptions and valid values.

Request URL & Header

POST /notes HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: api-test.payrix.com
APIKEY:{{private_api_key}}

Example Request Body

{
  "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

{
  "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"
}

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"
}

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"
}

Upload the Image or Document File Associated with the Entity’s Note - Example Code Snippet

Visit our API Documentation for parameter descriptions and valid values.

Request URL & Header

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)

name: Document Name
filename: <Selected File>

Example Request Body (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

{
  "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
}

Declines can occur for one of the following reasons:

These declines will be accompanied by a note added to your account from the risk reviewer.

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.

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,manualReview

Headers

Content-Type:application/json
APIKEY:{{private_api_key}}

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.

Use the following API call to retrieve a complete list of all Change Requests for your Login:

URL & Method

GET https://apiv2.stage.payrix.com/changeRequests/

Search Query

entity[equals]=t1_ent_6465433f7c283cbc472a771&deleted[exact]=null&model[equals]=accounts

Headers

Content-Type:application/json
APIKEY:{{private_api_key}}

URL & Method

GET https://apiv2.stage.payrix.com/logins/{id}

Path Parameters

Search Query

?expand[analyzedChangeRequests][]

Headers

Content-Type:application/json
APIKEY:{{private_api_key}}

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.

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/

Headers

Content-Type:application/json
APIKEY:{{private_api_key}}

Body Parameters

Example Request Body

For Partition

{
  "id": "p1_ptn_xxxxxxxxxxxx",
  "changeManagementEnabled": 1,
}

For Division

{
  "id": "p1_div_xxxxxxxxxxxx",
  "changeManagementEnabled": 1,
}

From the Change Requests Queue, you can:

• Respond to Change Requests individually or in batches:

  • Approve - The Change Request was approved after manual risk review.

  • Decline - The Change Request was declined after a manual risk review.

  • Mark as Reviewed - The Change Request has been reviewed and is awaiting a decision.

• Sort Change Requests by:

  • User - The user name of the business (entity) owner that submitted the Change Request

  • Merchant - The associated Merchant who’s bank account is being changed.

  • Division - The division that the Merchant belongs to.

  • Days Boarded - The number of days the Merchant has successfully been boarded on the Payrix platform.

  • Fields - The fields being changed or added with the Change Request.

  • New Value - The field values being added or updated for each field.

  • Analyst - The name of the Risk Analyst who has reviewed and responded to the Change Request.

  • Change Date - The date the Change Request was submitted.

• Filter Change Requests by Status:

  • Manual Review - The Change Request was submitted and required a manual risk review.

  • Reviewed - The Change Request has been reviewed and is awaiting a decision.

  • Approved - The Change Request was approved after submission.

  • Declined - The Change Request was declined after submission.

  • Deleted - The initial Change Requests were deleted (cancelled) by the requesting user.

URL & Method

GET https://apiv2.stage.payrix.com/changeRequests/{id}

Path Parameters

Headers

Content-Type:application/json
APIKEY:{{private_api_key}}

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.

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.

Approve a Change Request:

1. Click Approve from the listed action options. This will approve the submitted Change Request.

2. 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:

1. Click Decline from the listed action options. This will deny the submitted Change Request.

2. 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).

3. 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.

Declines can occur for one of the following reasons:

These declines will be accompanied by a note added to your account from the risk reviewer.