---
title: "Create funding instruction"
method: POST
path: "/funding-instructions"
tags: ["fundingInstructions"]
---

# Create funding instruction

`POST /funding-instructions`

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](https://docs.payroc.com/api/schema/funding/funding-activity/retrieve-balance) 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.

## Headers

- `Authorization` string, required
- `Idempotency-Key` string, uuid, required

## Request body

- Instruction — Inform the payfac what to do with the specified funds. **
  - `instructionId` integer — Unique identifier that we assigned to the funding instruction.
  - `createdDate` string, datetime — Date that we created the funding instruction. The date format follows the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard.
  - `lastModifiedDate` string, datetime — Date of the most recent change to the funding instruction. The date format follows the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard.
  - `status` 'accepted' | 'pending' | 'completed' — 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.
  - `merchants` InstructionMerchantsItems[] — Array of merchants objects. Each object specifies the merchant whose funding balance we distribute and who you want to send the funds to.
    - `merchantId` string, required — Unique identifier that the processor assigned to the merchant.
    - `recipients` InstructionMerchantsItemsRecipientsItems[], required — Array of recipients objects. Each object contains information about the funding account and the amount of funds we send to the funding account.
      - `fundingAccountId` integer, required — Unique identifier that we assigned to the funding account.
      - `paymentMethod` 'ACH', required — Payment method that we use to send funds to the funding account.
      - `amount` InstructionMerchantsItemsRecipientsItemsAmount, required — Object that contains information about the funds that we send to the funding account.
        - `value` integer, required — Amount of funds in the currency's lowest denomination, for example, cents.
        - `currency` 'USD' — Currency of the value parameter.
      - `status` 'accepted' | 'pending' | 'released' | 'funded' | 'failed' | 'rejected' | 'onHold' — 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.
      - `metadata` object — [Metadata](https://docs.payroc.com/api/metadata) object you can use to include custom data with your request.
      - `link` InstructionMerchantsItemsRecipientsItemsLink — Object that contains HATEOAS links for the resource.
        - `rel` string — Indicates the relationship between the current resource and the target resource.
        - `method` string — HTTP method that you need to use with the target resource.
        - `href` string — URL of the target resource.
    - `link` InstructionMerchantsItemsLink — Object that contains HATEOAS links for the resource.
      - `rel` string — Indicates the relationship between the current resource and the target resource.
      - `method` string — HTTP method that you need to use with the target resource.
      - `href` string — URL of the target resource.
  - `metadata` object — [Metadata](https://docs.payroc.com/api/metadata) object you can use to include custom data with your request.

## Response `201`

Successful request. We accepted the instructions.

- Instruction — Inform the payfac what to do with the specified funds. **
  - `instructionId` integer — Unique identifier that we assigned to the funding instruction.
  - `createdDate` string, datetime — Date that we created the funding instruction. The date format follows the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard.
  - `lastModifiedDate` string, datetime — Date of the most recent change to the funding instruction. The date format follows the [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) standard.
  - `status` 'accepted' | 'pending' | 'completed' — 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.
  - `merchants` InstructionMerchantsItems[] — Array of merchants objects. Each object specifies the merchant whose funding balance we distribute and who you want to send the funds to.
    - `merchantId` string, required — Unique identifier that the processor assigned to the merchant.
    - `recipients` InstructionMerchantsItemsRecipientsItems[], required — Array of recipients objects. Each object contains information about the funding account and the amount of funds we send to the funding account.
      - `fundingAccountId` integer, required — Unique identifier that we assigned to the funding account.
      - `paymentMethod` 'ACH', required — Payment method that we use to send funds to the funding account.
      - `amount` InstructionMerchantsItemsRecipientsItemsAmount, required — Object that contains information about the funds that we send to the funding account.
        - `value` integer, required — Amount of funds in the currency's lowest denomination, for example, cents.
        - `currency` 'USD' — Currency of the value parameter.
      - `status` 'accepted' | 'pending' | 'released' | 'funded' | 'failed' | 'rejected' | 'onHold' — 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.
      - `metadata` object — [Metadata](https://docs.payroc.com/api/metadata) object you can use to include custom data with your request.
      - `link` InstructionMerchantsItemsRecipientsItemsLink — Object that contains HATEOAS links for the resource.
        - `rel` string — Indicates the relationship between the current resource and the target resource.
        - `method` string — HTTP method that you need to use with the target resource.
        - `href` string — URL of the target resource.
    - `link` InstructionMerchantsItemsLink — Object that contains HATEOAS links for the resource.
      - `rel` string — Indicates the relationship between the current resource and the target resource.
      - `method` string — HTTP method that you need to use with the target resource.
      - `href` string — URL of the target resource.
  - `metadata` object — [Metadata](https://docs.payroc.com/api/metadata) object you can use to include custom data with your request.

## Other responses

- `400` — Validation error.
- `401` — Identity could not be verified
- `403` — Do not have permissions to perform this action
- `406` — Not acceptable
- `409` — Conflict
- `500` — An error has occured

---

[API](https://skmtc.dev/payroc/apis/schema.md) · [All operations](https://skmtc.dev/payroc/apis/schema/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/payroc/schema/revisions/1d9d3e305945/schema)