Skip to main content

Payees

Introduction​

Payees in the system are entities that can participate in the flow of funds by are not the underlying merchant of record for a transaction. Payees in the system can be for either an Individual or Company. Any payments can be split to payees in the system (with some exceptions).

The Process for Adding Payees to the System is as Follows​

  1. Create a payee application via ui or Boarding API.
  2. Send the payee the link to complete the payee application
  3. Check the status of the payee in the ui or Boarding API, look for status ACTIVE. Alternatively, you can subscribe to the payee approved webhook event.
  4. Use the Payment Splits feature of payments to send funds to the payee.

Payee Application Creation UI​

To start with the Payee flow, create a Payee application using the Add Payee button. This will generate a Payee application link. You can then send this link out to the Payees that you will like to add to your Account.

Payee Application

Payee Application Creation API​

You can also create a Payee application using the API. You will need to specify the parent as well as the parent type. Please provide the parent_id and parent_type in the request body. At this time we support only PARTNER as the parent type. The parent is the partner that the payee will be associated with.

Example request:

curl -X POST --location 'https://<api-host>/payees/link' \
--header 'x-api-key: key_123456789' \
--header 'Content-Type: application/json' \
--data '{
    "parent_id": "part_xxxxxxxxx",
    "parent_type": "PARTNER",
}'

The response will contain the link to the Payee application which you can send programmatically.

{
    "payee_application_id": "ctrctapp_xxxxxxxxx",
    "link": "https://app.getfwd.com/payees/application/xxxxxxxxx",
    "payee_status": "UNDER_REVIEW"
}

Payee Application Form​

The payee that's being boarded can select to be an Individual or Company.

For an Individual Payee, we collect personal information such as:

  1. Full name
  2. Date of birth
  3. Contact details (address, phone number, email)
  4. Social Security Number or Tax Identification Number
  5. Banking information for split payments (account number, routing number)

For a Company Payee, the information will include:

  1. Company name
  2. Legal business structure (e.g., LLC, corporation)
  3. Tax Identification Number
  4. Details of owners of the company
  5. Company address
  6. Banking information for split payments (company account details)

Payee Application Form

Payee Workflow​

Payee Application Review:​

After a payee submits their application using the provided link, the application is received for review. The information submitted should be accessible and reviewable through the platform's UI or Boarding API.

Fetch Status:

curl --location 'https://<api-host>/payees/application/ctrctapp_xxxxxxxxx' \
--header 'x-api-key: key_123456789' \
--header 'Content-Type: application/json'

Response:

{
    "payee_application_id": "ctrctapp_xxxxxxxxx",
    "payee_status": "UNDER_REVIEW"
}

Status for the Application will be one of the following:

  1. APPROVED
  2. NEED_INFORMATION
  3. REJECTED
  4. UNDER_REVIEW
Note: NEED_INFORMATION is not a final status. You will need to resubmit the Application with the requested information.

If the Application is approved, a new payee entity will be created. You can fetch the status of the Payee using the following API:

curl --location 'https://<api-host>/payees/ctrct_xxxxxxxxx' \
--header 'x-api-key: key_123456789' \
--header 'Content-Type: application/json'

The status for the Payee will be one of the following:

  1. ACTIVE
  2. INACTIVE

Approval Process:​

The submitted information to ensure it meets our criteria and compliance standards. If everything is in order, we will approve the Payee application promptly.

Process a Payment to a Payee:​

Once the Payee application is approved, you can start splitting payments to the Payee.

{
  "payment_splits": [
    {
      "amount": 100,
      "description": "Application Fee",
      "account_id": "ctrct_xxxxxxxxxxx"
    }
  ]
}

Payee Management:​

Utilize the Payee Management feature in your system, accessible either through the UI or Boarding API. Enable or disable each payee based on your needs.

Real-time Webhook Events:​

The platform has event system that emits a specific event when a Payee is approved. This event could trigger further actions within your system or notify relevant stakeholders.

UI Access for Payee Management:​

You have the ability to manage Payees through the platform's UI. Users are be able to easily navigate through the list of Payees, view their details, and make necessary changes. Additionally you can manage which Payee should be active or deactivated.

Payee Management

Additional Resources​

Reviewing Payee Transactions​

curl "https://<api-host>/transactions" \
    -H  "x-contractor-id: ctrct_xxxxxxxxxxx" \
    -H  "x-api-key: key_123456789"