Set Up an External Payer or Payee

Overview

Many payment flows involve a counterparty who is not, and never will be, a customer of your FinTech. A customer might wire money to their landlord, or receive an ACH credit from a relative. Synctera refers to these counterparties generically as external payers and payees. This guide assumes:

The structure is payment-rail agnostic — it works the same whether the money movement is ACH or wire.
The payer and payee are different people.
The payee is not a customer of your FinTech.

In the Synctera platform, an external payer or payee is modeled as:

A person or business, created with is_customer: false. This represents their identity for compliance and OFAC screening purposes, without putting them through KYC/KYB or giving them customer-level access.
An external account, created with a verification.status of UNVERIFIED. This represents their bank account at another institution.

Key characteristics:

Reuses the existing Persons, Businesses, and External Accounts APIs — no special endpoint for creating a payee itself.
Unverified accounts can only receive credits. To debit an external account (for example, to pull funds via ACH), the account must be verified. See the External Accounts guide for verification flows.
The link between a payer and their payee can be modeled explicitly with a PAYER_PAYEE party relationship, so you don’t have to maintain that mapping entirely on your own side.

Prerequisites

This guide assumes you are familiar with:

It also assumes you have already created the payer as a personal or business customer with an account. This guide covers only the payee side of the relationship. The curl examples authenticate with an apikey environment variable. Some examples depend on identifiers generated by previous steps; these are shown as placeholders like {PAYEE_ID}.

Adding a payee

Create the payee as a person or business

Create the payee with is_customer: false so they are represented on the platform without being treated as a customer. The more identifying information you provide, the better — it reduces the chance of an OFAC false positive later, and makes the payee easier to recognize if they are reused across multiple payers.For an individual payee, use POST /v2/persons:

curl \
  -X POST \
  -H "Authorization: Bearer $apikey" \
  -H 'Content-Type: application/json' \
  https://api.synctera.com/v2/persons \
  --data-binary '
  {
    "is_customer": false,
    "first_name": "Jane",
    "last_name": "Smith",
    "phone_number": "+14374570680",
    "status": "ACTIVE",
    "legal_address": {
      "address_line_1": "50 Main St",
      "city": "New York",
      "state": "NY",
      "postal_code": "12345",
      "country_code": "US"
    }
  }'

For a business payee, use POST /v2/businesses:

curl \
  -X POST \
  -H "Authorization: Bearer $apikey" \
  -H 'Content-Type: application/json' \
  https://api.synctera.com/v2/businesses \
  --data-binary '
  {
    "entity_name": "Apex Corporation",
    "formation_date": "2000-01-01",
    "is_customer": false,
    "status": "ACTIVE",
    "phone_number": "+14374570680",
    "legal_address": {
      "address_line_1": "50 Main St",
      "city": "New York",
      "state": "NY",
      "postal_code": "12345",
      "country_code": "US"
    }
  }'

Either call returns an id (for a person, customer_id; for a business, business_id) that you use to link the payee’s external account in the next step.

If the payee will receive a wire, collect at minimum a legal name and legal address — this is the minimum information needed to run an OFAC check without an unacceptable false-positive rate.

Add the payee's external account

Create an external account for the payee with POST /v2/external_accounts, passing the customer_id or business_id from the previous step. Because you have not independently verified that the payee owns this account, leave verification.status as UNVERIFIED and verification.vendor as MANUAL.Provide a routing number for every payment rail you intend to use — ach_routing_number for ACH, wire_routing_number for wires. Since this structure is rail-agnostic, a single external account can support both.

curl \
  -X POST \
  -H "Authorization: Bearer $apikey" \
  -H 'Content-Type: application/json' \
  https://api.synctera.com/v2/external_accounts \
  --data-binary '
  {
    "account_identifiers": {
      "number": "78277121"
    },
    "account_owner_names": [
      "Jane Smith"
    ],
    "routing_identifiers": {
      "bank_countries": [
        "US"
      ],
      "ach_routing_number": "756392185",
      "wire_routing_number": "915075033",
      "bank_name": "Chase"
    },
    "verification": {
      "vendor": "MANUAL",
      "status": "UNVERIFIED"
    },
    "customer_id": "7d943c51-e4ff-4e57-9558-08cab6b963c7",
    "customer_type": "PERSONAL"
  }'

For a business payee, set customer_type to BUSINESS and pass the business_id from Step 1 instead of customer_id.The response returns the external account id, used as the destination (or source) account when originating ACH or wire payments:

{
  "id": "{PAYEE_EXTERNAL_ACCOUNT_ID}",
  "customer_id": "7d943c51-e4ff-4e57-9558-08cab6b963c7",
  "account_identifiers": {
    "number": "78277121"
  },
  "account_owner_names": ["Jane Smith"],
  "routing_identifiers": {
    "bank_countries": ["US"],
    "ach_routing_number": "756392185",
    "wire_routing_number": "915075033",
    "bank_name": "Chase"
  },
  "verification": {
    "status": "UNVERIFIED",
    "vendor": "MANUAL"
  }
}

The account remains UNVERIFIED unless you run it through an independent verification flow. An unverified account can only receive credits — it cannot be debited. If your use case requires pulling funds from the payee (for example, an ACH debit), see Verification steps in the External Accounts guide.

Link the payer and payee

Record the relationship between your customer (the payer) and the payee with a PAYER_PAYEE party relationship, using POST /v2/relationships. Provide exactly one of from_person_id/from_business_id for the payer and one of to_person_id/to_business_id for the payee, plus additional_data.transfer_type to record which direction money is expected to move:

`transfer_type`	Use
`CREDIT`	The payer sends money to the payee (e.g. a wire to a landlord).
`DEBIT`	The payer pulls money from the payee (e.g. an ACH debit).
`DEBIT_OR_CREDIT`	Either direction is allowed.

curl \
  -X POST \
  -H "Authorization: Bearer $apikey" \
  -H 'Content-Type: application/json' \
  https://api.synctera.com/v2/relationships \
  --data-binary '
  {
    "relationship_type": "PAYER_PAYEE",
    "from_person_id": "{PAYER_CUSTOMER_ID}",
    "to_person_id": "{PAYEE_PERSON_ID}",
    "additional_data": {
      "transfer_type": "CREDIT"
    }
  }'

For a business payer or payee, use from_business_id or to_business_id in place of the person fields. The response returns the relationship id:

{
  "id": "{RELATIONSHIP_ID}",
  "relationship_type": "PAYER_PAYEE",
  "from_person_id": "{PAYER_CUSTOMER_ID}",
  "to_person_id": "{PAYEE_PERSON_ID}",
  "additional_data": {
    "transfer_type": "CREDIT"
  },
  "creation_time": "2026-08-26T18:09:12.881517Z"
}

Managing payer–payee relationships

List a payer’s payees

Use GET /v2/relationships, filtering by from_person_id (or from_business_id) and relationship_type=PAYER_PAYEE, to retrieve every payee linked to a given payer:

curl \
  -X GET \
  -H "Authorization: Bearer $apikey" \
  "https://api.synctera.com/v2/relationships?from_person_id={PAYER_CUSTOMER_ID}&relationship_type=PAYER_PAYEE"

Update a relationship

Change the transfer_type (for example, if a payee that could only receive credits is later verified for debits) with PATCH /v2/relationships/{RELATIONSHIP_ID}:

curl \
  -X PATCH \
  -H "Authorization: Bearer $apikey" \
  -H 'Content-Type: application/json' \
  https://api.synctera.com/v2/relationships/{RELATIONSHIP_ID} \
  --data-binary '
  {
    "additional_data": {
      "transfer_type": "DEBIT_OR_CREDIT"
    }
  }'

Remove a relationship

Delete the link with DELETE /v2/relationships/{RELATIONSHIP_ID}. This removes the payer–payee association only; the underlying person/business and external account are unaffected.

curl \
  -X DELETE \
  -H "Authorization: Bearer $apikey" \
  https://api.synctera.com/v2/relationships/{RELATIONSHIP_ID}

Best practices

Collect as much payee information as possible — beyond the minimum required fields, additional details (address, date of birth, etc.) reduce the chance of an OFAC false positive, especially for wires.
Always set is_customer: false for payees who are not onboarding as customers, so they are not mistakenly treated as account holders.
Leave new accounts UNVERIFIED unless you have independently confirmed ownership — this also enforces that the account can only receive funds, not be debited.
Provide a routing number for every rail you support — a single external account can carry both ach_routing_number and wire_routing_number.
Reuse existing payees — if a payee already exists as a person or business on your platform, link to the existing record and account instead of creating duplicates.
Use the PAYER_PAYEE relationship to query payees — filter GET /v2/relationships by from_person_id/from_business_id instead of building a separate mapping table.

Create a Personal Customer

Create the originating payer customer.

Create a Business Customer

Create a business payee or payer.

External Accounts

Verify an external account to enable debits.

Domestic Wires

Send a wire to an external payee.

Overview

Onboard a Personal Customer

Onboard a Business Customer

Create Accounts

Link External Accounts

Link External Cards

Issue Cards

Move Money

Get Transactions

Dispute Transactions

Platform Tools

Use Cases

Set Up an External Payer or Payee

Overview

Prerequisites

Adding a payee

Managing payer–payee relationships

List a payer’s payees

Update a relationship

Remove a relationship

Best practices

Create a Personal Customer

Create a Business Customer

External Accounts

Domestic Wires

API reference

​Overview

​Prerequisites

​Adding a payee

​Managing payer–payee relationships

​List a payer’s payees

​Update a relationship

​Remove a relationship

​Best practices

​Related guides

Create a Personal Customer

Create a Business Customer

External Accounts

Domestic Wires

​API reference

Overview

Prerequisites

Adding a payee

Managing payer–payee relationships

List a payer’s payees

Update a relationship

Remove a relationship

Best practices

Related guides

API reference