Developer resources
/
Test your Integration
/
Funding

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.
Successful response:
Response
application/json
{
  "recipientId": 234,
  "status": "approved",
  "createdDate": "2024-07-02T15:30:00Z",
  "lastModifiedDate": "2024-07-02T15:30:00Z",
  "recipientType": "privateCorporation",
  "taxId": "12-3456789",
  "charityId": "abc123",
  "doingBuinessAs": "abc123",
  "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": "[email protected]"
    }
  ],
  "metadata": {
    "yourCustomField": "abc123"
  },
  "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"
      }
    }
  ]
}

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.
Successful response:
Response
application/json
{
  "fundingAccountId": 123,
  "createdDate": "2024-07-02T15:30:00Z",
  "lastModifiedDate": "2024-07-02T15:30:00Z",
  "status": "approved",
  "type": "checking",
  "use": "credit",
  "nameOnAccount": "Jane Doe",
  "paymentMethods": [
    {
      "type": "ach",
      "value": {
        "routingNumber": "*****6789",
        "accountNumber": "******7890"
      }
    }
  ],
  "metadata": {
    "yourCustomField": "abc123"
  },
  "links": [
    {
      "rel": "parent",
      "href": "https://api.payroc.com/v1/funding-recipient/234",
      "method": "get"
    }
  ]
}

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 to create a new Owner.
Successful response:
Response
application/json
{
  "ownerId": 4564,
  "firstName": "Jane",
  "middleName": "Helen",
  "lastName": "Doe",
  "dateOfBirth": "1964-03-22",
  "address": {
    "address1": "1 Example Ave.",
    "address2": "Example Address Line 2",
    "address3": "Example Address Line 3",
    "city": "Chicago",
    "state": "Illinois",
    "country": "US",
    "postalCode": "60056"
  },
  "identifiers": [
    {
      "type": "nationalId",
      "value": "xxxxx4320"
    }
  ],
  "contactMethods": [
    {
      "type": "email",
      "value": "[email protected]"
    }
  ],
  "relationship": {
    "equityPercentage": 48.5,
    "title": "CFO",
    "isControlProng": true,
    "isAuthorizedSignatory": false
  }
}

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.
Successful response:
Response
application/json
[
  {
    "fundingAccountId": 123,
    "createdDate": "2024-07-02T15:30:00Z",
    "lastModifiedDate": "2024-07-02T15:30:00Z",
    "status": "approved",
    "type": "checking",
    "use": "credit",
    "nameOnAccount": "Jane Doe",
    "paymentMethods": [
      {
        "type": "ach",
        "value": {
          "routingNumber": "*****6789",
          "accountNumber": "******7890"
        }
      }
    ],
    "metadata": {
      "yourCustomField": "abc123"
    },
    "links": [
      {
        "rel": "parent",
        "href": "https://api.payroc.com/v1/funding-recipient/234",
        "method": "get"
      }
    ]
  },
  {
    "fundingAccountId": 124,
    "createdDate": "2024-07-02T15:30:00Z",
    "lastModifiedDate": "2024-07-02T15:30:00Z",
    "status": "pending",
    "type": "checking",
    "use": "debit",
    "nameOnAccount": "Jane Doe",
    "paymentMethods": [
      {
        "type": "ach",
        "value": {
          "routingNumber": "*****8725",
          "accountNumber": "******3491"
        }
      }
    ],
    "metadata": {
      "yourCustomField": "abc123"
    },
    "links": [
      {
        "rel": "parent",
        "href": "https://api.payroc.com/v1/funding-recipient/235",
        "method": "get"
      }
    ]
  }
]

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.
Successful response:
Response
application/json
{
  "instructionId": 64643131,
  "createdDate": "2024-07-02T15:30:00Z",
  "lastModifiedDate": "2024-07-02T15:30:00Z",
  "status": "accepted",
  "merchants": [
    {
      "merchantId": "4525644354",
      "recipients": [
        {
          "status": "accepted",
          "fundingAccountId": 123,
          "paymentMethod": "ACH",
          "amount": {
            "value": 120000,
            "currency": "USD"
          },
          "metadata": {
            "yourCustomField": "abc123"
          },
          "link": {
            "rel": "fundingAccount",
            "method": "get",
            "href": "https://api.payroc.com/v1/funding-accounts/123"
          }
        }
      ],
      "link": {
        "rel": "merchant",
        "method": "get",
        "href": "https://api.payroc.com/v1/merchants/4525644354"
      }
    }
  ],
  "metadata": {
    "instructionRef": "abc123"
  }
}

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:
Response
application/json
{
  "instructionId": 64643131,
  "createdDate": "2024-07-02T15:30:00Z",
  "lastModifiedDate": "2024-07-02T15:30:00Z",
  "status": "accepted",
  "merchants": [
    {
      "merchantId": "4525644354",
      "recipients": [
        {
          "status": "accepted",
          "fundingAccountId": 123,
          "paymentMethod": "ACH",
          "amount": {
            "value": 120000,
            "currency": "USD"
          },
          "metadata": {
            "yourCustomField": "abc123"
          },
          "link": {
            "rel": "fundingAccount",
            "method": "get",
            "href": "https://api.payroc.com/v1/funding-accounts/123"
          }
        }
      ],
      "link": {
        "rel": "merchant",
        "method": "get",
        "href": "https://api.payroc.com/v1/merchants/4525644354"
      }
    }
  ],
  "metadata": {
    "instructionRef": "abc123"
  }
}

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.
Successful response:
Response
application/json
{
  "limit": 10,
  "count": 10,
  "hasMore": true,
  "links": [
    {
      "rel": "previous",
      "method": "get",
      "href": "https://api.payroc.com/v1/funding-activity?before=11&limit=10&datefrom=2024-07-01&dateto=2024-07-03"
    },
    {
      "rel": "next",
      "method": "get",
      "href": "https://api.payroc.com/v1/funding-activity?after=20&limit=10&datefrom=2024-07-01&dateto=2024-07-03"
    }
  ],
  "data": [
    {
      "id": 11,
      "date": "2024-07-02T17:00:00.000Z",
      "merchant": "Pizza Doe",
      "recipient": "Pizza Doe",
      "description": "Large Pepperoni Pizza",
      "type": "credit",
      "amount": 4999,
      "currency": "USD"
    },
    {
      "id": 12,
      "date": "2024-07-02T19:32:00.000Z",
      "merchant": "Pizza Doe",
      "recipient": "Pizza Doe",
      "description": "Medium Pepperoni Pizza",
      "type": "credit",
      "amount": 3999,
      "currency": "USD"
    },
    {
      "id": 13,
      "date": "2024-07-02T17:00:00.000Z",
      "merchant": "Pizza Doe",
      "recipient": "Pizza Doe",
      "description": "Small Pepperoni Pizza",
      "type": "credit",
      "amount": 3299,
      "currency": "USD"
    },
    {
      "id": 14,
      "date": "2024-07-02T17:00:00.000Z",
      "merchant": "Pizza Doe",
      "recipient": "Payroc",
      "description": "Interchange Fees",
      "type": "debit",
      "amount": 50,
      "currency": "USD"
    },
    {
      "id": 15,
      "date": "2024-07-02T09:10:00.000Z",
      "merchant": "Pizza Doe",
      "recipient": "Pizza Doe",
      "description": "Premium Club Subscription",
      "type": "credit",
      "amount": 4999,
      "currency": "USD"
    },
    {
      "id": 16,
      "date": "2024-07-02T17:00:00.000Z",
      "merchant": "Doe Hot Dogs",
      "recipient": "Doe Hot Dogs",
      "description": "Adjustment",
      "type": "credit",
      "amount": 750,
      "currency": "USD"
    },
    {
      "id": 17,
      "date": "2024-07-02T17:00:00.000Z",
      "merchant": "Doe Hot Dogs",
      "recipient": "Payroc",
      "description": "Interchange Fees",
      "type": "debit",
      "amount": 5,
      "currency": "USD"
    },
    {
      "id": 18,
      "date": "2024-07-02T17:00:00.000Z",
      "merchant": "Pizza Doe",
      "recipient": "Payroc",
      "description": "Charge back",
      "type": "debit",
      "amount": 1000,
      "currency": "USD"
    },
    {
      "id": 19,
      "date": "2024-07-02T17:00:00.000Z",
      "merchant": "Pizza Doe",
      "recipient": "Pizza Doe",
      "description": "Family Meal Deal",
      "type": "credit",
      "amount": 5999,
      "currency": "USD"
    },
    {
      "id": 20,
      "date": "2024-07-02T17:00:00.000Z",
      "merchant": "Pizza Doe",
      "recipient": "Pizza Doe",
      "description": "Reservation",
      "type": "debit",
      "amount": 1000,
      "currency": "USD"
    }
  ]
}

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.