Skip to content
payrocdevelopers

Set up a funding recipient

Create a funding recipient by sending a POST request to the Funding Recipients endpoint, enabling third-party entities such as charities to receive funds from your account.

Prerequisites: Authentication

Important: Before you begin, make sure that you have read our Getting Started guide, and that you have received your API key.

A funding recipient is an entity that can receive funds using funding instructions. Each funding recipient includes at least one of the following:

  • Funding account: The funding recipient’s bank account.
  • Owner: Individuals that are associated with the funding recipient.

You can create funding recipients for third parties that can’t directly process sales. For example, charities.

Integration steps

  • Create your funding recipient.

Before you begin

Authenticate your requests before making API calls. If your request fails, see Errors.

Create your funding recipient

To create your funding recipient, send a POST request to our Funding Recipients endpoint.

EnvironmentURL
Testhttps://api.uat.payroc.com/v1/funding-recipients
Productionhttps://api.payroc.com/v1/funding-recipients

To create the body of your request, use the following parameters:

Schema (request.body)

Request body schema for POST /funding-recipients

Note: Use our metadata feature to add custom information to your request.

Example request

Request

POST https://api.payroc.com/v1/funding-recipients

Create funding recipient

curl
curl -X POST https://api.payroc.com/v1/funding-recipients \
     -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "recipientType": "privateCorporation",
  "taxId": "12-3456789",
  "doingBusinessAs": "Pizza Doe",
  "address": {
    "address1": "1 Example Ave.",
    "address2": "Example Address Line 2",
    "address3": "Example Address Line 3",
    "city": "Chicago",
    "country": "US",
    "postalCode": "60056",
    "state": "Illinois"
  },
  "contactMethods": [
    {
      "type": "email",
      "value": "jane.doe@example.com"
    },
    {
      "type": "phone",
      "value": "2025550164"
    }
  ],
  "owners": [
    {
      "firstName": "Jane",
      "lastName": "Doe",
      "dateOfBirth": "1964-03-22",
      "address": {
        "address1": "1 Example Ave.",
        "city": "Chicago",
        "state": "Illinois",
        "country": "US",
        "postalCode": "60056"
      },
      "identifiers": [
        {
          "type": "nationalId",
          "value": "000-00-4320"
        }
      ],
      "contactMethods": [
        {
          "type": "email",
          "value": "jane.doe@example.com"
        },
        {
          "type": "phone",
          "value": "2025550164"
        }
      ],
      "relationship": {
        "isControlProng": true,
        "equityPercentage": 48.5,
        "title": "CFO",
        "isAuthorizedSignatory": false
      },
      "middleName": "Helen"
    }
  ],
  "fundingAccounts": [
    {
      "type": "checking",
      "use": "credit",
      "nameOnAccount": "Jane Doe",
      "paymentMethods": [
        {
          "type": "ach",
          "value": {
            "routingNumber": "123456789",
            "accountNumber": "1234567890"
          }
        }
      ]
    }
  ],
  "metadata": {
    "yourCustomField": "abc123"
  }
}'

Create funding recipient

Python
import requests

url = "https://api.payroc.com/v1/funding-recipients"

payload = {
    "recipientType": "privateCorporation",
    "taxId": "12-3456789",
    "doingBusinessAs": "Pizza Doe",
    "address": {
        "address1": "1 Example Ave.",
        "address2": "Example Address Line 2",
        "address3": "Example Address Line 3",
        "city": "Chicago",
        "country": "US",
        "postalCode": "60056",
        "state": "Illinois"
    },
    "contactMethods": [
        {
            "type": "email",
            "value": "jane.doe@example.com"
        },
        {
            "type": "phone",
            "value": "2025550164"
        }
    ],
    "owners": [
        {
            "firstName": "Jane",
            "lastName": "Doe",
            "dateOfBirth": "1964-03-22",
            "address": {
                "address1": "1 Example Ave.",
                "city": "Chicago",
                "state": "Illinois",
                "country": "US",
                "postalCode": "60056"
            },
            "identifiers": [
                {
                    "type": "nationalId",
                    "value": "000-00-4320"
                }
            ],
            "contactMethods": [
                {
                    "type": "email",
                    "value": "jane.doe@example.com"
                },
                {
                    "type": "phone",
                    "value": "2025550164"
                }
            ],
            "relationship": {
                "isControlProng": True,
                "equityPercentage": 48.5,
                "title": "CFO",
                "isAuthorizedSignatory": False
            },
            "middleName": "Helen"
        }
    ],
    "fundingAccounts": [
        {
            "type": "checking",
            "use": "credit",
            "nameOnAccount": "Jane Doe",
            "paymentMethods": [
                {
                    "type": "ach",
                    "value": {
                        "routingNumber": "123456789",
                        "accountNumber": "1234567890"
                    }
                }
            ]
        }
    ],
    "metadata": { "yourCustomField": "abc123" }
}
headers = {
    "Idempotency-Key": "8e03978e-40d5-43e8-bc93-6894a57f9324",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.json())

Create funding recipient

JavaScript
const url = 'https://api.payroc.com/v1/funding-recipients';
const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '8e03978e-40d5-43e8-bc93-6894a57f9324',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"recipientType":"privateCorporation","taxId":"12-3456789","doingBusinessAs":"Pizza Doe","address":{"address1":"1 Example Ave.","address2":"Example Address Line 2","address3":"Example Address Line 3","city":"Chicago","country":"US","postalCode":"60056","state":"Illinois"},"contactMethods":[{"type":"email","value":"jane.doe@example.com"},{"type":"phone","value":"2025550164"}],"owners":[{"firstName":"Jane","lastName":"Doe","dateOfBirth":"1964-03-22","address":{"address1":"1 Example Ave.","city":"Chicago","state":"Illinois","country":"US","postalCode":"60056"},"identifiers":[{"type":"nationalId","value":"000-00-4320"}],"contactMethods":[{"type":"email","value":"jane.doe@example.com"},{"type":"phone","value":"2025550164"}],"relationship":{"isControlProng":true,"equityPercentage":48.5,"title":"CFO","isAuthorizedSignatory":false},"middleName":"Helen"}],"fundingAccounts":[{"type":"checking","use":"credit","nameOnAccount":"Jane Doe","paymentMethods":[{"type":"ach","value":{"routingNumber":"123456789","accountNumber":"1234567890"}}]}],"metadata":{"yourCustomField":"abc123"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

Create funding recipient

go
package main

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

func main() {

	url := "https://api.payroc.com/v1/funding-recipients"

	payload := strings.NewReader("{\n  \"recipientType\": \"privateCorporation\",\n  \"taxId\": \"12-3456789\",\n  \"doingBusinessAs\": \"Pizza Doe\",\n  \"address\": {\n    \"address1\": \"1 Example Ave.\",\n    \"address2\": \"Example Address Line 2\",\n    \"address3\": \"Example Address Line 3\",\n    \"city\": \"Chicago\",\n    \"country\": \"US\",\n    \"postalCode\": \"60056\",\n    \"state\": \"Illinois\"\n  },\n  \"contactMethods\": [\n    {\n      \"type\": \"email\",\n      \"value\": \"jane.doe@example.com\"\n    },\n    {\n      \"type\": \"phone\",\n      \"value\": \"2025550164\"\n    }\n  ],\n  \"owners\": [\n    {\n      \"firstName\": \"Jane\",\n      \"lastName\": \"Doe\",\n      \"dateOfBirth\": \"1964-03-22\",\n      \"address\": {\n        \"address1\": \"1 Example Ave.\",\n        \"city\": \"Chicago\",\n        \"state\": \"Illinois\",\n        \"country\": \"US\",\n        \"postalCode\": \"60056\"\n      },\n      \"identifiers\": [\n        {\n          \"type\": \"nationalId\",\n          \"value\": \"000-00-4320\"\n        }\n      ],\n      \"contactMethods\": [\n        {\n          \"type\": \"email\",\n          \"value\": \"jane.doe@example.com\"\n        },\n        {\n          \"type\": \"phone\",\n          \"value\": \"2025550164\"\n        }\n      ],\n      \"relationship\": {\n        \"isControlProng\": true,\n        \"equityPercentage\": 48.5,\n        \"title\": \"CFO\",\n        \"isAuthorizedSignatory\": false\n      },\n      \"middleName\": \"Helen\"\n    }\n  ],\n  \"fundingAccounts\": [\n    {\n      \"type\": \"checking\",\n      \"use\": \"credit\",\n      \"nameOnAccount\": \"Jane Doe\",\n      \"paymentMethods\": [\n        {\n          \"type\": \"ach\",\n          \"value\": {\n            \"routingNumber\": \"123456789\",\n            \"accountNumber\": \"1234567890\"\n          }\n        }\n      ]\n    }\n  ],\n  \"metadata\": {\n    \"yourCustomField\": \"abc123\"\n  }\n}")

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

	req.Header.Add("Idempotency-Key", "8e03978e-40d5-43e8-bc93-6894a57f9324")
	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))

}

Create funding recipient

ruby
require 'uri'
require 'net/http'

url = URI("https://api.payroc.com/v1/funding-recipients")

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

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '8e03978e-40d5-43e8-bc93-6894a57f9324'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"recipientType\": \"privateCorporation\",\n  \"taxId\": \"12-3456789\",\n  \"doingBusinessAs\": \"Pizza Doe\",\n  \"address\": {\n    \"address1\": \"1 Example Ave.\",\n    \"address2\": \"Example Address Line 2\",\n    \"address3\": \"Example Address Line 3\",\n    \"city\": \"Chicago\",\n    \"country\": \"US\",\n    \"postalCode\": \"60056\",\n    \"state\": \"Illinois\"\n  },\n  \"contactMethods\": [\n    {\n      \"type\": \"email\",\n      \"value\": \"jane.doe@example.com\"\n    },\n    {\n      \"type\": \"phone\",\n      \"value\": \"2025550164\"\n    }\n  ],\n  \"owners\": [\n    {\n      \"firstName\": \"Jane\",\n      \"lastName\": \"Doe\",\n      \"dateOfBirth\": \"1964-03-22\",\n      \"address\": {\n        \"address1\": \"1 Example Ave.\",\n        \"city\": \"Chicago\",\n        \"state\": \"Illinois\",\n        \"country\": \"US\",\n        \"postalCode\": \"60056\"\n      },\n      \"identifiers\": [\n        {\n          \"type\": \"nationalId\",\n          \"value\": \"000-00-4320\"\n        }\n      ],\n      \"contactMethods\": [\n        {\n          \"type\": \"email\",\n          \"value\": \"jane.doe@example.com\"\n        },\n        {\n          \"type\": \"phone\",\n          \"value\": \"2025550164\"\n        }\n      ],\n      \"relationship\": {\n        \"isControlProng\": true,\n        \"equityPercentage\": 48.5,\n        \"title\": \"CFO\",\n        \"isAuthorizedSignatory\": false\n      },\n      \"middleName\": \"Helen\"\n    }\n  ],\n  \"fundingAccounts\": [\n    {\n      \"type\": \"checking\",\n      \"use\": \"credit\",\n      \"nameOnAccount\": \"Jane Doe\",\n      \"paymentMethods\": [\n        {\n          \"type\": \"ach\",\n          \"value\": {\n            \"routingNumber\": \"123456789\",\n            \"accountNumber\": \"1234567890\"\n          }\n        }\n      ]\n    }\n  ],\n  \"metadata\": {\n    \"yourCustomField\": \"abc123\"\n  }\n}"

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

Create funding recipient

Java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.payroc.com/v1/funding-recipients")
  .header("Idempotency-Key", "8e03978e-40d5-43e8-bc93-6894a57f9324")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"recipientType\": \"privateCorporation\",\n  \"taxId\": \"12-3456789\",\n  \"doingBusinessAs\": \"Pizza Doe\",\n  \"address\": {\n    \"address1\": \"1 Example Ave.\",\n    \"address2\": \"Example Address Line 2\",\n    \"address3\": \"Example Address Line 3\",\n    \"city\": \"Chicago\",\n    \"country\": \"US\",\n    \"postalCode\": \"60056\",\n    \"state\": \"Illinois\"\n  },\n  \"contactMethods\": [\n    {\n      \"type\": \"email\",\n      \"value\": \"jane.doe@example.com\"\n    },\n    {\n      \"type\": \"phone\",\n      \"value\": \"2025550164\"\n    }\n  ],\n  \"owners\": [\n    {\n      \"firstName\": \"Jane\",\n      \"lastName\": \"Doe\",\n      \"dateOfBirth\": \"1964-03-22\",\n      \"address\": {\n        \"address1\": \"1 Example Ave.\",\n        \"city\": \"Chicago\",\n        \"state\": \"Illinois\",\n        \"country\": \"US\",\n        \"postalCode\": \"60056\"\n      },\n      \"identifiers\": [\n        {\n          \"type\": \"nationalId\",\n          \"value\": \"000-00-4320\"\n        }\n      ],\n      \"contactMethods\": [\n        {\n          \"type\": \"email\",\n          \"value\": \"jane.doe@example.com\"\n        },\n        {\n          \"type\": \"phone\",\n          \"value\": \"2025550164\"\n        }\n      ],\n      \"relationship\": {\n        \"isControlProng\": true,\n        \"equityPercentage\": 48.5,\n        \"title\": \"CFO\",\n        \"isAuthorizedSignatory\": false\n      },\n      \"middleName\": \"Helen\"\n    }\n  ],\n  \"fundingAccounts\": [\n    {\n      \"type\": \"checking\",\n      \"use\": \"credit\",\n      \"nameOnAccount\": \"Jane Doe\",\n      \"paymentMethods\": [\n        {\n          \"type\": \"ach\",\n          \"value\": {\n            \"routingNumber\": \"123456789\",\n            \"accountNumber\": \"1234567890\"\n          }\n        }\n      ]\n    }\n  ],\n  \"metadata\": {\n    \"yourCustomField\": \"abc123\"\n  }\n}")
  .asString();

Create funding recipient

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

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.payroc.com/v1/funding-recipients', [
  'body' => '{
  "recipientType": "privateCorporation",
  "taxId": "12-3456789",
  "doingBusinessAs": "Pizza Doe",
  "address": {
    "address1": "1 Example Ave.",
    "address2": "Example Address Line 2",
    "address3": "Example Address Line 3",
    "city": "Chicago",
    "country": "US",
    "postalCode": "60056",
    "state": "Illinois"
  },
  "contactMethods": [
    {
      "type": "email",
      "value": "jane.doe@example.com"
    },
    {
      "type": "phone",
      "value": "2025550164"
    }
  ],
  "owners": [
    {
      "firstName": "Jane",
      "lastName": "Doe",
      "dateOfBirth": "1964-03-22",
      "address": {
        "address1": "1 Example Ave.",
        "city": "Chicago",
        "state": "Illinois",
        "country": "US",
        "postalCode": "60056"
      },
      "identifiers": [
        {
          "type": "nationalId",
          "value": "000-00-4320"
        }
      ],
      "contactMethods": [
        {
          "type": "email",
          "value": "jane.doe@example.com"
        },
        {
          "type": "phone",
          "value": "2025550164"
        }
      ],
      "relationship": {
        "isControlProng": true,
        "equityPercentage": 48.5,
        "title": "CFO",
        "isAuthorizedSignatory": false
      },
      "middleName": "Helen"
    }
  ],
  "fundingAccounts": [
    {
      "type": "checking",
      "use": "credit",
      "nameOnAccount": "Jane Doe",
      "paymentMethods": [
        {
          "type": "ach",
          "value": {
            "routingNumber": "123456789",
            "accountNumber": "1234567890"
          }
        }
      ]
    }
  ],
  "metadata": {
    "yourCustomField": "abc123"
  }
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
    'Idempotency-Key' => '8e03978e-40d5-43e8-bc93-6894a57f9324',
  ],
]);

echo $response->getBody();

Create funding recipient

C#
using RestSharp;

var client = new RestClient("https://api.payroc.com/v1/funding-recipients");
var request = new RestRequest(Method.POST);
request.AddHeader("Idempotency-Key", "8e03978e-40d5-43e8-bc93-6894a57f9324");
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"recipientType\": \"privateCorporation\",\n  \"taxId\": \"12-3456789\",\n  \"doingBusinessAs\": \"Pizza Doe\",\n  \"address\": {\n    \"address1\": \"1 Example Ave.\",\n    \"address2\": \"Example Address Line 2\",\n    \"address3\": \"Example Address Line 3\",\n    \"city\": \"Chicago\",\n    \"country\": \"US\",\n    \"postalCode\": \"60056\",\n    \"state\": \"Illinois\"\n  },\n  \"contactMethods\": [\n    {\n      \"type\": \"email\",\n      \"value\": \"jane.doe@example.com\"\n    },\n    {\n      \"type\": \"phone\",\n      \"value\": \"2025550164\"\n    }\n  ],\n  \"owners\": [\n    {\n      \"firstName\": \"Jane\",\n      \"lastName\": \"Doe\",\n      \"dateOfBirth\": \"1964-03-22\",\n      \"address\": {\n        \"address1\": \"1 Example Ave.\",\n        \"city\": \"Chicago\",\n        \"state\": \"Illinois\",\n        \"country\": \"US\",\n        \"postalCode\": \"60056\"\n      },\n      \"identifiers\": [\n        {\n          \"type\": \"nationalId\",\n          \"value\": \"000-00-4320\"\n        }\n      ],\n      \"contactMethods\": [\n        {\n          \"type\": \"email\",\n          \"value\": \"jane.doe@example.com\"\n        },\n        {\n          \"type\": \"phone\",\n          \"value\": \"2025550164\"\n        }\n      ],\n      \"relationship\": {\n        \"isControlProng\": true,\n        \"equityPercentage\": 48.5,\n        \"title\": \"CFO\",\n        \"isAuthorizedSignatory\": false\n      },\n      \"middleName\": \"Helen\"\n    }\n  ],\n  \"fundingAccounts\": [\n    {\n      \"type\": \"checking\",\n      \"use\": \"credit\",\n      \"nameOnAccount\": \"Jane Doe\",\n      \"paymentMethods\": [\n        {\n          \"type\": \"ach\",\n          \"value\": {\n            \"routingNumber\": \"123456789\",\n            \"accountNumber\": \"1234567890\"\n          }\n        }\n      ]\n    }\n  ],\n  \"metadata\": {\n    \"yourCustomField\": \"abc123\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Create funding recipient

swift
import Foundation

let headers = [
  "Idempotency-Key": "8e03978e-40d5-43e8-bc93-6894a57f9324",
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "recipientType": "privateCorporation",
  "taxId": "12-3456789",
  "doingBusinessAs": "Pizza Doe",
  "address": [
    "address1": "1 Example Ave.",
    "address2": "Example Address Line 2",
    "address3": "Example Address Line 3",
    "city": "Chicago",
    "country": "US",
    "postalCode": "60056",
    "state": "Illinois"
  ],
  "contactMethods": [
    [
      "type": "email",
      "value": "jane.doe@example.com"
    ],
    [
      "type": "phone",
      "value": "2025550164"
    ]
  ],
  "owners": [
    [
      "firstName": "Jane",
      "lastName": "Doe",
      "dateOfBirth": "1964-03-22",
      "address": [
        "address1": "1 Example Ave.",
        "city": "Chicago",
        "state": "Illinois",
        "country": "US",
        "postalCode": "60056"
      ],
      "identifiers": [
        [
          "type": "nationalId",
          "value": "000-00-4320"
        ]
      ],
      "contactMethods": [
        [
          "type": "email",
          "value": "jane.doe@example.com"
        ],
        [
          "type": "phone",
          "value": "2025550164"
        ]
      ],
      "relationship": [
        "isControlProng": true,
        "equityPercentage": 48.5,
        "title": "CFO",
        "isAuthorizedSignatory": false
      ],
      "middleName": "Helen"
    ]
  ],
  "fundingAccounts": [
    [
      "type": "checking",
      "use": "credit",
      "nameOnAccount": "Jane Doe",
      "paymentMethods": [
        [
          "type": "ach",
          "value": [
            "routingNumber": "123456789",
            "accountNumber": "1234567890"
          ]
        ]
      ]
    ]
  ],
  "metadata": ["yourCustomField": "abc123"]
] as [String : Any]

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

let request = NSMutableURLRequest(url: NSURL(string: "https://api.payroc.com/v1/funding-recipients")! 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()

If your request is successful, we create the funding recipient and return a response. The response contains the following fields:

Schema (response.body)

Response body schema for POST /funding-recipients

Example response

Response (201)

JSON
{
  "recipientType": "privateCorporation",
  "taxId": "12-3456789",
  "doingBusinessAs": "Pizza Doe",
  "address": {
    "address1": "1 Example Ave.",
    "address2": "Example Address Line 2",
    "address3": "Example Address Line 3",
    "city": "Chicago",
    "country": "US",
    "postalCode": "60056",
    "state": "Illinois"
  },
  "contactMethods": [
    {
      "type": "email",
      "value": "jane.doe@example.com"
    },
    {
      "type": "phone",
      "value": "2025550164"
    }
  ],
  "owners": [
    {
      "ownerId": 4564,
      "link": {
        "rel": "owner",
        "href": "https://api.payroc.com/v1/owners/4564",
        "method": "get"
      }
    }
  ],
  "fundingAccounts": [
    {
      "fundingAccountId": 123,
      "status": "pending",
      "link": {
        "rel": "fundingAccount",
        "href": "https://api.payroc.com/v1/funding-accounts/123",
        "method": "get"
      }
    }
  ],
  "recipientId": 234,
  "status": "pending",
  "createdDate": "2024-07-02T15:30:00+00:00",
  "lastModifiedDate": "2024-07-02T15:30:00+00:00",
  "metadata": {
    "yourCustomField": "abc123"
  }
}

Test cases

Our integration team provides you with test cases that you can run to verify that your integration works with our API.

For your next steps, we recommend that you follow our guide about sending funds to your funding recipients. To view other functions about managing your funding recipients, see funding recipients.

Browse guides

Search documentation

API reference169
Guides118
Knowledge38
legal1
Solutions32
Workflows74
↑↓highlight↵openView all search results

Menu

Theme

Sign out

Your saved plans remain in your organization. This browser’s private draft and account view will be cleared.

Talk to an engineer