Fund merchants

Set up a funding recipient

View as Markdown

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.

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

Request

recipientTypeenumRequired
Type or legal structure of the funding recipient.
taxIdstringRequired
Employer identification number (EIN) or Social Security number (SSN).
doingBusinessAsstringRequired
Trading name of the business or organization.
addressobjectRequired
Polymorphic object that contains address information for a funding recipient.
contactMethodslist of objectsRequired
Array of polymorphic objects, which contain contact information. **Note:** You must provide an email address. The value of the type parameter determines which variant you should use: - `email` - Email address - `phone` - Phone number - `mobile` - Mobile number - `fax` - Fax number
ownerslist of objectsRequired
Array of owner objects. Each object contains information about an individual who owns or manages the funding recipient.
fundingAccountslist of objectsRequired
Array of fundingAccount objects that you can use to add funding accounts to the funding recipient.
charityIdstringOptional
Government identifier of the charity.
metadatamap from strings to stringsOptional
[Metadata](https://docs.payroc.com/api/metadata) object you can use to include custom data with your request.

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

Example request

POST
/v1/funding-recipients
1curl -X POST https://api.payroc.com/v1/funding-recipients \
2     -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
3     -H "Authorization: Bearer <token>" \
4     -H "Content-Type: application/json" \
5     -d '{
6  "recipientType": "privateCorporation",
7  "taxId": "12-3456789",
8  "doingBusinessAs": "Pizza Doe",
9  "address": {
10    "address1": "1 Example Ave.",
11    "address2": "Example Address Line 2",
12    "address3": "Example Address Line 3",
13    "city": "Chicago",
14    "country": "US",
15    "postalCode": "60056",
16    "state": "Illinois"
17  },
18  "contactMethods": [
19    {
20      "type": "email",
21      "value": "[email protected]"
22    },
23    {
24      "type": "phone",
25      "value": "2025550164"
26    }
27  ],
28  "owners": [
29    {
30      "firstName": "Jane",
31      "lastName": "Doe",
32      "dateOfBirth": "1964-03-22",
33      "address": {
34        "address1": "1 Example Ave.",
35        "city": "Chicago",
36        "state": "Illinois",
37        "country": "US",
38        "postalCode": "60056"
39      },
40      "identifiers": [
41        {
42          "type": "nationalId",
43          "value": "000-00-4320"
44        }
45      ],
46      "contactMethods": [
47        {
48          "type": "email",
49          "value": "[email protected]"
50        },
51        {
52          "type": "phone",
53          "value": "2025550164"
54        }
55      ],
56      "relationship": {
57        "isControlProng": true,
58        "equityPercentage": 48.5,
59        "title": "CFO",
60        "isAuthorizedSignatory": false
61      },
62      "middleName": "Helen"
63    }
64  ],
65  "fundingAccounts": [
66    {
67      "type": "checking",
68      "use": "credit",
69      "nameOnAccount": "Jane Doe",
70      "paymentMethods": [
71        {
72          "type": "ach",
73          "value": {
74            "routingNumber": "123456789",
75            "accountNumber": "1234567890"
76          }
77        }
78      ]
79    }
80  ],
81  "metadata": {
82    "yourCustomField": "abc123"
83  }
84}'
Try it

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

Response

recipientTypeenumRequired
Type or legal structure of the funding recipient.
taxIdstringRequired
Employer identification number (EIN) or Social Security number (SSN).
doingBusinessAsstringRequired
Legal name of the business or organization.
addressobjectRequired
Polymorphic object that contains address information for a funding recipient.
contactMethodslist of objectsRequired
Array of polymorphic objects, which contain contact information. The value of the type parameter determines which variant you should use: - `email` - Email address - `phone` - Phone number - `mobile` - Mobile number - `fax` - Fax number
ownerslist of objectsRequiredRead-only
Array of owner objects associated with the funding recipient.
fundingAccountslist of objectsRequiredRead-only
Array of fundingAccount objects associated with the funding recipient.
recipientIdintegerOptionalRead-only
Unique identifier that we assigned to the funding recipient.
statusenumOptionalRead-only
Indicates if we have approved the funding recipient.
createdDatedatetimeOptionalRead-only
Date the funding recipient was created.
lastModifiedDatedatetimeOptionalRead-only
Date the funding recipient was last modified.
charityIdstringOptional
Government identifier of the charity.
metadatamap from strings to stringsOptional
[Metadata](https://docs.payroc.com/api/metadata) object you can use to include custom data with your request.

Example response

Response
1{
2  "recipientType": "privateCorporation",
3  "taxId": "123456789",
4  "doingBusinessAs": "string",
5  "address": {
6    "address1": "1 Example Ave.",
7    "address2": "Example Address Line 2",
8    "address3": "Example Address Line 3",
9    "city": "Chicago",
10    "country": "US",
11    "postalCode": "60056",
12    "state": "Illinois"
13  },
14  "contactMethods": [
15    {
16      "type": "email",
17      "value": "[email protected]"
18    }
19  ],
20  "owners": [
21    {
22      "ownerId": 4564,
23      "link": {
24        "rel": "owner",
25        "href": "https://api.payroc.com/v1/owners/4564",
26        "method": "get"
27      }
28    }
29  ],
30  "fundingAccounts": [
31    {
32      "fundingAccountId": 123,
33      "status": "approved",
34      "link": {
35        "rel": "fundingAccount",
36        "href": "https://api.payroc.com/v1/funding-accounts/123",
37        "method": "get"
38      }
39    },
40    {
41      "fundingAccountId": 124,
42      "status": "rejected",
43      "link": {
44        "rel": "fundingAccount",
45        "href": "https://api.payroc.com/v1/funding-accounts/124",
46        "method": "get"
47      }
48    }
49  ],
50  "recipientId": 234,
51  "status": "approved",
52  "createdDate": "2024-07-02T15:30:00Z",
53  "lastModifiedDate": "2024-07-02T15:30:00Z",
54  "charityId": "string",
55  "metadata": {
56    "yourCustomField": "abc123"
57  }
58}

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.