Skip to content
payrocdevelopers

Create funding recipient

Browse API reference

POST/funding-recipientscreateFundingRecipient

Use this method to create a funding recipient.

A funding recipient is a business or organization that can receive funds but can't run transactions, for example, a charity.

In the request, include the following information:

  • Legal information, including its tax ID, Doing Business As (DBA) name, and address.
  • Contact information, including the email address.
  • Owners' details, including their contact details.
  • Funding account details.

Our gateway returns the recipientId of the funding recipient, which you can use to run follow-on actions.

Parameters

NameInTypeDescription
Idempotency-KeyRequiredheaderstring

Unique identifier that you generate for each request. You must use the UUID v4 format for the identifier. For more information about the idempotency key, go to Idempotency.

Request body

application/json
Field Edit request inputs →
  • addressobjectrequired
    Polymorphic object that contains address information for a funding recipient.
    • addressobject
      Object that contains information about the address.
      • address1stringrequired
        Address line 1.≤ 150 chars
      • address2string
        Address line 2.≤ 150 chars
      • address3string
        Address line 3.≤ 150 chars
      • citystringrequired
        City.≤ 50 chars
      • countrystringrequired
        Two-digit country code for the country that the business operates in. The format follows the ISO-3166-1 standard.2–2 chars
      • postalCodestringrequired
        Zip code or postal code.≤ 10 chars
      • statestringrequired
        Name of the state or state abbreviation.≤ 50 chars
  • charityIdstring
    Government identifier of the charity.
  • contactMethodsobject[]required
    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≥ 1 items
    • emailobject
      • typestringrequired
        Type of contact method.email
      • valuestringrequired
        Email address.≤ 50 chars
    • phoneobject
      • typestringrequired
        Type of contact method.phone
      • valuestringrequired
        Phone number.≤ 15 chars
    • mobileobject
      • typestringrequired
        Type of contact method.mobile
      • valuestringrequired
        Mobile number.≤ 15 chars
    • faxobject
      • typestringrequired
        Type of contact method.fax
      • valuestringrequired
        Fax number.≤ 15 chars
  • doingBusinessAsstringrequired
    Trading name of the business or organization.
  • fundingAccountsobject[]required
    Array of fundingAccount objects that you can use to add funding accounts to the funding recipient.≥ 1 items
    • metadataobject
      Metadata object you can use to include custom data with your request.
    • nameOnAccountstringrequired
      Name of the account holder.
    • paymentMethodsobject[]required
      Array of PaymentMethodAch objects.
      • ACH payment methodobject
        +4 more fields at deeper levels — see the full spec
    • typestringrequired
      Type of funding account.checkingsavingsgeneralLedger
    • usestringrequired
      Indicates if we send funds or withdraw funds from the account. credit Send funds to the account. debit Withdraw funds from the account. creditAndDebit Send funds and withdraw funds from the account. Note: If the funding account is associated with a funding recipient, we accept only a value of credit.creditdebitcreditAndDebit
  • metadataobject
    Metadata object you can use to include custom data with your request.
  • ownersobject[]required
    Array of owner objects. Each object contains information about an individual who owns or manages the funding recipient.≥ 1 items
    • addressobjectrequired
      Object that contains information about the address.
      • address1stringrequired
        Address line 1.≤ 150 chars
      • address2string
        Address line 2.≤ 150 chars
      • address3string
        Address line 3.≤ 150 chars
      • citystringrequired
        City.≤ 50 chars
      • countrystringrequired
        Two-digit country code for the country that the business operates in. The format follows the ISO-3166-1 standard.2–2 chars
      • postalCodestringrequired
        Zip code or postal code.≤ 10 chars
      • statestringrequired
        Name of the state or state abbreviation.≤ 50 chars
    • contactMethodsobject[]required
      Array of polymorphic objects, which contain contact information. Note: If you are adding information about an owner, you must provide at least an email address. If you are adding information about a contact, you must provide at least a contact number. The value of the type parameter determines which variant you should use: email Email address phone Phone number mobile Mobile number fax Fax number1–4 items
      • emailobject
        +2 more fields at deeper levels — see the full spec
      • phoneobject
        +2 more fields at deeper levels — see the full spec
      • mobileobject
        +2 more fields at deeper levels — see the full spec
      • faxobject
        +2 more fields at deeper levels — see the full spec
    • dateOfBirthstringdaterequired
      Owner's date of birth. The format of this value is YYYY-MM-DD.
    • firstNamestringrequired
      Owner's first name.≤ 50 chars
    • identifiersobject[]required
      Array of IDs.≥ 1 items
      • typestringrequired
        Type of ID provided to verify identity.nationalId
      • valuestringrequired
        Social Security Number (SSN) or Social Insurance Number (SIN).
    • lastNamestringrequired
      Owner's last name.≤ 50 chars
    • middleNamestring
      Owner's middle name.≤ 50 chars
    • relationshipobjectrequired
      Object that contains information about the owner's relationship to the business.
      • equityPercentagenumberpercentage
        Percentage equity stake that the owner holds in the business.
      • isAuthorizedSignatoryboolean
        Indicates if the owner is an authorized signatory.
      • isControlProngbooleanrequired
        Indicates if the owner is a control prong. You can identify only one control prong for a business.
      • titlestring
        Owner's job title.
  • recipientTypestringrequired
    Type or legal structure of the funding recipient.privateCorporationpublicCorporationnonProfitgovernmentprivateLlcpublicLlcprivatePartnershippublicPartnership+1 more
  • taxIdstringrequired
    Employer identification number (EIN) or Social Security number (SSN).

Responses

Successful request. We created the funding recipient.

201 Created · application/json
{
  "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"
    }
  ],
  "createdDate": "2024-07-02T15:30:00+00:00",
  "doingBusinessAs": "Pizza Doe",
  "fundingAccounts": [
    {
      "fundingAccountId": 123,
      "link": {
        "href": "https://api.payroc.com/v1/funding-accounts/123",
        "method": "get",
        "rel": "fundingAccount"
      },
      "status": "pending"
    }
  ],
  "lastModifiedDate": "2024-07-02T15:30:00+00:00",
  "metadata": {
    "yourCustomField": "abc123"
  },
  "owners": [
    {
      "link": {
        "href": "https://api.payroc.com/v1/owners/4564",
        "method": "get",
        "rel": "owner"
      },
      "ownerId": 4564
    }
  ],
  "recipientId": 234,
  "recipientType": "privateCorporation",
  "status": "pending",
  "taxId": "12-3456789"
}
Response schema · 44 fields
  • addressobjectrequired
    Polymorphic object that contains address information for a funding recipient.
    • addressobject
      Object that contains information about the address.
      • address1stringrequired
        Address line 1.≤ 150 chars
      • address2string
        Address line 2.≤ 150 chars
      • address3string
        Address line 3.≤ 150 chars
      • citystringrequired
        City.≤ 50 chars
      • countrystringrequired
        Two-digit country code for the country that the business operates in. The format follows the ISO-3166-1 standard.2–2 chars
      • postalCodestringrequired
        Zip code or postal code.≤ 10 chars
      • statestringrequired
        Name of the state or state abbreviation.≤ 50 chars
  • charityIdstring
    Government identifier of the charity.
  • contactMethodsobject[]required
    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≥ 1 items
    • emailobject
      • typestringrequired
        Type of contact method.email
      • valuestringrequired
        Email address.≤ 50 chars
    • phoneobject
      • typestringrequired
        Type of contact method.phone
      • valuestringrequired
        Phone number.≤ 15 chars
    • mobileobject
      • typestringrequired
        Type of contact method.mobile
      • valuestringrequired
        Mobile number.≤ 15 chars
    • faxobject
      • typestringrequired
        Type of contact method.fax
      • valuestringrequired
        Fax number.≤ 15 chars
  • createdDatestringdate-time
    Date the funding recipient was created.
  • doingBusinessAsstringrequired
    Legal name of the business or organization.
  • fundingAccountsobject[]required
    Array of fundingAccount objects associated with the funding recipient.
    • fundingAccountIdinteger
      Unique identifier of the funding account.
    • linkobject
      Object that contains HATEOAS links for the resource.
      • hrefstring
        URL of the target resource.
      • methodstring
        HTTP method that you need to use with the target resource.
      • relstring
        Indicates the relationship between the current resource and the target resource.
    • statusstring
      Status of the funding account.approvedrejectedpendinghold
  • lastModifiedDatestringdate-time
    Date the funding recipient was last modified.
  • metadataobject
    Metadata object you can use to include custom data with your request.
  • ownersobject[]required
    Array of owner objects associated with the funding recipient.
    • linkobject
      Object that contains HATEOAS links for the resource.
      • hrefstring
        URL of the target resource.
      • methodstring
        HTTP method that you need to use with the target resource.
      • relstring
        Indicates the relationship between the current resource and the target resource.
    • ownerIdinteger
      Unique identifier of the owner.
  • recipientIdinteger
    Unique identifier that we assigned to the funding recipient.
  • recipientTypestringrequired
    Type or legal structure of the funding recipient.privateCorporationpublicCorporationnonProfitgovernmentprivateLlcpublicLlcprivatePartnershippublicPartnership+1 more
  • statusstring
    Indicates if we have approved the funding recipient.approvedrejectedpending
  • taxIdstringrequired
    Employer identification number (EIN) or Social Security number (SSN).

Used in workflows

set-up-a-funding-recipient

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