> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.mercoa.com/embedded-ap-ar/guides/accounts-receivable/creating-and-managing-payers/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.mercoa.com/_mcp/server.

In accounts receivable (AR), C3s are the payer entities that want to pay the invoices your customers send them through Mercoa. They can be individuals or businesses.

In Mercoa, you'll need to create a **payer** for each payer that your customers will be sending invoices to through your platform.

# Creating Payers

Payers can be created in the [dashboard](https://mercoa.com/dashboard) or with the [create entity](/api-reference/entity/create) endpoint, and linked to a customer using the [link payors](/api-reference/entity/counterparty/add-payors) endpoint.

They will also automatically be created and linked when one of your customers adds a new invoice recipient through the [React component](/react-library/overview) or embed.

## Creating the Payer Entity

Using the [create entity](/api-reference/entity/create) endpoint, create a new entity, and make sure the following fields are set:

```ts
{
  isPayee: false, // This marks the entity as unable to receive funds
  isPayor: true, // This marks the entity able to pay funds
  isCustomer: false // This indicates that you don't have a direct relationship with this entity (i.e., they are your customer's vendor)
}
```

This will automatically add the vendor to the `platform` network.

## Capturing Payer Details

Payer details are captured automatically during the accounts receivable flow using the [React components](/react-library/overview). The C2 must define who the customer they are sending an invoice to is when they create and send an invoice, and the customer-facing payment portal captures the remaining payer information needed to process the transaction.

## Adding the Payer to the Vendor as a Counterparty

If the C3 payer entity is created manually, you must manually link it to the vendor via API.

You can link the payer to any entity using the [link payors](/api-reference/entity/counterparty/add-payors) endpoint. This will create a relationship between the two entities, and allow the vendor to send invoices to the payer.

For example, if you have a vendor Entity with id `ent_8545a84e-a45f-41bf-bdf1-33b42a55812c`, and a payer Entity with id `ent_21661ac1-a2a8-4465-a6c0-64474ba8181d`, you can link them using the following request:

### Request

POST [https://api.mercoa.com/entity/\{entityId}/addPayors](https://api.mercoa.com/entity/\{entityId}/addPayors)

**`Default`**

```curl Default
curl -X POST https://api.mercoa.com/entity/ent_8545a84e-a45f-41bf-bdf1-33b42a55812c/addPayors \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "payors": [
    "ent_21661ac1-a2a8-4465-a6c0-64474ba8181d"
  ],
  "customizations": [
    {
      "counterpartyId": "ent_21661ac1-a2a8-4465-a6c0-64474ba8181d",
      "accounts": [
        {
          "accountId": "85866843",
          "postalCode": "94105",
          "nameOnAccount": "John Doe"
        }
      ]
    }
  ]
}'
```

**`Default`**

```python Default
import requests

url = "https://api.mercoa.com/entity/ent_8545a84e-a45f-41bf-bdf1-33b42a55812c/addPayors"

payload = {
    "payors": ["ent_21661ac1-a2a8-4465-a6c0-64474ba8181d"],
    "customizations": [
        {
            "counterpartyId": "ent_21661ac1-a2a8-4465-a6c0-64474ba8181d",
            "accounts": [
                {
                    "accountId": "85866843",
                    "postalCode": "94105",
                    "nameOnAccount": "John Doe"
                }
            ]
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

**`Default`**

```typescript Default
import { MercoaClient } from "@mercoa/javascript";

const client = new MercoaClient({ token: "YOUR_TOKEN" });
await client.entity.counterparty.addPayors("ent_8545a84e-a45f-41bf-bdf1-33b42a55812c", {
    payors: ["ent_21661ac1-a2a8-4465-a6c0-64474ba8181d"],
    customizations: [{
            counterpartyId: "ent_21661ac1-a2a8-4465-a6c0-64474ba8181d",
            accounts: [{
                    accountId: "85866843",
                    postalCode: "94105",
                    nameOnAccount: "John Doe"
                }]
        }]
});

```

**`Default`**

```go Default
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.mercoa.com/entity/ent_8545a84e-a45f-41bf-bdf1-33b42a55812c/addPayors"

	payload := strings.NewReader("{\n  \"payors\": [\n    \"ent_21661ac1-a2a8-4465-a6c0-64474ba8181d\"\n  ],\n  \"customizations\": [\n    {\n      \"counterpartyId\": \"ent_21661ac1-a2a8-4465-a6c0-64474ba8181d\",\n      \"accounts\": [\n        {\n          \"accountId\": \"85866843\",\n          \"postalCode\": \"94105\",\n          \"nameOnAccount\": \"John Doe\"\n        }\n      ]\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

**`Default`**

```ruby Default
require 'uri'
require 'net/http'

url = URI("https://api.mercoa.com/entity/ent_8545a84e-a45f-41bf-bdf1-33b42a55812c/addPayors")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"payors\": [\n    \"ent_21661ac1-a2a8-4465-a6c0-64474ba8181d\"\n  ],\n  \"customizations\": [\n    {\n      \"counterpartyId\": \"ent_21661ac1-a2a8-4465-a6c0-64474ba8181d\",\n      \"accounts\": [\n        {\n          \"accountId\": \"85866843\",\n          \"postalCode\": \"94105\",\n          \"nameOnAccount\": \"John Doe\"\n        }\n      ]\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body
```

**`Default`**

```java Default
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.mercoa.com/entity/ent_8545a84e-a45f-41bf-bdf1-33b42a55812c/addPayors")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"payors\": [\n    \"ent_21661ac1-a2a8-4465-a6c0-64474ba8181d\"\n  ],\n  \"customizations\": [\n    {\n      \"counterpartyId\": \"ent_21661ac1-a2a8-4465-a6c0-64474ba8181d\",\n      \"accounts\": [\n        {\n          \"accountId\": \"85866843\",\n          \"postalCode\": \"94105\",\n          \"nameOnAccount\": \"John Doe\"\n        }\n      ]\n    }\n  ]\n}")
  .asString();
```

**`Default`**

```php Default
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.mercoa.com/entity/ent_8545a84e-a45f-41bf-bdf1-33b42a55812c/addPayors', [
  'body' => '{
  "payors": [
    "ent_21661ac1-a2a8-4465-a6c0-64474ba8181d"
  ],
  "customizations": [
    {
      "counterpartyId": "ent_21661ac1-a2a8-4465-a6c0-64474ba8181d",
      "accounts": [
        {
          "accountId": "85866843",
          "postalCode": "94105",
          "nameOnAccount": "John Doe"
        }
      ]
    }
  ]
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

**`Default`**

```csharp Default
using RestSharp;

var client = new RestClient("https://api.mercoa.com/entity/ent_8545a84e-a45f-41bf-bdf1-33b42a55812c/addPayors");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"payors\": [\n    \"ent_21661ac1-a2a8-4465-a6c0-64474ba8181d\"\n  ],\n  \"customizations\": [\n    {\n      \"counterpartyId\": \"ent_21661ac1-a2a8-4465-a6c0-64474ba8181d\",\n      \"accounts\": [\n        {\n          \"accountId\": \"85866843\",\n          \"postalCode\": \"94105\",\n          \"nameOnAccount\": \"John Doe\"\n        }\n      ]\n    }\n  ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

**`Default`**

```swift Default
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "payors": ["ent_21661ac1-a2a8-4465-a6c0-64474ba8181d"],
  "customizations": [
    [
      "counterpartyId": "ent_21661ac1-a2a8-4465-a6c0-64474ba8181d",
      "accounts": [
        [
          "accountId": "85866843",
          "postalCode": "94105",
          "nameOnAccount": "John Doe"
        ]
      ]
    ]
  ]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.mercoa.com/entity/ent_8545a84e-a45f-41bf-bdf1-33b42a55812c/addPayors")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

## Finding Counterparties

Once you have created and linked payers to the vendor, you can use the [get counterparties](/api-reference/entity/counterparty/find-payors) endpoint to find the payers linked to the vendor.

### Request

GET [https://api.mercoa.com/entity/\{entityId}/counterparties/payors](https://api.mercoa.com/entity/\{entityId}/counterparties/payors)

**`Default`**

```curl Default
curl -G https://api.mercoa.com/entity/ent_8545a84e-a45f-41bf-bdf1-33b42a55812c/counterparties/payors \
     -H "Authorization: Bearer <token>" \
     --data-urlencode "name=Big Box" \
     -d paymentMethods=true \
     -d invoiceMetrics=true
```

**`Default`**

```python Default
import requests

url = "https://api.mercoa.com/entity/ent_8545a84e-a45f-41bf-bdf1-33b42a55812c/counterparties/payors"

querystring = {"name":"Big Box","paymentMethods":"true","invoiceMetrics":"true"}

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
```

**`Default`**

```typescript Default
import { MercoaClient } from "@mercoa/javascript";

const client = new MercoaClient({ token: "YOUR_TOKEN" });
await client.entity.counterparty.findPayors("ent_8545a84e-a45f-41bf-bdf1-33b42a55812c", {
    name: "Big Box",
    paymentMethods: true,
    invoiceMetrics: true
});

```

**`Default`**

```go Default
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.mercoa.com/entity/ent_8545a84e-a45f-41bf-bdf1-33b42a55812c/counterparties/payors?name=Big+Box&paymentMethods=true&invoiceMetrics=true"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

**`Default`**

```ruby Default
require 'uri'
require 'net/http'

url = URI("https://api.mercoa.com/entity/ent_8545a84e-a45f-41bf-bdf1-33b42a55812c/counterparties/payors?name=Big+Box&paymentMethods=true&invoiceMetrics=true")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

**`Default`**

```java Default
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.mercoa.com/entity/ent_8545a84e-a45f-41bf-bdf1-33b42a55812c/counterparties/payors?name=Big+Box&paymentMethods=true&invoiceMetrics=true")
  .header("Authorization", "Bearer <token>")
  .asString();
```

**`Default`**

```php Default
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.mercoa.com/entity/ent_8545a84e-a45f-41bf-bdf1-33b42a55812c/counterparties/payors?name=Big+Box&paymentMethods=true&invoiceMetrics=true', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();
```

**`Default`**

```csharp Default
using RestSharp;

var client = new RestClient("https://api.mercoa.com/entity/ent_8545a84e-a45f-41bf-bdf1-33b42a55812c/counterparties/payors?name=Big+Box&paymentMethods=true&invoiceMetrics=true");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

**`Default`**

```swift Default
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.mercoa.com/entity/ent_8545a84e-a45f-41bf-bdf1-33b42a55812c/counterparties/payors?name=Big+Box&paymentMethods=true&invoiceMetrics=true")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

## Hiding / Archiving Counterparties

If you don't want a counterparty to show up for an Entity in the counterparty search, you can hide them using the [hide payor from search](/api-reference/entity/counterparty/hide-payors) endpoint.

### Request

POST [https://api.mercoa.com/entity/\{entityId}/hidePayors](https://api.mercoa.com/entity/\{entityId}/hidePayors)

**`Default`**

```curl Default
curl -X POST https://api.mercoa.com/entity/ent_8545a84e-a45f-41bf-bdf1-33b42a55812c/hidePayors \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "payors": [
    "ent_21661ac1-a2a8-4465-a6c0-64474ba8181d"
  ]
}'
```

**`Default`**

```python Default
import requests

url = "https://api.mercoa.com/entity/ent_8545a84e-a45f-41bf-bdf1-33b42a55812c/hidePayors"

payload = { "payors": ["ent_21661ac1-a2a8-4465-a6c0-64474ba8181d"] }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

**`Default`**

```typescript Default
import { MercoaClient } from "@mercoa/javascript";

const client = new MercoaClient({ token: "YOUR_TOKEN" });
await client.entity.counterparty.hidePayors("ent_8545a84e-a45f-41bf-bdf1-33b42a55812c", {
    payors: ["ent_21661ac1-a2a8-4465-a6c0-64474ba8181d"]
});

```

**`Default`**

```go Default
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.mercoa.com/entity/ent_8545a84e-a45f-41bf-bdf1-33b42a55812c/hidePayors"

	payload := strings.NewReader("{\n  \"payors\": [\n    \"ent_21661ac1-a2a8-4465-a6c0-64474ba8181d\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

**`Default`**

```ruby Default
require 'uri'
require 'net/http'

url = URI("https://api.mercoa.com/entity/ent_8545a84e-a45f-41bf-bdf1-33b42a55812c/hidePayors")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"payors\": [\n    \"ent_21661ac1-a2a8-4465-a6c0-64474ba8181d\"\n  ]\n}"

response = http.request(request)
puts response.read_body
```

**`Default`**

```java Default
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.mercoa.com/entity/ent_8545a84e-a45f-41bf-bdf1-33b42a55812c/hidePayors")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"payors\": [\n    \"ent_21661ac1-a2a8-4465-a6c0-64474ba8181d\"\n  ]\n}")
  .asString();
```

**`Default`**

```php Default
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.mercoa.com/entity/ent_8545a84e-a45f-41bf-bdf1-33b42a55812c/hidePayors', [
  'body' => '{
  "payors": [
    "ent_21661ac1-a2a8-4465-a6c0-64474ba8181d"
  ]
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

**`Default`**

```csharp Default
using RestSharp;

var client = new RestClient("https://api.mercoa.com/entity/ent_8545a84e-a45f-41bf-bdf1-33b42a55812c/hidePayors");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"payors\": [\n    \"ent_21661ac1-a2a8-4465-a6c0-64474ba8181d\"\n  ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

**`Default`**

```swift Default
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = ["payors": ["ent_21661ac1-a2a8-4465-a6c0-64474ba8181d"]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.mercoa.com/entity/ent_8545a84e-a45f-41bf-bdf1-33b42a55812c/hidePayors")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```