Funding | Payroc | Documentation

To check that you have correctly coded your integration to our API specifications, complete our test cases for each API resource. Each API resource has a unique test endpoint and a unique set of test cases.

If your tests are successful:
We send you an email to inform you that you can now send requests to the live endpoint.

If your tests are unsuccessful:
Contact the project owner or email us for help at [email protected].

Test environment

Run the following tests using our test environment with the credentials that we provided you.

Test environment base URI: https://api.uat.payroc.com/v1

Testing Funding Recipients

Use our /funding-recipients endpoint to create and manage third-party recipients that receive funds from your transactions. To verify that your integration works with this endpoint, run the following tests:

Test 1: Create a Funding Recipient

You can create a Funding Recipient independently of any existing MIDs on your account.

Use our /funding-recipients endpoint to create a new Funding Recipient.

POST

/v1/funding-recipients

1 using Payroc;
2 using System.Threading.Tasks;
3 using Payroc.Funding.FundingRecipients;
4 using System.Collections.Generic;
5 using System;
6 
7 namespace Usage;
8 
9 public class Example
10 {
11     public async Task Do() {
12         var client = new BasePayrocClient(
13             clientOptions: new ClientOptions {
14                 Environment = PayrocEnvironment.Production
15             }
16         );
17 
18         await client.Funding.FundingRecipients.CreateAsync(
19             new CreateFundingRecipient {
20                 IdempotencyKey = "8e03978e-40d5-43e8-bc93-6894a57f9324",
21                 RecipientType = CreateFundingRecipientRecipientType.PrivateCorporation,
22                 TaxId = "12-3456789",
23                 DoingBusinessAs = "Pizza Doe",
24                 Address = new Address {
25                     Address1 = "1 Example Ave.",
26                     Address2 = "Example Address Line 2",
27                     Address3 = "Example Address Line 3",
28                     City = "Chicago",
29                     State = "Illinois",
30                     Country = "US",
31                     PostalCode = "60056"
32                 },
33                 ContactMethods = new List<ContactMethod>(){
34                     new ContactMethod(
35                         new ContactMethodEmail {
36                             Value = "[email protected]"
37                         }
38                     ),
39                     new ContactMethod(
40                         new ContactMethodPhone {
41                             Value = "2025550164"
42                         }
43                     ),
44                 }
45                 ,
46                 Owners = new List<Owner>(){
47                     new Owner {
48                         FirstName = "Jane",
49                         LastName = "Doe",
50                         DateOfBirth = DateOnly.Parse("1964-03-22"),
51                         Address = new Address {
52                             Address1 = "1 Example Ave.",
53                             City = "Chicago",
54                             State = "Illinois",
55                             Country = "US",
56                             PostalCode = "60056"
57                         },
58                         Identifiers = new List<Identifier>(){
59                             new Identifier {
60                                 Type = IdentifierType.NationalId,
61                                 Value = "000-00-4320"
62                             },
63                         }
64                         ,
65                         ContactMethods = new List<ContactMethod>(){
66                             new ContactMethod(
67                                 new ContactMethodEmail {
68                                     Value = "[email protected]"
69                                 }
70                             ),
71                             new ContactMethod(
72                                 new ContactMethodPhone {
73                                     Value = "2025550164"
74                                 }
75                             ),
76                         }
77                         ,
78                         Relationship = new OwnerRelationship {
79                             IsControlProng = true,
80                             EquityPercentage = 48.5f,
81                             Title = "CFO",
82                             IsAuthorizedSignatory = false
83                         },
84                         MiddleName = "Helen"
85                     },
86                 }
87                 ,
88                 FundingAccounts = new List<FundingAccount>(){
89                     new FundingAccount {
90                         Type = FundingAccountType.Checking,
91                         Use = FundingAccountUse.Credit,
92                         NameOnAccount = "Jane Doe",
93                         PaymentMethods = new List<PaymentMethodsItem>(){
94                             new PaymentMethodsItem(
95                                 new PaymentMethodAch {
96                                     Value = new PaymentMethodAchValue {
97                                         RoutingNumber = "123456789",
98                                         AccountNumber = "1234567890"
99                                     }
100                                 }
101                             ),
102                         }
103 
104                     },
105                 }
106                 ,
107                 Metadata = new Dictionary<string, string>(){
108                     ["yourCustomField"] = "abc123",
109                 }
110 
111             }
112         );
113     }
114 
115 }

Try it

Successful 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     "state": "Illinois",
11     "country": "US",
12     "postalCode": "60056"
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 2: Add a Funding Account to a Recipient

You can use our /funding-recipients endpoint to manage Funding Accounts associated with a Recipient.

Use our /funding-recipients endpoint to add a new Funding Account to an existing Recipient.

POST

/v1/funding-recipients/:recipientId/funding-accounts

1 using Payroc;
2 using System.Threading.Tasks;
3 using Payroc.Funding.FundingRecipients;
4 using System.Collections.Generic;
5 
6 namespace Usage;
7 
8 public class Example
9 {
10     public async Task Do() {
11         var client = new BasePayrocClient(
12             clientOptions: new ClientOptions {
13                 Environment = PayrocEnvironment.Production
14             }
15         );
16 
17         await client.Funding.FundingRecipients.CreateAccountAsync(
18             new CreateAccountFundingRecipientsRequest {
19                 RecipientId = 234,
20                 IdempotencyKey = "8e03978e-40d5-43e8-bc93-6894a57f9324",
21                 Body = new FundingAccount {
22                     Type = FundingAccountType.Savings,
23                     Use = FundingAccountUse.Credit,
24                     NameOnAccount = "Fred Nerk",
25                     PaymentMethods = new List<PaymentMethodsItem>(){
26                         new PaymentMethodsItem(
27                             new PaymentMethodAch {
28                                 Value = new PaymentMethodAchValue {
29                                     RoutingNumber = "123123123",
30                                     AccountNumber = "987654321"
31                                 }
32                             }
33                         ),
34                     }
35                     ,
36                     Metadata = new Dictionary<string, string>(){
37                         ["responsiblePerson"] = "Jane Doe",
38                     }
39 
40                 }
41             }
42         );
43     }
44 
45 }

Try it

Successful response:

Response

1 {
2   "type": "checking",
3   "use": "credit",
4   "nameOnAccount": "Jane Doe",
5   "paymentMethods": [
6     {
7       "type": "ach",
8       "value": {
9         "routingNumber": "*****6789",
10         "accountNumber": "******7890"
11       }
12     }
13   ],
14   "fundingAccountId": 123,
15   "createdDate": "2024-07-02T15:30:00Z",
16   "lastModifiedDate": "2024-07-02T15:30:00Z",
17   "status": "approved",
18   "metadata": {
19     "yourCustomField": "abc123"
20   },
21   "links": [
22     {
23       "rel": "parent",
24       "method": "get",
25       "href": "https://api.payroc.com/v1/funding-recipients/234"
26     }
27   ]
28 }

Test 3: Add a new Owner to a Recipient

You can use our /funding-recipients endpoint to create and manage Owner objects associated with the Funding Recipient.

Use our /funding-recipients endpoint to create a new Owner.

POST

/v1/funding-recipients/:recipientId/owners

1 using Payroc;
2 using System.Threading.Tasks;
3 using Payroc.Funding.FundingRecipients;
4 using System;
5 using System.Collections.Generic;
6 
7 namespace Usage;
8 
9 public class Example
10 {
11     public async Task Do() {
12         var client = new BasePayrocClient(
13             clientOptions: new ClientOptions {
14                 Environment = PayrocEnvironment.Production
15             }
16         );
17 
18         await client.Funding.FundingRecipients.CreateOwnerAsync(
19             new CreateOwnerFundingRecipientsRequest {
20                 RecipientId = 234,
21                 IdempotencyKey = "8e03978e-40d5-43e8-bc93-6894a57f9324",
22                 Body = new Owner {
23                     FirstName = "Fred",
24                     LastName = "Nerk",
25                     DateOfBirth = DateOnly.Parse("1980-01-19"),
26                     Address = new Address {
27                         Address1 = "2 Example Ave.",
28                         City = "Chicago",
29                         State = "Illinois",
30                         Country = "US",
31                         PostalCode = "60056"
32                     },
33                     Identifiers = new List<Identifier>(){
34                         new Identifier {
35                             Type = IdentifierType.NationalId,
36                             Value = "000-00-9876"
37                         },
38                     }
39                     ,
40                     ContactMethods = new List<ContactMethod>(){
41                         new ContactMethod(
42                             new ContactMethodEmail {
43                                 Value = "[email protected]"
44                             }
45                         ),
46                         new ContactMethod(
47                             new ContactMethodPhone {
48                                 Value = "2025550110"
49                             }
50                         ),
51                     }
52                     ,
53                     Relationship = new OwnerRelationship {
54                         IsControlProng = false,
55                         EquityPercentage = 51.5f,
56                         Title = "CEO",
57                         IsAuthorizedSignatory = true
58                     },
59                     MiddleName = "Jim"
60                 }
61             }
62         );
63     }
64 
65 }

Try it

Successful response:

Response

1 {
2   "firstName": "Jane",
3   "lastName": "Doe",
4   "dateOfBirth": "1964-03-22",
5   "address": {
6     "address1": "1 Example Ave.",
7     "city": "Chicago",
8     "state": "Illinois",
9     "country": "US",
10     "postalCode": "60056",
11     "address2": "Example Address Line 2",
12     "address3": "Example Address Line 3"
13   },
14   "identifiers": [
15     {
16       "type": "nationalId",
17       "value": "xxxxx4320"
18     }
19   ],
20   "contactMethods": [
21     {
22       "type": "email",
23       "value": "[email protected]"
24     }
25   ],
26   "relationship": {
27     "isControlProng": true,
28     "equityPercentage": 48.5,
29     "title": "CFO",
30     "isAuthorizedSignatory": false
31   },
32   "ownerId": 4564,
33   "middleName": "Helen"
34 }

Test 4: Retrieve the Funding Accounts for a Recipient

To create accurate Funding Instructions, it’s important to make sure that you can retrieve a list of Funding Accounts for any Funding Recipients that you create.

Use our /funding-accounts endpoint to retrieve a list of Funding Accounts for a Funding Recipient.

GET

/v1/funding-recipients/:recipientId/funding-accounts

1 using Payroc;
2 using System.Threading.Tasks;
3 using Payroc.Funding.FundingRecipients;
4 
5 namespace Usage;
6 
7 public class Example
8 {
9     public async Task Do() {
10         var client = new BasePayrocClient(
11             clientOptions: new ClientOptions {
12                 Environment = PayrocEnvironment.Production
13             }
14         );
15 
16         await client.Funding.FundingRecipients.ListAccountsAsync(
17             new ListFundingRecipientFundingAccountsRequest {
18                 RecipientId = 234
19             }
20         );
21     }
22 
23 }

Try it

Successful response:

Response

1 [
2   {
3     "type": "checking",
4     "use": "credit",
5     "nameOnAccount": "Jane Doe",
6     "paymentMethods": [
7       {
8         "type": "ach",
9         "value": {
10           "routingNumber": "*****6789",
11           "accountNumber": "******7890"
12         }
13       }
14     ],
15     "fundingAccountId": 123,
16     "createdDate": "2024-07-02T15:30:00Z",
17     "lastModifiedDate": "2024-07-02T15:30:00Z",
18     "status": "approved",
19     "metadata": {
20       "yourCustomField": "abc123"
21     },
22     "links": [
23       {
24         "rel": "parent",
25         "method": "get",
26         "href": "https://api.payroc.com/v1/funding-recipients/234"
27       }
28     ]
29   },
30   {
31     "type": "checking",
32     "use": "debit",
33     "nameOnAccount": "Jane Doe",
34     "paymentMethods": [
35       {
36         "type": "ach",
37         "value": {
38           "routingNumber": "*****8725",
39           "accountNumber": "******3491"
40         }
41       }
42     ],
43     "fundingAccountId": 124,
44     "createdDate": "2024-07-02T15:30:00Z",
45     "lastModifiedDate": "2024-07-02T15:30:00Z",
46     "status": "pending",
47     "metadata": {
48       "yourCustomField": "abc123"
49     },
50     "links": [
51       {
52         "rel": "parent",
53         "method": "get",
54         "href": "https://api.payroc.com/v1/funding-recipients/235"
55       }
56     ]
57   }
58 ]

Testing Funding Instructions

You can use our /funding-instructions endpoint to tell us how to split your available funds across multiple Funding Accounts. For example, Funding Accounts that belong to your sales office, your merchants, or any Funding Recipients. To verify that your integration works with this endpoint, run the following tests:

Test 5: Create a new Funding Instruction

A Funding Instruction tells us how to split funds across multiple accounts.

Use our /funding-accounts endpoint to retrieve a list of Funding Accounts.
Use our /funding-instructions endpoint to create a new Funding Instruction.

POST

/v1/funding-instructions

1 using Payroc;
2 using System.Threading.Tasks;
3 using Payroc.Funding.FundingInstructions;
4 using System.Collections.Generic;
5 
6 namespace Usage;
7 
8 public class Example
9 {
10     public async Task Do() {
11         var client = new BasePayrocClient(
12             clientOptions: new ClientOptions {
13                 Environment = PayrocEnvironment.Production
14             }
15         );
16 
17         await client.Funding.FundingInstructions.CreateAsync(
18             new CreateFundingInstructionsRequest {
19                 IdempotencyKey = "8e03978e-40d5-43e8-bc93-6894a57f9324",
20                 Body = new Instruction {
21                     Merchants = new List<InstructionMerchantsItem>(){
22                         new InstructionMerchantsItem {
23                             MerchantId = "4525644354",
24                             Recipients = new List<InstructionMerchantsItemRecipientsItem>(){
25                                 new InstructionMerchantsItemRecipientsItem {
26                                     FundingAccountId = 123,
27                                     PaymentMethod = InstructionMerchantsItemRecipientsItemPaymentMethod.Ach,
28                                     Amount = new InstructionMerchantsItemRecipientsItemAmount {
29                                         Value = 120000,
30                                         Currency = InstructionMerchantsItemRecipientsItemAmountCurrency.Usd
31                                     },
32                                     Metadata = new Dictionary<string, string>(){
33                                         ["yourCustomField"] = "abc123",
34                                     }
35 
36                                 },
37                             }
38 
39                         },
40                     }
41                     ,
42                     Metadata = new Dictionary<string, string>(){
43                         ["yourCustomField"] = "abc123",
44                     }
45 
46                 }
47             }
48         );
49     }
50 
51 }

Try it

Successful response:

Response

1 {
2   "instructionId": 64643131,
3   "createdDate": "2024-07-02T15:30:00Z",
4   "lastModifiedDate": "2024-07-02T15:30:00Z",
5   "status": "accepted",
6   "merchants": [
7     {
8       "merchantId": "4525644354",
9       "recipients": [
10         {
11           "fundingAccountId": 123,
12           "paymentMethod": "ACH",
13           "amount": {
14             "value": 120000,
15             "currency": "USD"
16           },
17           "status": "accepted",
18           "metadata": {
19             "yourCustomField": "abc123"
20           },
21           "link": {
22             "rel": "fundingAccount",
23             "method": "get",
24             "href": "https://api.payroc.com/v1/funding-accounts/123"
25           }
26         }
27       ],
28       "link": {
29         "rel": "merchant",
30         "method": "get",
31         "href": "https://api.payroc.com/v1/processing-accounts/4525644354"
32       }
33     }
34   ],
35   "metadata": {
36     "instructionRef": "abc123"
37   }
38 }

Test 6: Update a Funding Instruction

While a Funding Instruction has a status of accepted, you can continue to edit and update the instruction. To update a Funding Instruction, you must send a PUT request to the correct Funding Instruction id.

Use our /funding-instructions endpoint to update a Funding Instruction.

Successful response:

Test 7: List Funding Activity

You can use our /funding-activity endpoint to retrieve a list of all funding activity so far.

Use our /funding-activity endpoint to retrieve a list of all funding activity.

GET

/v1/funding-activity

1 using Payroc;
2 using System.Threading.Tasks;
3 using Payroc.Funding.FundingActivity;
4 using System;
5 
6 namespace Usage;
7 
8 public class Example
9 {
10     public async Task Do() {
11         var client = new BasePayrocClient(
12             clientOptions: new ClientOptions {
13                 Environment = PayrocEnvironment.Production
14             }
15         );
16 
17         await client.Funding.FundingActivity.ListAsync(
18             new ListFundingActivityRequest {
19                 Before = "2571",
20                 After = "8516",
21                 Limit = 25,
22                 DateFrom = DateOnly.Parse("2024-07-02"),
23                 DateTo = DateOnly.Parse("2024-07-03"),
24                 MerchantId = "4525644354"
25             }
26         );
27     }
28 
29 }

Try it

Successful response:

Response

1 {
2   "data": [
3     {
4       "id": 11,
5       "date": "2024-07-02T17:00:00.000Z",
6       "merchant": "Pizza Doe",
7       "description": "sales",
8       "amount": 4999,
9       "type": "credit",
10       "currency": "USD"
11     },
12     {
13       "id": 12,
14       "date": "2024-07-02T19:32:00.000Z",
15       "merchant": "Pizza Doe",
16       "description": "sales",
17       "amount": 3999,
18       "type": "credit",
19       "currency": "USD"
20     },
21     {
22       "id": 13,
23       "date": "2024-07-02T17:00:00.000Z",
24       "merchant": "Pizza Doe",
25       "description": "sales",
26       "amount": 3299,
27       "type": "credit",
28       "currency": "USD"
29     },
30     {
31       "id": 14,
32       "date": "2024-07-02T17:00:00.000Z",
33       "merchant": "Pizza Doe",
34       "description": "Interchange Fees",
35       "amount": 50,
36       "type": "debit",
37       "currency": "USD",
38       "recipient": "Payroc"
39     },
40     {
41       "id": 15,
42       "date": "2024-07-02T09:10:00.000Z",
43       "merchant": "Pizza Doe",
44       "description": "sales",
45       "amount": 4999,
46       "type": "credit",
47       "currency": "USD"
48     },
49     {
50       "id": 16,
51       "date": "2024-07-02T17:00:00.000Z",
52       "merchant": "Doe Hot Dogs",
53       "description": "Adjustment",
54       "amount": 750,
55       "type": "credit",
56       "currency": "USD"
57     },
58     {
59       "id": 17,
60       "date": "2024-07-02T17:00:00.000Z",
61       "merchant": "Doe Hot Dogs",
62       "description": "Interchange Fees",
63       "amount": 5,
64       "type": "debit",
65       "currency": "USD",
66       "recipient": "Payroc"
67     },
68     {
69       "id": 18,
70       "date": "2024-07-02T17:00:00.000Z",
71       "merchant": "Pizza Doe",
72       "description": "Charge back",
73       "amount": 1000,
74       "type": "debit",
75       "currency": "USD",
76       "recipient": "Payroc"
77     },
78     {
79       "id": 19,
80       "date": "2024-07-02T17:00:00.000Z",
81       "merchant": "Pizza Doe",
82       "description": "sales",
83       "amount": 5999,
84       "type": "credit",
85       "currency": "USD"
86     },
87     {
88       "id": 20,
89       "date": "2024-07-02T17:00:00.000Z",
90       "merchant": "Pizza Doe",
91       "description": "payment",
92       "amount": 1000,
93       "type": "debit",
94       "currency": "USD",
95       "recipient": "Pizza Doe"
96     }
97   ],
98   "count": 10,
99   "hasMore": true,
100   "limit": 10,
101   "links": [
102     {
103       "rel": "previous",
104       "method": "get",
105       "href": "https://api.payroc.com/v1/funding-activity?before=11&limit=10&datefrom=2024-07-01&dateto=2024-07-03"
106     },
107     {
108       "rel": "next",
109       "method": "get",
110       "href": "https://api.payroc.com/v1/funding-activity?after=20&limit=10&datefrom=2024-07-01&dateto=2024-07-03"
111     }
112   ]
113 }

Results

After you complete your tests, send your results to [email protected]. A member of our team will contact you to confirm certification or to provide support.

Need more help?

We are here to help! If you need help with your integration, contact us at [email protected] or through our Developer Community.