Test your integration

Funding

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
1curl -X POST https://api.payroc.com/v1/funding-recipients \
2     -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
3     -H "Authorization: Bearer <token>" \
4     -H "Content-Type: application/json" \
5     -d '{
6  "recipientType": "privateCorporation",
7  "taxId": "12-3456789",
8  "address": {
9    "address1": "1 Example Ave.",
10    "city": "Chicago",
11    "state": "Illinois",
12    "country": "US",
13    "postalCode": "60056"
14  },
15  "contactMethods": [
16    {
17      "type": "email",
18      "value": "[email protected]"
19    }
20  ],
21  "owners": [
22    {
23      "firstName": "Jane",
24      "lastName": "Doe",
25      "dateOfBirth": "1964-03-22",
26      "address": {
27        "address1": "1 Example Ave.",
28        "city": "Chicago",
29        "state": "Illinois",
30        "country": "US",
31        "postalCode": "60056"
32      },
33      "identifiers": [
34        {
35          "type": "nationalId",
36          "value": "xxxxx4320"
37        }
38      ],
39      "contactMethods": [
40        {
41          "type": "email",
42          "value": "[email protected]"
43        }
44      ],
45      "relationship": {
46        "isControlProng": true
47      }
48    }
49  ],
50  "fundingAccounts": [
51    {
52      "type": "checking",
53      "use": "credit",
54      "nameOnAccount": "Jane Doe",
55      "paymentMethods": [
56        {}
57      ]
58    }
59  ]
60}'

Successful response:

Response
1{
2  "recipientType": "privateCorporation",
3  "taxId": "12-3456789",
4  "doingBuinessAs": "foo",
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": "foo",
55  "metadata": {}
56}

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
1curl -X POST https://api.payroc.com/v1/funding-recipients/234/funding-accounts \
2     -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
3     -H "Authorization: Bearer <token>" \
4     -H "Content-Type: application/json" \
5     -d '{
6  "type": "checking",
7  "use": "credit",
8  "nameOnAccount": "Jane Doe",
9  "paymentMethods": [
10    {}
11  ]
12}'

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-recipient/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
1curl -X POST https://api.payroc.com/v1/funding-recipients/234/owners \
2     -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
3     -H "Authorization: Bearer <token>" \
4     -H "Content-Type: application/json" \
5     -d '{
6  "firstName": "Jane",
7  "lastName": "Doe",
8  "dateOfBirth": "1964-03-22",
9  "address": {
10    "address1": "1 Example Ave.",
11    "city": "Chicago",
12    "state": "Illinois",
13    "country": "US",
14    "postalCode": "60056"
15  },
16  "identifiers": [
17    {
18      "type": "nationalId",
19      "value": "xxxxx4320"
20    }
21  ],
22  "contactMethods": [
23    {
24      "type": "email",
25      "value": "[email protected]"
26    }
27  ],
28  "relationship": {
29    "isControlProng": true
30  }
31}'

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": 0,
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
1curl https://api.payroc.com/v1/funding-recipients/234/funding-accounts \
2     -H "Authorization: Bearer <token>"

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-recipient/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-recipient/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
1curl -X POST https://api.payroc.com/v1/funding-instructions \
2     -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
3     -H "Authorization: Bearer <token>" \
4     -H "Content-Type: application/json" \
5     -d '{}'

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/merchants/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
1curl -G https://api.payroc.com/v1/funding-activity \
2     -H "Authorization: Bearer <token>" \
3     -d before=2571 \
4     -d after=8516 \
5     -d limit=25 \
6     -d dateFrom=2024-07-02 \
7     -d dateTo=2024-07-03 \
8     -d merchantId=4525644354

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.