# Send funds to your merchants

Send funds to your merchants by creating a Funding Instruction with a POST request to the Funding Instructions endpoint, optionally checking available balance first via GET /v1/funding-balance.

**Prerequisites:** [Authentication](/api/authentication)

**Important:** Before you begin, make sure that you have read our [Getting Started](/guides/getting-started "Getting started") guide, and that you have received your API key.

To send funds to your merchants, you need to provide us with instructions about:

- Funding accounts that we should send the funds to
- Amount of funds that we should send

Before you create your funding instructions, we recommend that you check to make sure you have the funds available to send.

<a id="integration-steps"></a>
## Integration steps

**Step 1.**	(Optional) Check the available balance.  
**Step 2.**	Create a funding instruction.

<a id="before-you-begin"></a>
## Before you begin

[Authenticate your requests](/api/authentication) before making API calls. If your request fails, see [Errors](/api/errors).

<a id="step-1-optional-check-the-available-balance"></a>
## Step 1. (Optional) Check the available balance

To check the available balance, you need to send a GET request to our Funding Balance endpoint.

| Environment | URL |
| --- | --- |
| Test | [https://api.uat.payroc.com/v1/funding-balance](https://api.uat.payroc.com/v1/funding-balance) |
| Production | [https://api.payroc.com/v1/funding-balance](https://api.payroc.com/v1/funding-balance) |

<a id="schema-requestquery"></a>
### Schema (`request.query`)

[Query parameters for `GET /funding-balance`](/api/get-funding-balance)

<a id="example-request"></a>
### Example request

<a id="request"></a>
### Request

GET [https://api.payroc.com/v1/funding-balance](https://api.payroc.com/v1/funding-balance)

**`Paginated list of merchant balances`**

```curl
curl -G https://api.payroc.com/v1/funding-balance \
     -H "Authorization: Bearer <token>" \
     -d after=8516 \
     -d before=2571 \
     -d limit=25 \
     -d merchantId=4525644354
```

**`Paginated list of merchant balances`**

```python
import requests

url = "https://api.payroc.com/v1/funding-balance"

querystring = {"after":"8516","before":"2571","limit":"25","merchantId":"4525644354"}

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
```

**`Paginated list of merchant balances`**

```javascript
const url = 'https://api.payroc.com/v1/funding-balance?after=8516&before=2571&limit=25&merchantId=4525644354';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

**`Paginated list of merchant balances`**

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.payroc.com/v1/funding-balance?after=8516&before=2571&limit=25&merchantId=4525644354"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

**`Paginated list of merchant balances`**

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.payroc.com/v1/funding-balance?after=8516&before=2571&limit=25&merchantId=4525644354")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

**`Paginated list of merchant balances`**

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.payroc.com/v1/funding-balance?after=8516&before=2571&limit=25&merchantId=4525644354")
  .header("Authorization", "Bearer <token>")
  .asString();
```

**`Paginated list of merchant balances`**

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.payroc.com/v1/funding-balance?after=8516&before=2571&limit=25&merchantId=4525644354', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();
```

**`Paginated list of merchant balances`**

```csharp
using RestSharp;

var client = new RestClient("https://api.payroc.com/v1/funding-balance?after=8516&before=2571&limit=25&merchantId=4525644354");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

**`Paginated list of merchant balances`**

```swift
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.payroc.com/v1/funding-balance?after=8516&before=2571&limit=25&merchantId=4525644354")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

If your request is successful, we return a response that contains the funds available for your merchant. The response contains the following fields:

<a id="schema-responsebody"></a>
### Schema (`response.body`)

[Response body schema for `GET /funding-balance`](/api/get-funding-balance)

<a id="example-response"></a>
### Example response

<a id="response-200"></a>
### Response (200)

```json
{
  "data": [
    {
      "merchantId": "4525644354",
      "funds": 120000,
      "pending": 50050,
      "available": 69950,
      "currency": "USD"
    },
    {
      "merchantId": "9876543219",
      "funds": 50000,
      "pending": 0,
      "available": 50000,
      "currency": "USD"
    }
  ],
  "limit": 2,
  "count": 2,
  "hasMore": true,
  "links": [
    {
      "rel": "previous",
      "method": "get",
      "href": "https://api.payroc.com/v1/funding-balance?before=4525644354&limit=2"
    },
    {
      "rel": "next",
      "method": "get",
      "href": "https://api.payroc.com/v1/funding-balance?after=9876543219&limit=2"
    }
  ]
}
```

<a id="step-2-create-a-funding-instruction"></a>
## Step 2. Create a funding instruction

**Note:** You can use a funding instruction to send funds to a single merchant or to multiple merchants in a single request.

To create your funding instruction, send a POST request to our Funding Instructions endpoint.

| Environment | URL |
| --- | --- |
| Test | [https://api.uat.payroc.com/v1/funding-instructions](https://api.uat.payroc.com/v1/funding-instructions) |
| Production | [https://api.payroc.com/v1/funding-instructions](https://api.payroc.com/v1/funding-instructions) |

To create the body of your request, use the following parameters:

<a id="schema-requestbody"></a>
### Schema (`request.body`)

[Request body schema for `POST /funding-instructions`](/api/create-instruction)

**Note:** Use our [metadata](/api/metadata "Metadata") feature to add custom information to your request.

<a id="example-request-1"></a>
### Example request

<a id="request-1"></a>
### Request

POST [https://api.payroc.com/v1/funding-instructions](https://api.payroc.com/v1/funding-instructions)

**`Funding instruction`**

```curl
curl -X POST https://api.payroc.com/v1/funding-instructions \
     -H "Idempotency-Key: 8e03978e-40d5-43e8-bc93-6894a57f9324" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "merchants": [
    {
      "merchantId": "4525644354",
      "recipients": [
        {
          "fundingAccountId": 123,
          "paymentMethod": "ACH",
          "amount": {
            "value": 120000,
            "currency": "USD"
          },
          "metadata": {
            "yourCustomField": "abc123"
          }
        }
      ]
    }
  ],
  "metadata": {
    "yourCustomField": "abc123"
  }
}'
```

**`Funding instruction`**

```python
import requests

url = "https://api.payroc.com/v1/funding-instructions"

payload = {
    "merchants": [
        {
            "merchantId": "4525644354",
            "recipients": [
                {
                    "fundingAccountId": 123,
                    "paymentMethod": "ACH",
                    "amount": {
                        "value": 120000,
                        "currency": "USD"
                    },
                    "metadata": { "yourCustomField": "abc123" }
                }
            ]
        }
    ],
    "metadata": { "yourCustomField": "abc123" }
}
headers = {
    "Idempotency-Key": "8e03978e-40d5-43e8-bc93-6894a57f9324",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

**`Funding instruction`**

```javascript
const url = 'https://api.payroc.com/v1/funding-instructions';
const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '8e03978e-40d5-43e8-bc93-6894a57f9324',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"merchants":[{"merchantId":"4525644354","recipients":[{"fundingAccountId":123,"paymentMethod":"ACH","amount":{"value":120000,"currency":"USD"},"metadata":{"yourCustomField":"abc123"}}]}],"metadata":{"yourCustomField":"abc123"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

**`Funding instruction`**

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.payroc.com/v1/funding-instructions"

	payload := strings.NewReader("{\n  \"merchants\": [\n    {\n      \"merchantId\": \"4525644354\",\n      \"recipients\": [\n        {\n          \"fundingAccountId\": 123,\n          \"paymentMethod\": \"ACH\",\n          \"amount\": {\n            \"value\": 120000,\n            \"currency\": \"USD\"\n          },\n          \"metadata\": {\n            \"yourCustomField\": \"abc123\"\n          }\n        }\n      ]\n    }\n  ],\n  \"metadata\": {\n    \"yourCustomField\": \"abc123\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "8e03978e-40d5-43e8-bc93-6894a57f9324")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

**`Funding instruction`**

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.payroc.com/v1/funding-instructions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '8e03978e-40d5-43e8-bc93-6894a57f9324'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"merchants\": [\n    {\n      \"merchantId\": \"4525644354\",\n      \"recipients\": [\n        {\n          \"fundingAccountId\": 123,\n          \"paymentMethod\": \"ACH\",\n          \"amount\": {\n            \"value\": 120000,\n            \"currency\": \"USD\"\n          },\n          \"metadata\": {\n            \"yourCustomField\": \"abc123\"\n          }\n        }\n      ]\n    }\n  ],\n  \"metadata\": {\n    \"yourCustomField\": \"abc123\"\n  }\n}"

response = http.request(request)
puts response.read_body
```

**`Funding instruction`**

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.payroc.com/v1/funding-instructions")
  .header("Idempotency-Key", "8e03978e-40d5-43e8-bc93-6894a57f9324")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"merchants\": [\n    {\n      \"merchantId\": \"4525644354\",\n      \"recipients\": [\n        {\n          \"fundingAccountId\": 123,\n          \"paymentMethod\": \"ACH\",\n          \"amount\": {\n            \"value\": 120000,\n            \"currency\": \"USD\"\n          },\n          \"metadata\": {\n            \"yourCustomField\": \"abc123\"\n          }\n        }\n      ]\n    }\n  ],\n  \"metadata\": {\n    \"yourCustomField\": \"abc123\"\n  }\n}")
  .asString();
```

**`Funding instruction`**

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.payroc.com/v1/funding-instructions', [
  'body' => '{
  "merchants": [
    {
      "merchantId": "4525644354",
      "recipients": [
        {
          "fundingAccountId": 123,
          "paymentMethod": "ACH",
          "amount": {
            "value": 120000,
            "currency": "USD"
          },
          "metadata": {
            "yourCustomField": "abc123"
          }
        }
      ]
    }
  ],
  "metadata": {
    "yourCustomField": "abc123"
  }
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
    'Idempotency-Key' => '8e03978e-40d5-43e8-bc93-6894a57f9324',
  ],
]);

echo $response->getBody();
```

**`Funding instruction`**

```csharp
using RestSharp;

var client = new RestClient("https://api.payroc.com/v1/funding-instructions");
var request = new RestRequest(Method.POST);
request.AddHeader("Idempotency-Key", "8e03978e-40d5-43e8-bc93-6894a57f9324");
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"merchants\": [\n    {\n      \"merchantId\": \"4525644354\",\n      \"recipients\": [\n        {\n          \"fundingAccountId\": 123,\n          \"paymentMethod\": \"ACH\",\n          \"amount\": {\n            \"value\": 120000,\n            \"currency\": \"USD\"\n          },\n          \"metadata\": {\n            \"yourCustomField\": \"abc123\"\n          }\n        }\n      ]\n    }\n  ],\n  \"metadata\": {\n    \"yourCustomField\": \"abc123\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

**`Funding instruction`**

```swift
import Foundation

let headers = [
  "Idempotency-Key": "8e03978e-40d5-43e8-bc93-6894a57f9324",
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "merchants": [
    [
      "merchantId": "4525644354",
      "recipients": [
        [
          "fundingAccountId": 123,
          "paymentMethod": "ACH",
          "amount": [
            "value": 120000,
            "currency": "USD"
          ],
          "metadata": ["yourCustomField": "abc123"]
        ]
      ]
    ]
  ],
  "metadata": ["yourCustomField": "abc123"]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.payroc.com/v1/funding-instructions")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

If your request is successful, we create the funding instruction and return a response. The response contains the following fields:

<a id="schema-responsebody-1"></a>
### Schema (`response.body`)

[Response body schema for `POST /funding-instructions`](/api/create-instruction)

<a id="example-response-1"></a>
### Example response

<a id="response-201"></a>
### Response (201)

```json
{
  "instructionId": 64643131,
  "createdDate": "2024-07-02T15:30:00Z",
  "lastModifiedDate": "2024-07-02T15:30:00Z",
  "status": "accepted",
  "merchants": [
    {
      "merchantId": "4525644354",
      "recipients": [
        {
          "fundingAccountId": 123,
          "paymentMethod": "ACH",
          "amount": {
            "value": 120000,
            "currency": "USD"
          },
          "status": "accepted",
          "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/processing-accounts/4525644354"
      }
    }
  ],
  "metadata": {
    "yourCustomField": "abc123"
  }
}
```

<a id="test-cases"></a>
## Test cases

Our integration team provides you with [test cases](/guides/testing) that you can run to verify that your integration works with our API.

For your next steps, we recommend that you integrate with the other functions so you can manage your funding instructions. To view the other functions, see [funding instructions](/api/resources/funding-instructions).