Versions Compared

Old Version 8

changes.mady.by.user Miles Graves

Saved on

compared with

New Version 9

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, manually (without using Plaid), that . This entity is required to submit 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 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.

...

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:

Info

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.

Referrers & Merchants can:

For Facilitators

...

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

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.

...

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.

...

{    "changes": {      "account": {

Request Parameters

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

Step 1: Create the Change Requesta new account or update an existing account.

URL & Method

Code Block
POST https://apiv2test-api.stage.payrix.com/changeRequestsaccounts
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}}

Example Request Body

Code Block
languagejson

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.

0- No reserve.

1- Account withheld.

3- Account usage pending manual review.

4- Move all funds from this Account into a reserve.

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

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": "",
        "payment": { 
          "numberdescription": "{{newAccountNumber}}", 
       
            "routingprimary": 1,
      "{{newRoutingNumber}}"
        } 
         "status": 0,
     },   },    "verifications": {      "entitycurrency": { 
      "idUSD": "{{assoicated entity's ID}}", 
    }, 
    "accounts": [ 
      { 
        "id": "1234",  
        "payment": { 
          "method": "method", 
          "number": "{existing account number}}", 
          "routing": "{{existing routing number}}", 
        } 
      } 
    ] 
  } 
} 

Example Response

Code Block
{
    "response": {
        "data": [,
            "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: Upload Supporting Documentation

URL & Method

Code Block
POST https://apiv2.stage.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)

Response Parameters

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

Timestamp for the Upload URL expiration.

...

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.

...