> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.payroc.com/llms.txt.
> For full documentation content, see https://docs.payroc.com/llms-full.txt.
# Set up a funding recipient
**Important:** Before you begin, make sure that you have read our [Getting Started](/get-started/getting-started "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
### Bearer tokens
Use our Identity Service to generate a Bearer token to include in the header of your requests. To generate your Bearer token, complete the following steps:
1. Include your API key in the x-api-key parameter in the header of a POST request.
2. Send your request to [https://identity.payroc.com/authorize](https://identity.payroc.com/authorize).
**Note:** You need to generate a new Bearer token before the previous Bearer token expires.
#### Example request
```bash
curl --location --request POST 'https://identity.payroc.com/authorize' --header 'x-api-key: '
```
#### Example response
If your request is successful, we return a response that contains your Bearer token, information about its scope, and when it expires.
```json
{
"access_token": "eyJhbGc....adQssw5c",
"expires_in": 3600,
"scope": "service_a service_b",
"token_type": "Bearer"
}
```
### Headers
To create the header of each POST request, you must include the following parameters:
* **Content-Type:** Include application/json as the value for this parameter.
* **Authorization:** Include your Bearer token in this parameter.
* **Idempotency-Key:** Include a UUID v4 to make the request idempotent.
```bash
curl
-H "Content-Type: application/json"
-H "Authorization: "
-H "Idempotency-Key: "
```
### Errors
If your request is unsuccessful, we return an error. For more information about errors, see [Errors](/api/errors).
## Create your funding recipient
To create your funding recipient, send a POST request to our Funding Recipients endpoint.
| Endpoint | Prefix | URL |
| :--------- | :--------- | :--------------------------------------------------------------------------------------------------- |
| Test | `api.uat.` | [https://api.uat.payroc.com/v1/funding-recipients](https://api.uat.payroc.com/v1/funding-recipients) |
| Production | `api.` | [https://api.payroc.com/v1/funding-recipients](https://api.payroc.com/v1/funding-recipients) |
To create the body of your request, use the following parameters:
### Schema (`request.body`)
```yaml
openapi: 3.1.0
info:
title: API
version: 1.0.0
paths:
/funding-recipients:
post:
operationId: create
summary: Create funding recipient
description: "Use this method to create a funding recipient. \n\nA funding recipient is a business or organization that can receive funds but can't run transactions, for example, a charity. \n\nIn the request, include the following information: \n-\tLegal information, including its tax ID, Doing Business As (DBA) name, and address. \n-\tContact information, including the email address. \n-\tOwners' details, including their contact details. \n-\tFunding account details. \n\nOur gateway returns the recipientId of the funding recipient, which you can use to run follow-on actions. \n"
tags:
- subpackage_funding.subpackage_funding/fundingRecipients
parameters:
- name: Idempotency-Key
in: header
description: >-
Unique identifier that you generate for each request. You must use
the [UUID v4 format](https://www.rfc-editor.org/rfc/rfc4122) for the
identifier. For more information about the idempotency key, go to
[Idempotency](https://docs.payroc.com/api/idempotency).
required: true
schema:
type: string
format: uuid
responses:
'201':
description: Successful request. We created the funding recipient.
content:
application/json:
schema:
$ref: '#/components/schemas/fundingRecipient'
'400':
description: Validation errors
content:
application/json:
schema:
$ref: '#/components/schemas/400'
'401':
description: Identity could not be verified
content:
application/json:
schema:
$ref: '#/components/schemas/401'
'403':
description: Do not have permissions to perform this action
content:
application/json:
schema:
$ref: '#/components/schemas/403'
'406':
description: Not acceptable
content:
application/json:
schema:
$ref: '#/components/schemas/406'
'409':
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/409'
'500':
description: An error has occured
content:
application/json:
schema:
$ref: '#/components/schemas/500'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/createFundingRecipient'
servers:
- url: https://api.payroc.com/v1
- url: https://api.uat.payroc.com/v1
components:
schemas:
'400':
type: object
properties:
type:
type: string
description: URI reference identifying the problem type
title:
type: string
description: Short description of the issue.
status:
type: integer
description: Http status code
detail:
type: string
description: Explanation of the problem
errors:
type: array
items:
$ref: '#/components/schemas/ErrorsItems'
required:
- type
- title
- status
- detail
title: '400'
'401':
type: object
properties:
type:
type: string
description: URI reference identifying the problem type
title:
type: string
description: Short description of the issue.
status:
type: integer
description: Http status code
detail:
type: string
description: Explanation of the problem
required:
- type
- title
- status
- detail
title: '401'
'403':
type: object
properties:
type:
type: string
description: URI reference identifying the problem type
title:
type: string
description: Short description of the issue.
status:
type: integer
description: Http status code
detail:
type: string
description: Explanation of the problem
instance:
type: string
description: Resource path the action was attempted on
resource:
type: string
description: Resource the action was attempted on
required:
- type
- title
- status
- detail
title: '403'
'406':
type: object
properties:
type:
type: string
description: URI reference identifying the problem type
title:
type: string
description: Short description of the issue.
status:
type: integer
description: Http status code
detail:
type: string
description: Explanation of the problem
required:
- type
- title
- status
- detail
title: '406'
'409':
type: object
properties:
type:
type: string
description: URI reference identifying the problem type
title:
type: string
description: Short description of the issue.
status:
type: integer
description: Http status code
detail:
type: string
description: Explanation of the problem
instance:
type: string
description: Resource path to the existing resource
errors:
type: array
items:
$ref: '#/components/schemas/ErrorsItems'
link:
$ref: '#/components/schemas/link'
required:
- type
- title
- status
- detail
title: '409'
'500':
type: object
properties:
type:
type: string
description: URI reference identifying the problem type
title:
type: string
description: Short description of the issue.
status:
type: integer
description: Http status code
detail:
type: string
description: Explanation of the problem
errors:
type: array
items:
$ref: '#/components/schemas/ErrorsItems'
required:
- type
- title
- status
- detail
title: '500'
CreateFundingRecipientStatus:
type: string
enum:
- approved
- rejected
- pending
title: CreateFundingRecipientStatus
CreateFundingRecipientRecipientType:
type: string
enum:
- privateCorporation
- publicCorporation
- nonProfit
- government
- privateLlc
- publicLlc
- privatePartnership
- publicPartnership
- soleProprietor
description: Type or legal structure of the funding recipient.
title: CreateFundingRecipientRecipientType
address:
type: object
properties:
address1:
type: string
description: Address line 1.
address2:
type: string
description: Address line 2.
address3:
type: string
description: Address line 3.
city:
type: string
description: City.
state:
type: string
description: Name of the state or state abbreviation.
country:
type: string
description: >-
Two-digit country code for the country that the business operates
in. The format follows the
[ISO-3166-1](https://www.iso.org/iso-3166-country-codes.html)
standard.
postalCode:
type: string
description: Zip code or postal code.
required:
- address1
- city
- state
- country
- postalCode
description: Object that contains information about the address.
title: address
CreateFundingRecipientAddress:
oneOf:
- $ref: '#/components/schemas/address'
description: >-
Polymorphic object that contains address information for a funding
recipient.
title: CreateFundingRecipientAddress
contactMethod:
oneOf:
- type: object
properties:
type:
type: string
enum:
- email
description: 'Discriminator value: email'
value:
type: string
description: Email address.
required:
- type
- value
description: email variant
- type: object
properties:
type:
type: string
enum:
- phone
description: 'Discriminator value: phone'
value:
type: string
description: Phone number.
required:
- type
- value
description: phone variant
- type: object
properties:
type:
type: string
enum:
- mobile
description: 'Discriminator value: mobile'
value:
type: string
description: Mobile number.
required:
- type
- value
description: mobile variant
- type: object
properties:
type:
type: string
enum:
- fax
description: 'Discriminator value: fax'
value:
type: string
description: Fax number.
required:
- type
- value
description: fax variant
discriminator:
propertyName: type
title: contactMethod
IdentifierType:
type: string
enum:
- nationalId
description: Type of ID provided to verify identity.
title: IdentifierType
identifier:
type: object
properties:
type:
$ref: '#/components/schemas/IdentifierType'
description: Type of ID provided to verify identity.
value:
type: string
description: Social Security Number (SSN) or Social Insurance Number (SIN).
required:
- type
- value
title: identifier
ownerRelationship:
type: object
properties:
equityPercentage:
type: number
format: double
default: 0
description: Percentage equity stake that the owner holds in the business.
title:
type: string
description: Owner's job title.
isControlProng:
type: boolean
description: >-
Indicates if the owner is a control prong. You can identify only one
control prong for a business.
isAuthorizedSignatory:
type: boolean
description: Indicates if the owner is an authorized signatory.
required:
- isControlProng
description: >-
Object that contains information about the owner's relationship to the
business.
title: ownerRelationship
owner:
type: object
properties:
ownerId:
type: integer
description: Unique identifier that we assigned to the owner.
firstName:
type: string
description: Owner's first name.
middleName:
type: string
description: Owner's middle name.
lastName:
type: string
description: Owner's last name.
dateOfBirth:
type: string
format: date
description: Owner's date of birth. The format of this value is **YYYY-MM-DD**.
address:
$ref: '#/components/schemas/address'
identifiers:
type: array
items:
$ref: '#/components/schemas/identifier'
description: Array of IDs.
contactMethods:
type: array
items:
$ref: '#/components/schemas/contactMethod'
description: "Array of polymorphic objects, which contain contact information. \n\n**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. \n\nThe value of the type parameter determines which variant you should use: \n-\t`email` - Email address \n-\t`phone` - Phone number\n-\t`mobile` - Mobile number\n-\t`fax` - Fax number\n"
relationship:
$ref: '#/components/schemas/ownerRelationship'
description: >-
Object that contains information about the owner's relationship to
the business.
required:
- firstName
- lastName
- dateOfBirth
- address
- identifiers
- contactMethods
- relationship
title: owner
FundingAccountStatus:
type: string
enum:
- approved
- rejected
- pending
- hold
description: >
Status of the funding account. The value is one of the following:
- `approved` - We approved the funding account.
- `rejected` - We rejected the funding account.
- `pending` - We have not yet approved the funding account.
- `hold` - Our Risk team have temporarily placed a hold on the funding
account.
title: FundingAccountStatus
FundingAccountType:
type: string
enum:
- checking
- savings
- generalLedger
description: Type of funding account.
title: FundingAccountType
FundingAccountUse:
type: string
enum:
- credit
- debit
- creditAndDebit
description: >
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`.
title: FundingAccountUse
PaymentMethodsItemsDiscriminatorMappingAchValue:
type: object
properties:
routingNumber:
type: string
description: Routing number of the funding account.
accountNumber:
type: string
description: Account number of the funding account.
required:
- routingNumber
- accountNumber
description: Object that contains information about the funding account.
title: PaymentMethodsItemsDiscriminatorMappingAchValue
PaymentMethodsItems:
oneOf:
- type: object
properties:
type:
type: string
enum:
- ach
description: 'Discriminator value: ach'
value:
$ref: >-
#/components/schemas/PaymentMethodsItemsDiscriminatorMappingAchValue
description: Object that contains information about the funding account.
required:
- type
description: ACH payment method variant
discriminator:
propertyName: type
title: PaymentMethodsItems
paymentMethods:
type: array
items:
$ref: '#/components/schemas/PaymentMethodsItems'
description: Array of PaymentMethodAch objects.
title: paymentMethods
link:
type: object
properties:
rel:
type: string
description: >-
Indicates the relationship between the current resource and the
target resource.
method:
type: string
description: HTTP method that you need to use with the target resource.
href:
type: string
description: URL of the target resource.
required:
- rel
- method
- href
description: Object that contains HATEOAS links for the resource.
title: link
fundingAccount:
type: object
properties:
fundingAccountId:
type: integer
description: Unique identifier that we assigned to the funding account.
createdDate:
type: string
format: date-time
description: >-
Date and time that we received your request to create the funding
account in our system.
lastModifiedDate:
type: string
format: date-time
description: Date and time that the funding account was last modified.
status:
$ref: '#/components/schemas/FundingAccountStatus'
description: >
Status of the funding account. The value is one of the following:
- `approved` - We approved the funding account.
- `rejected` - We rejected the funding account.
- `pending` - We have not yet approved the funding account.
- `hold` - Our Risk team have temporarily placed a hold on the
funding account.
type:
$ref: '#/components/schemas/FundingAccountType'
description: Type of funding account.
use:
$ref: '#/components/schemas/FundingAccountUse'
description: >
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`.
nameOnAccount:
type: string
description: Name of the account holder.
paymentMethods:
$ref: '#/components/schemas/paymentMethods'
description: Array of paymentMethod objects.
metadata:
type: object
additionalProperties:
type: string
description: >-
[Metadata](https://docs.payroc.com/api/metadata) object you can use
to include custom data with your request.
links:
type: array
items:
$ref: '#/components/schemas/link'
description: Array of HATEOAS links.
required:
- type
- use
- nameOnAccount
- paymentMethods
title: fundingAccount
createFundingRecipient:
type: object
properties:
recipientId:
type: integer
status:
$ref: '#/components/schemas/CreateFundingRecipientStatus'
createdDate:
type: string
format: date-time
lastModifiedDate:
type: string
format: date-time
recipientType:
$ref: '#/components/schemas/CreateFundingRecipientRecipientType'
description: Type or legal structure of the funding recipient.
taxId:
type: string
description: >-
Employer identification number (EIN) or Social Security number
(SSN).
charityId:
type: string
description: Government identifier of the charity.
doingBusinessAs:
type: string
description: Trading name of the business or organization.
address:
$ref: '#/components/schemas/CreateFundingRecipientAddress'
description: >-
Polymorphic object that contains address information for a funding
recipient.
contactMethods:
type: array
items:
$ref: '#/components/schemas/contactMethod'
description: "Array of polymorphic objects, which contain contact information. \n\n**Note:** You must provide an email address.\n\nThe value of the type parameter determines which variant you should use: \n-\t`email` - Email address \n-\t`phone` - Phone number\n-\t`mobile` - Mobile number\n-\t`fax` - Fax number\n"
metadata:
type: object
additionalProperties:
type: string
description: >-
[Metadata](https://docs.payroc.com/api/metadata) object you can use
to include custom data with your request.
owners:
type: array
items:
$ref: '#/components/schemas/owner'
description: >-
Array of owner objects. Each object contains information about an
individual who owns or manages the funding recipient.
fundingAccounts:
type: array
items:
$ref: '#/components/schemas/fundingAccount'
description: >-
Array of fundingAccount objects that you can use to add funding
accounts to the funding recipient.
required:
- recipientType
- taxId
- doingBusinessAs
- address
- contactMethods
- owners
- fundingAccounts
title: createFundingRecipient
FundingRecipientStatus:
type: string
enum:
- approved
- rejected
- pending
description: Indicates if we have approved the funding recipient.
title: FundingRecipientStatus
FundingRecipientRecipientType:
type: string
enum:
- privateCorporation
- publicCorporation
- nonProfit
- government
- privateLlc
- publicLlc
- privatePartnership
- publicPartnership
- soleProprietor
description: Type or legal structure of the funding recipient.
title: FundingRecipientRecipientType
FundingRecipientAddress:
oneOf:
- $ref: '#/components/schemas/address'
description: >-
Polymorphic object that contains address information for a funding
recipient.
title: FundingRecipientAddress
FundingRecipientOwnersItemsLink:
type: object
properties:
rel:
type: string
description: >-
Indicates the relationship between the current resource and the
target resource.
href:
type: string
description: URL of the target resource.
method:
type: string
description: HTTP method that you need to use with the target resource.
description: Object that contains HATEOAS links for the resource.
title: FundingRecipientOwnersItemsLink
FundingRecipientOwnersItems:
type: object
properties:
ownerId:
type: integer
description: Unique identifier of the owner.
link:
$ref: '#/components/schemas/FundingRecipientOwnersItemsLink'
description: Object that contains HATEOAS links for the resource.
title: FundingRecipientOwnersItems
FundingRecipientFundingAccountsItemsStatus:
type: string
enum:
- approved
- rejected
- pending
- hold
description: Status of the funding account.
title: FundingRecipientFundingAccountsItemsStatus
FundingRecipientFundingAccountsItemsLink:
type: object
properties:
rel:
type: string
description: >-
Indicates the relationship between the current resource and the
target resource.
href:
type: string
description: URL of the target resource.
method:
type: string
description: HTTP method that you need to use with the target resource.
description: Object that contains HATEOAS links for the resource.
title: FundingRecipientFundingAccountsItemsLink
FundingRecipientFundingAccountsItems:
type: object
properties:
fundingAccountId:
type: integer
description: Unique identifier of the funding account.
status:
$ref: '#/components/schemas/FundingRecipientFundingAccountsItemsStatus'
description: Status of the funding account.
link:
$ref: '#/components/schemas/FundingRecipientFundingAccountsItemsLink'
description: Object that contains HATEOAS links for the resource.
title: FundingRecipientFundingAccountsItems
fundingRecipient:
type: object
properties:
recipientId:
type: integer
description: Unique identifier that we assigned to the funding recipient.
status:
$ref: '#/components/schemas/FundingRecipientStatus'
description: Indicates if we have approved the funding recipient.
createdDate:
type: string
format: date-time
description: Date the funding recipient was created.
lastModifiedDate:
type: string
format: date-time
description: Date the funding recipient was last modified.
recipientType:
$ref: '#/components/schemas/FundingRecipientRecipientType'
description: Type or legal structure of the funding recipient.
taxId:
type: string
description: >-
Employer identification number (EIN) or Social Security number
(SSN).
charityId:
type: string
description: Government identifier of the charity.
doingBusinessAs:
type: string
description: Legal name of the business or organization.
address:
$ref: '#/components/schemas/FundingRecipientAddress'
description: >-
Polymorphic object that contains address information for a funding
recipient.
contactMethods:
type: array
items:
$ref: '#/components/schemas/contactMethod'
description: "Array of polymorphic objects, which contain contact information. \n\nThe value of the type parameter determines which variant you should use: \n-\t`email` - Email address \n-\t`phone` - Phone number\n-\t`mobile` - Mobile number\n-\t`fax` - Fax number\n"
metadata:
type: object
additionalProperties:
type: string
description: >-
[Metadata](https://docs.payroc.com/api/metadata) object you can use
to include custom data with your request.
owners:
type: array
items:
$ref: '#/components/schemas/FundingRecipientOwnersItems'
description: Array of owner objects associated with the funding recipient.
fundingAccounts:
type: array
items:
$ref: '#/components/schemas/FundingRecipientFundingAccountsItems'
description: >-
Array of fundingAccount objects associated with the funding
recipient.
required:
- recipientType
- taxId
- doingBusinessAs
- address
- contactMethods
- owners
- fundingAccounts
title: fundingRecipient
ErrorsItems:
type: object
properties:
message:
type: string
description: Error message
title: ErrorsItems
```
**Note:** Use our [metadata](/api/metadata "Metadata") feature to add custom information to your request.
### Example request
### Request
POST [https://api.payroc.com/v1/funding-recipients](https://api.payroc.com/v1/funding-recipients)
```curl
curl -X POST https://api.payroc.com/v1/funding-recipients \
-H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
-H "Authorization: Bearer " \
-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",
"state": "Illinois",
"country": "US",
"postalCode": "60056"
},
"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"
}
}'
```
```typescript
import { PayrocClient } from "payroc";
async function main() {
const client = new PayrocClient();
await client.funding.fundingRecipients.create({
idempotencyKey: "8e03978e-40d5-43e8-bc93-6894a57f9324",
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",
state: "Illinois",
country: "US",
postalCode: "60056",
},
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",
},
});
}
main();
```
```python
from payroc import Payroc, Address, ContactMethod_Email, ContactMethod_Phone, Owner, Identifier, OwnerRelationship, FundingAccount, PaymentMethodsItem_Ach, PaymentMethodAchValue
import datetime
client = Payroc()
client.funding.funding_recipients.create(
idempotency_key="8e03978e-40d5-43e8-bc93-6894a57f9324",
recipient_type="privateCorporation",
tax_id="12-3456789",
doing_business_as="Pizza Doe",
address=Address(
address_1="1 Example Ave.",
address_2="Example Address Line 2",
address_3="Example Address Line 3",
city="Chicago",
state="Illinois",
country="US",
postal_code="60056",
),
contact_methods=[
ContactMethod_Email(
value="jane.doe@example.com",
),
ContactMethod_Phone(
value="2025550164",
)
],
owners=[
Owner(
first_name="Jane",
last_name="Doe",
date_of_birth=datetime.date.fromisoformat("1964-03-22"),
address=Address(
address_1="1 Example Ave.",
city="Chicago",
state="Illinois",
country="US",
postal_code="60056",
),
identifiers=[
Identifier(
type="nationalId",
value="000-00-4320",
)
],
contact_methods=[
ContactMethod_Email(
value="jane.doe@example.com",
),
ContactMethod_Phone(
value="2025550164",
)
],
relationship=OwnerRelationship(
is_control_prong=True,
equity_percentage=48.5,
title="CFO",
is_authorized_signatory=False,
),
middle_name="Helen",
)
],
funding_accounts=[
FundingAccount(
type="checking",
use="credit",
name_on_account="Jane Doe",
payment_methods=[
PaymentMethodsItem_Ach(
value=PaymentMethodAchValue(
routing_number="123456789",
account_number="1234567890",
),
)
],
)
],
metadata={
"yourCustomField": "abc123"
},
)
```
```java
package com.example.usage;
import com.payroc.api.PayrocApiClient;
import com.payroc.api.resources.funding.fundingrecipients.requests.CreateFundingRecipient;
import com.payroc.api.resources.funding.fundingrecipients.types.CreateFundingRecipientRecipientType;
import com.payroc.api.types.Address;
import com.payroc.api.types.ContactMethod;
import com.payroc.api.types.ContactMethodEmail;
import com.payroc.api.types.ContactMethodPhone;
import com.payroc.api.types.FundingAccount;
import com.payroc.api.types.FundingAccountType;
import com.payroc.api.types.FundingAccountUse;
import com.payroc.api.types.Identifier;
import com.payroc.api.types.IdentifierType;
import com.payroc.api.types.Owner;
import com.payroc.api.types.OwnerRelationship;
import com.payroc.api.types.PaymentMethodAch;
import com.payroc.api.types.PaymentMethodAchValue;
import com.payroc.api.types.PaymentMethodsItem;
import java.time.LocalDate;
import java.util.Arrays;
import java.util.HashMap;
public class Example {
public static void main(String[] args) {
PayrocApiClient client = PayrocApiClient
.builder()
.build();
client.funding().fundingRecipients().create(
CreateFundingRecipient
.builder()
.idempotencyKey("8e03978e-40d5-43e8-bc93-6894a57f9324")
.recipientType(CreateFundingRecipientRecipientType.PRIVATE_CORPORATION)
.taxId("12-3456789")
.doingBusinessAs("Pizza Doe")
.address(
Address
.builder()
.address1("1 Example Ave.")
.city("Chicago")
.state("Illinois")
.country("US")
.postalCode("60056")
.address2("Example Address Line 2")
.address3("Example Address Line 3")
.build()
)
.contactMethods(
Arrays.asList(
ContactMethod.email(
ContactMethodEmail
.builder()
.value("jane.doe@example.com")
.build()
),
ContactMethod.phone(
ContactMethodPhone
.builder()
.value("2025550164")
.build()
)
)
)
.owners(
Arrays.asList(
Owner
.builder()
.firstName("Jane")
.lastName("Doe")
.dateOfBirth(LocalDate.parse("1964-03-22"))
.address(
Address
.builder()
.address1("1 Example Ave.")
.city("Chicago")
.state("Illinois")
.country("US")
.postalCode("60056")
.build()
)
.relationship(
OwnerRelationship
.builder()
.isControlProng(true)
.equityPercentage(48.5f)
.title("CFO")
.isAuthorizedSignatory(false)
.build()
)
.middleName("Helen")
.identifiers(
Arrays.asList(
Identifier
.builder()
.type(IdentifierType.NATIONAL_ID)
.value("000-00-4320")
.build()
)
)
.contactMethods(
Arrays.asList(
ContactMethod.email(
ContactMethodEmail
.builder()
.value("jane.doe@example.com")
.build()
),
ContactMethod.phone(
ContactMethodPhone
.builder()
.value("2025550164")
.build()
)
)
)
.build()
)
)
.fundingAccounts(
Arrays.asList(
FundingAccount
.builder()
.type(FundingAccountType.CHECKING)
.use(FundingAccountUse.CREDIT)
.nameOnAccount("Jane Doe")
.paymentMethods(
Arrays.asList(
PaymentMethodsItem.ach(
PaymentMethodAch
.builder()
.value(
PaymentMethodAchValue
.builder()
.routingNumber("123456789")
.accountNumber("1234567890")
.build()
)
.build()
)
)
)
.build()
)
)
.metadata(
new HashMap() {{
put("yourCustomField", "abc123");
}}
)
.build()
);
}
}
```
```ruby
require "payroc"
client = Payroc::Client.new
client.funding.funding_recipients.create(
idempotency_key: "8e03978e-40d5-43e8-bc93-6894a57f9324",
recipient_type: "privateCorporation",
tax_id: "12-3456789",
doing_business_as: "Pizza Doe",
address: {
address_1: "1 Example Ave.",
address_2: "Example Address Line 2",
address_3: "Example Address Line 3",
city: "Chicago",
state: "Illinois",
country: "US",
postal_code: "60056"
},
contact_methods: [],
owners: [{
first_name: "Jane",
last_name: "Doe",
date_of_birth: "1964-03-22",
address: {
address_1: "1 Example Ave.",
city: "Chicago",
state: "Illinois",
country: "US",
postal_code: "60056"
},
identifiers: [{
type: "nationalId",
value: "000-00-4320"
}],
contact_methods: [],
relationship: {
is_control_prong: true,
equity_percentage: 48.5,
title: "CFO",
is_authorized_signatory: false
},
middle_name: "Helen"
}],
funding_accounts: [{
type: "checking",
use: "credit",
name_on_account: "Jane Doe",
payment_methods: []
}],
metadata: {
yourCustomField: "abc123"
}
)
```
```csharp
using Payroc;
using System.Threading.Tasks;
using Payroc.Funding.FundingRecipients;
using System.Collections.Generic;
using System;
namespace Usage;
public class Example
{
public async Task Do() {
var client = new PayrocClient();
await client.Funding.FundingRecipients.CreateAsync(
new CreateFundingRecipient {
IdempotencyKey = "8e03978e-40d5-43e8-bc93-6894a57f9324",
RecipientType = CreateFundingRecipientRecipientType.PrivateCorporation,
TaxId = "12-3456789",
DoingBusinessAs = "Pizza Doe",
Address = new Address {
Address1 = "1 Example Ave.",
Address2 = "Example Address Line 2",
Address3 = "Example Address Line 3",
City = "Chicago",
State = "Illinois",
Country = "US",
PostalCode = "60056"
},
ContactMethods = new List(){
new ContactMethod(
new ContactMethodEmail {
Value = "jane.doe@example.com"
}
),
new ContactMethod(
new ContactMethodPhone {
Value = "2025550164"
}
),
}
,
Owners = new List(){
new Owner {
FirstName = "Jane",
LastName = "Doe",
DateOfBirth = DateOnly.Parse("1964-03-22"),
Address = new Address {
Address1 = "1 Example Ave.",
City = "Chicago",
State = "Illinois",
Country = "US",
PostalCode = "60056"
},
Identifiers = new List(){
new Identifier {
Type = IdentifierType.NationalId,
Value = "000-00-4320"
},
}
,
ContactMethods = new List(){
new ContactMethod(
new ContactMethodEmail {
Value = "jane.doe@example.com"
}
),
new ContactMethod(
new ContactMethodPhone {
Value = "2025550164"
}
),
}
,
Relationship = new OwnerRelationship {
IsControlProng = true,
EquityPercentage = 48.5f,
Title = "CFO",
IsAuthorizedSignatory = false
},
MiddleName = "Helen"
},
}
,
FundingAccounts = new List(){
new FundingAccount {
Type = FundingAccountType.Checking,
Use = FundingAccountUse.Credit,
NameOnAccount = "Jane Doe",
PaymentMethods = new List(){
new PaymentMethodsItem(
new PaymentMethodAch {
Value = new PaymentMethodAchValue {
RoutingNumber = "123456789",
AccountNumber = "1234567890"
}
}
),
}
},
}
,
Metadata = new Dictionary(){
["yourCustomField"] = "abc123",
}
}
);
}
}
```
```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 \"state\": \"Illinois\",\n \"country\": \"US\",\n \"postalCode\": \"60056\"\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 ")
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))
}
```
```php
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",
"state": "Illinois",
"country": "US",
"postalCode": "60056"
},
"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 ',
'Content-Type' => 'application/json',
'Idempotency-Key' => '8e03978e-40d5-43e8-bc93-6894a57f9324',
],
]);
echo $response->getBody();
```
```swift
import Foundation
let headers = [
"Idempotency-Key": "8e03978e-40d5-43e8-bc93-6894a57f9324",
"Authorization": "Bearer ",
"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",
"state": "Illinois",
"country": "US",
"postalCode": "60056"
],
"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`)
```yaml
openapi: 3.1.0
info:
title: API
version: 1.0.0
paths:
/funding-recipients:
post:
operationId: create
summary: Create funding recipient
description: "Use this method to create a funding recipient. \n\nA funding recipient is a business or organization that can receive funds but can't run transactions, for example, a charity. \n\nIn the request, include the following information: \n-\tLegal information, including its tax ID, Doing Business As (DBA) name, and address. \n-\tContact information, including the email address. \n-\tOwners' details, including their contact details. \n-\tFunding account details. \n\nOur gateway returns the recipientId of the funding recipient, which you can use to run follow-on actions. \n"
tags:
- subpackage_funding.subpackage_funding/fundingRecipients
parameters:
- name: Idempotency-Key
in: header
description: >-
Unique identifier that you generate for each request. You must use
the [UUID v4 format](https://www.rfc-editor.org/rfc/rfc4122) for the
identifier. For more information about the idempotency key, go to
[Idempotency](https://docs.payroc.com/api/idempotency).
required: true
schema:
type: string
format: uuid
responses:
'201':
description: Successful request. We created the funding recipient.
content:
application/json:
schema:
$ref: '#/components/schemas/fundingRecipient'
'400':
description: Validation errors
content:
application/json:
schema:
$ref: '#/components/schemas/400'
'401':
description: Identity could not be verified
content:
application/json:
schema:
$ref: '#/components/schemas/401'
'403':
description: Do not have permissions to perform this action
content:
application/json:
schema:
$ref: '#/components/schemas/403'
'406':
description: Not acceptable
content:
application/json:
schema:
$ref: '#/components/schemas/406'
'409':
description: Conflict
content:
application/json:
schema:
$ref: '#/components/schemas/409'
'500':
description: An error has occured
content:
application/json:
schema:
$ref: '#/components/schemas/500'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/createFundingRecipient'
servers:
- url: https://api.payroc.com/v1
- url: https://api.uat.payroc.com/v1
components:
schemas:
'400':
type: object
properties:
type:
type: string
description: URI reference identifying the problem type
title:
type: string
description: Short description of the issue.
status:
type: integer
description: Http status code
detail:
type: string
description: Explanation of the problem
errors:
type: array
items:
$ref: '#/components/schemas/ErrorsItems'
required:
- type
- title
- status
- detail
title: '400'
'401':
type: object
properties:
type:
type: string
description: URI reference identifying the problem type
title:
type: string
description: Short description of the issue.
status:
type: integer
description: Http status code
detail:
type: string
description: Explanation of the problem
required:
- type
- title
- status
- detail
title: '401'
'403':
type: object
properties:
type:
type: string
description: URI reference identifying the problem type
title:
type: string
description: Short description of the issue.
status:
type: integer
description: Http status code
detail:
type: string
description: Explanation of the problem
instance:
type: string
description: Resource path the action was attempted on
resource:
type: string
description: Resource the action was attempted on
required:
- type
- title
- status
- detail
title: '403'
'406':
type: object
properties:
type:
type: string
description: URI reference identifying the problem type
title:
type: string
description: Short description of the issue.
status:
type: integer
description: Http status code
detail:
type: string
description: Explanation of the problem
required:
- type
- title
- status
- detail
title: '406'
'409':
type: object
properties:
type:
type: string
description: URI reference identifying the problem type
title:
type: string
description: Short description of the issue.
status:
type: integer
description: Http status code
detail:
type: string
description: Explanation of the problem
instance:
type: string
description: Resource path to the existing resource
errors:
type: array
items:
$ref: '#/components/schemas/ErrorsItems'
link:
$ref: '#/components/schemas/link'
required:
- type
- title
- status
- detail
title: '409'
'500':
type: object
properties:
type:
type: string
description: URI reference identifying the problem type
title:
type: string
description: Short description of the issue.
status:
type: integer
description: Http status code
detail:
type: string
description: Explanation of the problem
errors:
type: array
items:
$ref: '#/components/schemas/ErrorsItems'
required:
- type
- title
- status
- detail
title: '500'
CreateFundingRecipientStatus:
type: string
enum:
- approved
- rejected
- pending
title: CreateFundingRecipientStatus
CreateFundingRecipientRecipientType:
type: string
enum:
- privateCorporation
- publicCorporation
- nonProfit
- government
- privateLlc
- publicLlc
- privatePartnership
- publicPartnership
- soleProprietor
description: Type or legal structure of the funding recipient.
title: CreateFundingRecipientRecipientType
address:
type: object
properties:
address1:
type: string
description: Address line 1.
address2:
type: string
description: Address line 2.
address3:
type: string
description: Address line 3.
city:
type: string
description: City.
state:
type: string
description: Name of the state or state abbreviation.
country:
type: string
description: >-
Two-digit country code for the country that the business operates
in. The format follows the
[ISO-3166-1](https://www.iso.org/iso-3166-country-codes.html)
standard.
postalCode:
type: string
description: Zip code or postal code.
required:
- address1
- city
- state
- country
- postalCode
description: Object that contains information about the address.
title: address
CreateFundingRecipientAddress:
oneOf:
- $ref: '#/components/schemas/address'
description: >-
Polymorphic object that contains address information for a funding
recipient.
title: CreateFundingRecipientAddress
contactMethod:
oneOf:
- type: object
properties:
type:
type: string
enum:
- email
description: 'Discriminator value: email'
value:
type: string
description: Email address.
required:
- type
- value
description: email variant
- type: object
properties:
type:
type: string
enum:
- phone
description: 'Discriminator value: phone'
value:
type: string
description: Phone number.
required:
- type
- value
description: phone variant
- type: object
properties:
type:
type: string
enum:
- mobile
description: 'Discriminator value: mobile'
value:
type: string
description: Mobile number.
required:
- type
- value
description: mobile variant
- type: object
properties:
type:
type: string
enum:
- fax
description: 'Discriminator value: fax'
value:
type: string
description: Fax number.
required:
- type
- value
description: fax variant
discriminator:
propertyName: type
title: contactMethod
IdentifierType:
type: string
enum:
- nationalId
description: Type of ID provided to verify identity.
title: IdentifierType
identifier:
type: object
properties:
type:
$ref: '#/components/schemas/IdentifierType'
description: Type of ID provided to verify identity.
value:
type: string
description: Social Security Number (SSN) or Social Insurance Number (SIN).
required:
- type
- value
title: identifier
ownerRelationship:
type: object
properties:
equityPercentage:
type: number
format: double
default: 0
description: Percentage equity stake that the owner holds in the business.
title:
type: string
description: Owner's job title.
isControlProng:
type: boolean
description: >-
Indicates if the owner is a control prong. You can identify only one
control prong for a business.
isAuthorizedSignatory:
type: boolean
description: Indicates if the owner is an authorized signatory.
required:
- isControlProng
description: >-
Object that contains information about the owner's relationship to the
business.
title: ownerRelationship
owner:
type: object
properties:
ownerId:
type: integer
description: Unique identifier that we assigned to the owner.
firstName:
type: string
description: Owner's first name.
middleName:
type: string
description: Owner's middle name.
lastName:
type: string
description: Owner's last name.
dateOfBirth:
type: string
format: date
description: Owner's date of birth. The format of this value is **YYYY-MM-DD**.
address:
$ref: '#/components/schemas/address'
identifiers:
type: array
items:
$ref: '#/components/schemas/identifier'
description: Array of IDs.
contactMethods:
type: array
items:
$ref: '#/components/schemas/contactMethod'
description: "Array of polymorphic objects, which contain contact information. \n\n**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. \n\nThe value of the type parameter determines which variant you should use: \n-\t`email` - Email address \n-\t`phone` - Phone number\n-\t`mobile` - Mobile number\n-\t`fax` - Fax number\n"
relationship:
$ref: '#/components/schemas/ownerRelationship'
description: >-
Object that contains information about the owner's relationship to
the business.
required:
- firstName
- lastName
- dateOfBirth
- address
- identifiers
- contactMethods
- relationship
title: owner
FundingAccountStatus:
type: string
enum:
- approved
- rejected
- pending
- hold
description: >
Status of the funding account. The value is one of the following:
- `approved` - We approved the funding account.
- `rejected` - We rejected the funding account.
- `pending` - We have not yet approved the funding account.
- `hold` - Our Risk team have temporarily placed a hold on the funding
account.
title: FundingAccountStatus
FundingAccountType:
type: string
enum:
- checking
- savings
- generalLedger
description: Type of funding account.
title: FundingAccountType
FundingAccountUse:
type: string
enum:
- credit
- debit
- creditAndDebit
description: >
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`.
title: FundingAccountUse
PaymentMethodsItemsDiscriminatorMappingAchValue:
type: object
properties:
routingNumber:
type: string
description: Routing number of the funding account.
accountNumber:
type: string
description: Account number of the funding account.
required:
- routingNumber
- accountNumber
description: Object that contains information about the funding account.
title: PaymentMethodsItemsDiscriminatorMappingAchValue
PaymentMethodsItems:
oneOf:
- type: object
properties:
type:
type: string
enum:
- ach
description: 'Discriminator value: ach'
value:
$ref: >-
#/components/schemas/PaymentMethodsItemsDiscriminatorMappingAchValue
description: Object that contains information about the funding account.
required:
- type
description: ACH payment method variant
discriminator:
propertyName: type
title: PaymentMethodsItems
paymentMethods:
type: array
items:
$ref: '#/components/schemas/PaymentMethodsItems'
description: Array of PaymentMethodAch objects.
title: paymentMethods
link:
type: object
properties:
rel:
type: string
description: >-
Indicates the relationship between the current resource and the
target resource.
method:
type: string
description: HTTP method that you need to use with the target resource.
href:
type: string
description: URL of the target resource.
required:
- rel
- method
- href
description: Object that contains HATEOAS links for the resource.
title: link
fundingAccount:
type: object
properties:
fundingAccountId:
type: integer
description: Unique identifier that we assigned to the funding account.
createdDate:
type: string
format: date-time
description: >-
Date and time that we received your request to create the funding
account in our system.
lastModifiedDate:
type: string
format: date-time
description: Date and time that the funding account was last modified.
status:
$ref: '#/components/schemas/FundingAccountStatus'
description: >
Status of the funding account. The value is one of the following:
- `approved` - We approved the funding account.
- `rejected` - We rejected the funding account.
- `pending` - We have not yet approved the funding account.
- `hold` - Our Risk team have temporarily placed a hold on the
funding account.
type:
$ref: '#/components/schemas/FundingAccountType'
description: Type of funding account.
use:
$ref: '#/components/schemas/FundingAccountUse'
description: >
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`.
nameOnAccount:
type: string
description: Name of the account holder.
paymentMethods:
$ref: '#/components/schemas/paymentMethods'
description: Array of paymentMethod objects.
metadata:
type: object
additionalProperties:
type: string
description: >-
[Metadata](https://docs.payroc.com/api/metadata) object you can use
to include custom data with your request.
links:
type: array
items:
$ref: '#/components/schemas/link'
description: Array of HATEOAS links.
required:
- type
- use
- nameOnAccount
- paymentMethods
title: fundingAccount
createFundingRecipient:
type: object
properties:
recipientId:
type: integer
status:
$ref: '#/components/schemas/CreateFundingRecipientStatus'
createdDate:
type: string
format: date-time
lastModifiedDate:
type: string
format: date-time
recipientType:
$ref: '#/components/schemas/CreateFundingRecipientRecipientType'
description: Type or legal structure of the funding recipient.
taxId:
type: string
description: >-
Employer identification number (EIN) or Social Security number
(SSN).
charityId:
type: string
description: Government identifier of the charity.
doingBusinessAs:
type: string
description: Trading name of the business or organization.
address:
$ref: '#/components/schemas/CreateFundingRecipientAddress'
description: >-
Polymorphic object that contains address information for a funding
recipient.
contactMethods:
type: array
items:
$ref: '#/components/schemas/contactMethod'
description: "Array of polymorphic objects, which contain contact information. \n\n**Note:** You must provide an email address.\n\nThe value of the type parameter determines which variant you should use: \n-\t`email` - Email address \n-\t`phone` - Phone number\n-\t`mobile` - Mobile number\n-\t`fax` - Fax number\n"
metadata:
type: object
additionalProperties:
type: string
description: >-
[Metadata](https://docs.payroc.com/api/metadata) object you can use
to include custom data with your request.
owners:
type: array
items:
$ref: '#/components/schemas/owner'
description: >-
Array of owner objects. Each object contains information about an
individual who owns or manages the funding recipient.
fundingAccounts:
type: array
items:
$ref: '#/components/schemas/fundingAccount'
description: >-
Array of fundingAccount objects that you can use to add funding
accounts to the funding recipient.
required:
- recipientType
- taxId
- doingBusinessAs
- address
- contactMethods
- owners
- fundingAccounts
title: createFundingRecipient
FundingRecipientStatus:
type: string
enum:
- approved
- rejected
- pending
description: Indicates if we have approved the funding recipient.
title: FundingRecipientStatus
FundingRecipientRecipientType:
type: string
enum:
- privateCorporation
- publicCorporation
- nonProfit
- government
- privateLlc
- publicLlc
- privatePartnership
- publicPartnership
- soleProprietor
description: Type or legal structure of the funding recipient.
title: FundingRecipientRecipientType
FundingRecipientAddress:
oneOf:
- $ref: '#/components/schemas/address'
description: >-
Polymorphic object that contains address information for a funding
recipient.
title: FundingRecipientAddress
FundingRecipientOwnersItemsLink:
type: object
properties:
rel:
type: string
description: >-
Indicates the relationship between the current resource and the
target resource.
href:
type: string
description: URL of the target resource.
method:
type: string
description: HTTP method that you need to use with the target resource.
description: Object that contains HATEOAS links for the resource.
title: FundingRecipientOwnersItemsLink
FundingRecipientOwnersItems:
type: object
properties:
ownerId:
type: integer
description: Unique identifier of the owner.
link:
$ref: '#/components/schemas/FundingRecipientOwnersItemsLink'
description: Object that contains HATEOAS links for the resource.
title: FundingRecipientOwnersItems
FundingRecipientFundingAccountsItemsStatus:
type: string
enum:
- approved
- rejected
- pending
- hold
description: Status of the funding account.
title: FundingRecipientFundingAccountsItemsStatus
FundingRecipientFundingAccountsItemsLink:
type: object
properties:
rel:
type: string
description: >-
Indicates the relationship between the current resource and the
target resource.
href:
type: string
description: URL of the target resource.
method:
type: string
description: HTTP method that you need to use with the target resource.
description: Object that contains HATEOAS links for the resource.
title: FundingRecipientFundingAccountsItemsLink
FundingRecipientFundingAccountsItems:
type: object
properties:
fundingAccountId:
type: integer
description: Unique identifier of the funding account.
status:
$ref: '#/components/schemas/FundingRecipientFundingAccountsItemsStatus'
description: Status of the funding account.
link:
$ref: '#/components/schemas/FundingRecipientFundingAccountsItemsLink'
description: Object that contains HATEOAS links for the resource.
title: FundingRecipientFundingAccountsItems
fundingRecipient:
type: object
properties:
recipientId:
type: integer
description: Unique identifier that we assigned to the funding recipient.
status:
$ref: '#/components/schemas/FundingRecipientStatus'
description: Indicates if we have approved the funding recipient.
createdDate:
type: string
format: date-time
description: Date the funding recipient was created.
lastModifiedDate:
type: string
format: date-time
description: Date the funding recipient was last modified.
recipientType:
$ref: '#/components/schemas/FundingRecipientRecipientType'
description: Type or legal structure of the funding recipient.
taxId:
type: string
description: >-
Employer identification number (EIN) or Social Security number
(SSN).
charityId:
type: string
description: Government identifier of the charity.
doingBusinessAs:
type: string
description: Legal name of the business or organization.
address:
$ref: '#/components/schemas/FundingRecipientAddress'
description: >-
Polymorphic object that contains address information for a funding
recipient.
contactMethods:
type: array
items:
$ref: '#/components/schemas/contactMethod'
description: "Array of polymorphic objects, which contain contact information. \n\nThe value of the type parameter determines which variant you should use: \n-\t`email` - Email address \n-\t`phone` - Phone number\n-\t`mobile` - Mobile number\n-\t`fax` - Fax number\n"
metadata:
type: object
additionalProperties:
type: string
description: >-
[Metadata](https://docs.payroc.com/api/metadata) object you can use
to include custom data with your request.
owners:
type: array
items:
$ref: '#/components/schemas/FundingRecipientOwnersItems'
description: Array of owner objects associated with the funding recipient.
fundingAccounts:
type: array
items:
$ref: '#/components/schemas/FundingRecipientFundingAccountsItems'
description: >-
Array of fundingAccount objects associated with the funding
recipient.
required:
- recipientType
- taxId
- doingBusinessAs
- address
- contactMethods
- owners
- fundingAccounts
title: fundingRecipient
ErrorsItems:
type: object
properties:
message:
type: string
description: Error message
title: ErrorsItems
```
### Example response
### Response (201)
```json
{
"recipientType": "privateCorporation",
"taxId": "123456789",
"doingBusinessAs": "string",
"address": {
"address1": "1 Example Ave.",
"address2": "Example Address Line 2",
"address3": "Example Address Line 3",
"city": "Chicago",
"state": "Illinois",
"country": "US",
"postalCode": "60056"
},
"contactMethods": [
{
"type": "email",
"value": "jane.doe@example.com"
}
],
"owners": [
{
"ownerId": 4564,
"link": {
"rel": "owner",
"href": "https://api.payroc.com/v1/owners/4564",
"method": "get"
}
}
],
"fundingAccounts": [
{
"fundingAccountId": 123,
"status": "approved",
"link": {
"rel": "fundingAccount",
"href": "https://api.payroc.com/v1/funding-accounts/123",
"method": "get"
}
},
{
"fundingAccountId": 124,
"status": "rejected",
"link": {
"rel": "fundingAccount",
"href": "https://api.payroc.com/v1/funding-accounts/124",
"method": "get"
}
}
],
"recipientId": 234,
"status": "approved",
"createdDate": "2024-07-02T15:30:00Z",
"lastModifiedDate": "2024-07-02T15:30:00Z",
"charityId": "string",
"metadata": {
"yourCustomField": "abc123"
}
}
```
## Test cases
Our integration team provides you with [test cases](/test/test-your-integration) 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](/guides/fund-merchants/send-funds-to-your-merchants). To view other functions about managing your funding recipients, see [funding recipients](/api/schema/funding/funding-recipients/create "Funding Recipients").