Create funding instruction

Browse API reference

POST/funding-instructionscreateInstruction

Use this method to create a funding instruction that tells us how to distribute the funds from your merchants' transactions.

Note: Before you create a funding instruction, you can use our List Funding Balances method to view the amount of available funds that a merchant has.

In your request, include an array of merchantInstruction objects. Each merchantInstruction object contains the following:

Merchant ID (MID) of the merchant whose funding balance you want to distribute.
Funding account that you want to send funds to.
Amount that you want to send to the funding account.

Our gateway returns the instructionId, which you can use to run follow-on actions.

Parameters

Name	In	Type	Description
`Idempotency-Key`Required	header	`string`	Unique identifier that you generate for each request. You must use the UUID v4 format for the identifier. For more information about the idempotency key, go to Idempotency.

Request body

application/json

Field Edit request inputs →

merchantsobject[]
Array of merchants objects. Each object specifies the merchant whose funding balance we distribute and who you want to send the funds to.
- 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
  - amountobjectrequired
    Object that contains information about the funds that we send to the funding account.+2 more fields at deeper levels — see the full spec
  - fundingAccountIdintegerrequired
    Unique identifier that we assigned to the funding account.
  - metadataobject
    Metadata object you can use to include custom data with your request.
  - paymentMethodstringrequired
    Payment method that we use to send funds to the funding account.ACH
metadataobject
Metadata object you can use to include custom data with your request.

Responses

Successful request. We accepted the instructions.

201 Created · application/json

{
  "createdDate": "2024-07-02T15:30:00Z",
  "instructionId": 64643131,
  "lastModifiedDate": "2024-07-02T15:30:00Z",
  "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": {
            "supplier": "IT Support Services"
          },
          "paymentMethod": "ACH",
          "status": "accepted"
        }
      ]
    }
  ],
  "metadata": {
    "instructionCreatedBy": "Jane Doe"
  },
  "status": "accepted"
}

Response schema · 18 of 23 fields

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.
  - hrefstring
    URL of the target resource.
  - methodstring
    HTTP method that you need to use with the target resource.
  - relstring
    Indicates the relationship between the current resource and the target resource.
- 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
  - amountobjectrequired
    Object that contains information about the funds that we send to the funding account.+2 more fields at deeper levels — see the full spec
  - fundingAccountIdintegerrequired
    Unique identifier that we assigned to the funding account.
  - linkobject
    Object that contains HATEOAS links for the resource.+3 more fields at deeper levels — see the full spec
  - metadataobject
    Metadata object you can use to include custom data with your request.
  - paymentMethodstringrequired
    Payment method that we use to send funds to the funding account.ACH
  - statusstring
    Status of the individual payment instruction. Our gateway returns one of the following values: accepted We received the payment instruction, but we haven't reviewed it. pending We are reviewing the payment instruction. released We approved the payment instruction. funded We sent the funds to the funding account by ACH. failed The ACH payment to the funding account failed. rejected We reviewed the payment instruction and rejected it. onHold We have placed the payment instruction on hold.acceptedpendingreleasedfundedfailedrejectedonHold
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

Validation error.

400 Bad Request · application/problem+json

{
  "detail": "One or more funding accounts are restricted and can't receive funding instructions",
  "errors": [
    {
      "message": "Funding account on hold",
      "parameter": "fundingAccountId"
    }
  ],
  "status": 400,
  "title": "Funding accounts restricted",
  "type": "https://docs.payroc.com/api/errors#funding-accounts-restricted"
}

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

Conflict

409 Conflict · application/problem+json

{
  "detail": "'Idempotency-Key' is already in use against a different request",
  "status": 409,
  "title": "Idempotency-Key in use",
  "type": "https://docs.payroc.com/api/errors#idempotency-key-in-use"
}

Response schema · 13 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
instancestring
Resource path to the existing resource
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.
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

send-funds-to-a-merchant