List funding instructions

Browse API reference

GET/funding-instructionslistInstructions

Important: You can return a list of funding instructions from only the previous two years. If you want to view a funding instruction from more than two years ago and you have its instructionId, use our Retrieve Funding Instruction method.

Use this method to return a paginated list of funding instructions within a specific date range.

Note: If you want to view the details of a specific funding instruction and you have its instructionId, use our Retrieve Funding Instruction method.

Our gateway returns the following information for each instruction in the list:

Status of the funding instruction.
Funding information, including which merchant's funding balance we distribute and the funding account that we send the balance to.

For each funding instruction, we also return the instructionId, which you can use to perform follow-on actions.

Parameters

Name	In	Type	Description
`before`	query	`string`	Return the previous page of results before the value that you specify. You can’t send the before parameter in the same request as the after parameter.
`after`	query	`string`	Return the next page of results after the value that you specify. You can’t send the after parameter in the same request as the before parameter.
`limit`	query	`integer`	Limit the maximum number of results that we return for each page.
`dateFrom`Required	query	`string`	Filter by funding instructions sent after a specific date. Send a value in YYYY-MM-DD format.
`dateTo`Required	query	`string`	Filter by funding instructions sent before a specific date. Send a value in YYYY-MM-DD format.

Responses

Successful request. Returns a list of funding instructions.

200 OK · application/json

{
  "count": 2,
  "data": [
    {
      "createdDate": "2024-07-02T15:30:00Z",
      "instructionId": 64643131,
      "lastModifiedDate": "2024-07-02T15:30:00Z",
      "link": {
        "href": "https://api.payroc.com/v1/funding-instructions/64643131",
        "method": "get",
        "rel": "fundingInstruction"
      },
      "merchants": [
        {
          "link": {
            "href": "https://api.payroc.com/v1/processing-accounts/4525644354",
            "method": "get",
            "rel": "merchant"
          },
          "merchantId": "4525644354",
          "recipients": [
            {
              "amount": {
                "currency": "USD",
                "value": 120000
              },
              "fundingAccountId": 123,
              "link": {
                "href": "https://api.payroc.com/v1/funding-accounts/123",
                "method": "get",
                "rel": "fundingAccount"
              },
              "metadata": {
                "yourCustomField": "abc123"
              },
              "paymentMethod": "ACH",
              "status": "funded"
            },
            {
              "amount": {
                "currency": "USD",
                "value": 50050
              },
              "fundingAccountId": 124,
              "link": {
                "href": "https://api.payroc.com/v1/funding-accounts/124",
                "method": "get",
                "rel": "fundingAccount"
              },
              "metadata": {
                "yourCustomField": "abc123"
              },
              "paymentMethod": "ACH",
              "status": "rejected"
            }
          ]
        }
      ],
      "metadata": {
        "yourCustomField": "abc123"
      },
      "status": "completed"
    },
    {
      "createdDate": "2024-07-02T15:30:00Z",
      "instructionId": 64643132,
      "lastModifiedDate": "2024-07-02T15:30:00Z",
      "link": {
        "href": "https://api.payroc.com/v1/funding-instructions/64643132",
        "method": "get",
        "rel": "fundingInstruction"
      },
      "merchants": [
        {
          "link": {
            "href": "https://api.payroc.com/v1/processing-accounts/4525644354",
            "method": "get",
            "rel": "merchant"
          },
          "merchantId": "4525644354",
          "recipients": [
            {
              "amount": {
                "currency": "USD",
                "value": 5000
              },
              "fundingAccountId": 123,
              "link": {
                "href": "https://api.payroc.com/v1/funding-accounts/123",
                "method": "get",
                "rel": "fundingAccount"
              },
              "metadata": {
                "yourCustomField": "abc123"
              },
              "paymentMethod": "ACH",
              "status": "accepted"
            }
          ]
        },
        {
          "link": {
            "href": "https://api.payroc.com/v1/processing-accounts/4525644354",
            "method": "get",
            "rel": "merchant"
          },
          "merchantId": "4525644354",
          "recipients": [
            {
              "amount": {
                "currency": "USD",
                "value": 1000
              },
              "fundingAccountId": 124,
              "link": {
                "href": "https://api.payroc.com/v1/funding-accounts/124",
                "method": "get",
                "rel": "fundingAccount"
              },
              "metadata": {
                "yourCustomField": "abc123"
              },
              "paymentMethod": "ACH",
              "status": "accepted"
            }
          ]
        }
      ],
      "metadata": {
        "yourCustomField": "abc123"
      },
      "status": "accepted"
    }
  ],
  "hasMore": true,
  "limit": 2,
  "links": [
    {
      "href": "https://api.payroc.com/v1/funding-instructions?before=64643131&limit=2&datefrom=2024-07-01&dateto=2024-07-03",
      "method": "get",
      "rel": "previous"
    },
    {
      "href": "https://api.payroc.com/v1/funding-instructions?after=64643132&limit=2&datefrom=2024-07-01&dateto=2024-07-03",
      "method": "get",
      "rel": "next"
    }
  ]
}

Response schema · 21 of 35 fields

countinteger
Number of results we returned on this page. Note: This might not be the total number of results that match your query.
hasMoreboolean
Indicates whether there is another page of results available.
limitinteger
Maximum number of results that we return for each page.
linksobject[]
Reference links to navigate to the previous page of results or to the next page of results.
- hrefstringrequired
  URL of the target resource.
- methodstringrequired
  HTTP method that you need to use with the target resource.
- relstringrequired
  Indicates the relationship between the current resource and the target resource.
dataobject[]required
Array of fundingInstruction objects.
- createdDatestringdatetime
  Date that we created the funding instruction. The date format follows the ISO 8601 standard.
- instructionIdinteger
  Unique identifier that we assigned to the funding instruction.
- lastModifiedDatestringdatetime
  Date of the most recent change to the funding instruction. The date format follows the ISO 8601 standard.
- merchantsobject[]
  Array of merchants objects. Each object specifies the merchant whose funding balance we distribute and who you want to send the funds to.
  - linkobject
    Object that contains HATEOAS links for the resource.+3 more fields at deeper levels — see the full spec
  - merchantIdstringrequired
    Unique identifier that the processor assigned to the merchant.
  - recipientsobject[]required
    Array of recipients objects. Each object contains information about the funding account and the amount of funds we send to the funding account.≥ 1 items+11 more fields at deeper levels — see the full spec
- metadataobject
  Metadata object you can use to include custom data with your request.
- statusstring
  Status of the funding instruction. Our gateway returns one of the following values: accepted We have received the funding instruction but have not yet reviewed it. pending We have received the funding instruction and we are reviewing it. completed We have reviewed and processed the funding instruction.acceptedpendingcompleted
- linkobject
  Object that contains HATEOAS links for the resource.
  - hrefstringrequired
    URL of the target resource.
  - methodstringrequired
    HTTP method that you need to use with the target resource.
  - relstringrequired
    Indicates the relationship between the current resource and the target resource.

Validation error.

400 Bad Request · application/problem+json

{
  "detail": "One or more validation errors occurred, see error section for more info",
  "errors": [
    {
      "detail": "invalid date",
      "message": "datefrom cannot be longer than two years ago.",
      "parameter": "datefrom"
    }
  ],
  "status": 400,
  "title": "Bad request",
  "type": "https://docs.payroc.com/api/errors#bad-request"
}

Response schema · 8 fields

detailstringrequired
Explanation of the problem
errorsobject[]
- detailstring
  Short detail of the validation errors
- messagestring
  Error message
- parameterstring
  The parameter or field causing the issues
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Identity could not be verified

401 Unauthorized · application/problem+json

{
  "detail": "Your identity could not be verified",
  "status": 401,
  "title": "Not Authorized",
  "type": "https://docs.payroc.com/api/errors#not-authorized"
}

Response schema · 4 fields

detailstringrequired
Explanation of the problem
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Do not have permissions to perform this action

403 Forbidden · application/problem+json

{
  "detail": "You do not have the required permissions to perform this action",
  "instance": "https://api.payroc.com/v1/exampleResource/3",
  "resource": "exampleResource",
  "status": 403,
  "title": "Forbidden",
  "type": "https://docs.payroc.com/api/errors#forbidden"
}

Response schema · 6 fields

detailstringrequired
Explanation of the problem
instancestring
Resource path the action was attempted on
resourcestring
Resource the action was attempted on
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Not acceptable

406 Not Acceptable · application/problem+json

{
  "detail": "Resource does not support the representation requested",
  "status": 406,
  "title": "Not acceptable",
  "type": "https://docs.payroc.com/api/errors#not-acceptable"
}

Response schema · 4 fields

detailstringrequired
Explanation of the problem
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

An error has occured

500 Internal Server Error · application/problem+json

{
  "detail": "We are unable to process your request at this time",
  "errors": [
    {
      "message": "Service offline"
    }
  ],
  "status": 500,
  "title": "Api error",
  "type": "https://docs.payroc.com/api/errors#api-error"
}

Response schema · 6 fields

detailstringrequired
Explanation of the problem
errorsobject[]
- messagestring
  Error message
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Used in workflows

delete-a-funding-instruction update-a-funding-instruction