Versions Compared

Old Version 9

changes.mady.by.user Miles Graves

Saved on

compared with

New Version Current

changes.mady.by.user Miles Graves

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

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 must submit relevant 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:

...

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

  1. Updating bank account information from the Banking tab of the Merchant’s Profile page.

  2. While logged in as the Merchant, update bank account information from the Banking tab of the Merchant’s Portal Account Profile.

  3. Submitting an API call to the /changeRequests endpoint 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.

...

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
titleTipsRecommendation: Front-End User Interface API Integration for 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.

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.

...

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:

Expand
titleClick 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:

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.

Info

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

Info

“Your changes have been made.

Your changes are currently being validated for review.”

...

titleClick here to see steps to Submit a Change Request with the Payrix API

Step 1: Create a new account or update an existing account.

URL & Method

Code Block
POST https://test-api.payrix.com/accounts
Tip

Alternatively, you can use endpoint with a PUT request method to update an existing account's information using the same parameters below.

Headers

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

Request Parameters

...

Parameters

...

Type

...

Required

...

Description

...

Valid Values

...

entity

...

string

...

Required

...

The alphanumeric Entity ID associated with this Account.

...

name

...

string

...

A user-provided name for this bank account.

...

This field is stored as a text string and must be between 0 and 100 characters long.

...

description

...

string

A user-provided description for this bank account.

...

This field is stored as a text string and must be between 0 and 100 characters long.

...

primary

...

integer

...

Required

...

Indicates whether the Account is the 'primary' Account for the associated Entity.

...

Only one Account associated with each Entity can be the 'primary' Account.

...

type

...

string

...

Required

...

The type of financial account, debit, credit or both.

...

all - Debit/Checking + Credit

credit - Credit-Only

debit - Debit/Checking-Only

...

status

...

integer

...

Required

...

The status of the Account being ready to be added.

...

0 - Not Ready. Account holder is not ready to verify the account.

1 - Ready. Account is ready to be verified.

2 - Challeneged. The account has processed the challenge.

3 - Verified. The account has been verified.

4 - Manual. Issue during verification, required manual verification.

...

reserved

...

integer

...

Required

...

Indicates whether the Account will have a reserved placed on its funds.

...

checkStage

...

integer

...

The last stage completed for risk assessment.

...

createAccount - The final stage for review, add the account.

...

currency

...

integer

...

Required

...

The currency type for the account.

...

Any 3-digit currency symbol.

Default Value: USD

...

expiration

...

string

...

The expiration date of the related credit or debit account.

...

Format: MMYY

Example: February, 2025 = 0225

...

inactive

...

integer

...

Required

...

Whether this bank account is marked as ‘inactive’.

...

0 - Active

1 - Inactive

...

frozen

...

integer

...

Required

...

Whether this bank account is marked as ‘frozen’.

...

0 - Not Frozen

1 - Frozen

Example Request Body

Code Block
languagejson
{
  "primary": 1,
  "type": "all",
  "status": 1,
  "reserved": 1,
  "currency": "USD",
  "inactive": "0",
  "frozen": "0",
  "entity": "string",
  "name": "string",
  "description": "string",
  "checkStage": "createAccount",
  "expiration": "0529"
}

...

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

Code Block
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.

Expand
titleRequest 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 Block
{
  "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:

Lucidchart
pageCount1
autoUpdatetrue
aligncenter
typerich
autoSize1
macroId3dc6b808-6c75-4706-bc2d-2515fa4ca4f9
instanceId688e8386-c18b-322a-9462-f6b823009213
pages
width700
documentTokenv2_6229db14502e61f8c2b608c90548ae2c8139cb954e1b2ffa29ff9efaaf008464-a=129560282&c=688e8386-c18b-322a-9462-f6b823009213&d=513a5c38-aa06-430d-bdba-125c043b6547&p=23427711020
documentId513a5c38-aa06-430d-bdba-125c043b6547
updated1701460135846
height500

...

Submit a Change Request
Anchor
submit
submit

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
titleClick 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:

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.

Info

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

Info

“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:

Expand
titleStep 1: Create a new account or update an existing account.

Visit our API Documentation for parameter descriptions and valid values.

Request URL & Headers

Code Block
POST /accounts HTTP/1.1
Content-Type: application/json
Host: api-test.payrix.com
APIKEY:{{private_api_key}}
Tip

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.

Code Block
POST /accounts/{id} HTTP/1.1
Content-Type: application/json
Host: api-test.payrix.com
APIKEY:{{private_api_key}}

Example Request Body

Code Block
languagejson
{
  "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

Code Block
languagejson
{
    "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."
        ]
    }
}
: Upload Supporting DocumentationURL & Method

Response Parameters

Timestamp for the Upload URL expiration.
Expand
titleStep 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 our API Documentation for parameter descriptions and valid values.

Request URL & Header

Code Block
POST https://apiv2.stage /notes HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: api-test.payrix.com/entities/{entityType}/{entityId}/documents

Path Parameters

Parameter

Description

Valid Values

{entityType}

The type of entity adding a new bank account or editing an existing one.

merchant
referrer
facilitator

{entityId}

The entity ID of the business submitting the Change Request.

IDs beginning with t1_ent’s License, etc)

Parameter

Type

Description

Valid Values

uuid

string

Unique identifier of the document

name

string

The name of the document

description

string

A custom description of the document

type

string

The document type (Driver’s License, Bank Document, etc.)

ownership

string

The owner of the document.

merchant
referrer
facilitator

status

integer

Whether or not the uploaded document was reviewed by a risk analyst.

Reviewed
Not reviewed

createdAt

number

Timestamp of when the Document is created.

expiresAt

number


APIKEY:{{private_api_key}}

Example Request Body

Code Block
languagejson
{
  "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

Code Block
languagejson
{
  "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"
}

Expand
titleStep 3 - Create a new document (noteDocument) associated with the new Note.

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

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

Example Request Body

Code Block
languagejson
{
  "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"
}
Info

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.

Note

Warning: Submitting the wrong documentType (i.e. submitting a bank letter when voidCheck is selected) may cause significant delays in underwriting approval.

Example Response

Code Block
languagejson
{
  "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"
}
Expand
titleStep 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 our API Documentation for parameter descriptions and valid values.

Request URL & Header

Code Block
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 Block
name: Document Name
filename: <Selected File>

Example Request Body (JSON)

Code Block
languagejson
{
  "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

Code Block
languagejson
{
  "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, risk analysts from the Payrix platform (or your associated platform Facilitator) will conduct a review of the submitted account information and supporting documentation.

...

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

...

titleMore on Declines

...

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

...

Expand
titleClick here to see all features of the Change Requests Queue.

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 (cancelledCancelled) by the requesting user.

...

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

Info

You can also view previously declined Change Requests by clicking the Declined filter on the Change Requests tab.

Expand
titleMore 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.

...

Test Bank Account Change Requests in the Sandbox Environment
Anchor
test
test

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