Create funding instruction | Payroc

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.

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.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.

merchantslist of objectsOptional

Array of merchants objects. Each object specifies the merchant whose funding balance we distribute and who you want to send the funds to.

metadatamap from strings to stringsOptional

Metadata object you can use to include custom data with your request.

Response headers

locationstring

URI reference to created resource.

Response

Successful request. We accepted the instructions.

instructionIdintegerRead-only

Unique identifier that we assigned to the funding instruction.

createdDatestringRead-onlyformat: "datetime"

Date that we created the funding instruction. The date format follows the ISO 8601 standard.

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.

lastModifiedDatestringRead-onlyformat: "datetime"

Date of the most recent change to the funding instruction. The date format follows the ISO 8601 standard.

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.

statusenumRead-only

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.

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.

Allowed values:

merchantslist of objects

Array of merchants objects. Each object specifies the merchant whose funding balance we distribute and who you want to send the funds to.

metadatamap from strings to strings

Metadata object you can use to include custom data with your request.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

406

Not Acceptable Error

409

Conflict Error

500

Internal Server Error

1	using Payroc;
2	using System.Threading.Tasks;
3	using Payroc.Funding.FundingInstructions;
4	using System.Collections.Generic;
5
6	namespace Usage;
7
8	public class Example
9	{
10	public async Task Do() {
11	var client = new PayrocClient();
12
13	await client.Funding.FundingInstructions.CreateAsync(
14	new CreateFundingInstructionsRequest {
15	IdempotencyKey = "8e03978e-40d5-43e8-bc93-6894a57f9324",
16	Body = new Instruction {
17	Merchants = new List<InstructionMerchantsItem>(){
18	new InstructionMerchantsItem {
19	MerchantId = "4525644354",
20	Recipients = new List<InstructionMerchantsItemRecipientsItem>(){
21	new InstructionMerchantsItemRecipientsItem {
22	FundingAccountId = 123,
23	PaymentMethod = InstructionMerchantsItemRecipientsItemPaymentMethod.Ach,
24	Amount = new InstructionMerchantsItemRecipientsItemAmount {
25	Value = 120000,
26	Currency = InstructionMerchantsItemRecipientsItemAmountCurrency.Usd
27	},
28	Metadata = new Dictionary<string, string>(){
29	["yourCustomField"] = "abc123",
30	}
31
32	},
33	}
34
35	},
36	}
37	,
38	Metadata = new Dictionary<string, string>(){
39	["yourCustomField"] = "abc123",
40	}
41
42	}
43	}
44	);
45	}
46
47	}

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/processing-accounts/4525644354"
32	}
33	}
34	],
35	"metadata": {
36	"instructionRef": "abc123"
37	}
38	}

Authentication

Headers

Request

Response headers

Response

Errors