Create a Payout Batch

Create a batch of payouts to multiple users. Each payout in the batch is processed independently with its own idempotency key. The batch itself can also have an idempotency key to prevent duplicate batch submissions. All payouts in a batch must have fund=true.

POST /v2/payout-batches

Create a Payout Batch

cURL

curl --request POST \
  --url https://api.dots.dev/api/v2/payout-batches \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "items": [
    {
      "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
      "amount": 1000,
      "platform": "paypal",
      "idempotency_key": "b2c3d4e5-f6g7-h8i9-j0k1-l2m3n4o5p6q7",
      "fund": true,
      "tax_exempt": false,
      "metadata": {
        "invoice_id": "INV-123"
      }
    },
    {
      "user_id": "b269451c-9625-5452-c9db-171ee559b2b6",
      "amount": 2500,
      "platform": "ach",
      "account_id": "c369451c-a725-6552-d0ec-272ff669c3c7",
      "idempotency_key": "c3d4e5f6-g7h8-i9j0-k1l2-m3n4o5p6q7r8",
      "fund": true,
      "tax_exempt": false
    }
  ],
  "metadata": {
    "batch_type": "weekly_payouts",
    "week": "2024-01"
  }
}
'

import requests

url = "https://api.dots.dev/api/v2/payout-batches"

payload = {
    "items": [
        {
            "user_id": "a169451c-8525-4352-b8ca-070dd449a1a5",
            "amount": 1000,
            "platform": "paypal",
            "idempotency_key": "b2c3d4e5-f6g7-h8i9-j0k1-l2m3n4o5p6q7",
            "fund": True,
            "tax_exempt": False,
            "metadata": { "invoice_id": "INV-123" }
        },
        {
            "user_id": "b269451c-9625-5452-c9db-171ee559b2b6",
            "amount": 2500,
            "platform": "ach",
            "account_id": "c369451c-a725-6552-d0ec-272ff669c3c7",
            "idempotency_key": "c3d4e5f6-g7h8-i9j0-k1l2-m3n4o5p6q7r8",
            "fund": True,
            "tax_exempt": False
        }
    ],
    "metadata": {
        "batch_type": "weekly_payouts",
        "week": "2024-01"
    }
}
headers = {
    "Authorization": "Basic <encoded-value>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    items: [
      {
        user_id: 'a169451c-8525-4352-b8ca-070dd449a1a5',
        amount: 1000,
        platform: 'paypal',
        idempotency_key: 'b2c3d4e5-f6g7-h8i9-j0k1-l2m3n4o5p6q7',
        fund: true,
        tax_exempt: false,
        metadata: {invoice_id: 'INV-123'}
      },
      {
        user_id: 'b269451c-9625-5452-c9db-171ee559b2b6',
        amount: 2500,
        platform: 'ach',
        account_id: 'c369451c-a725-6552-d0ec-272ff669c3c7',
        idempotency_key: 'c3d4e5f6-g7h8-i9j0-k1l2-m3n4o5p6q7r8',
        fund: true,
        tax_exempt: false
      }
    ],
    metadata: {batch_type: 'weekly_payouts', week: '2024-01'}
  })
};

fetch('https://api.dots.dev/api/v2/payout-batches', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.dots.dev/api/v2/payout-batches",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'items' => [
        [
                'user_id' => 'a169451c-8525-4352-b8ca-070dd449a1a5',
                'amount' => 1000,
                'platform' => 'paypal',
                'idempotency_key' => 'b2c3d4e5-f6g7-h8i9-j0k1-l2m3n4o5p6q7',
                'fund' => true,
                'tax_exempt' => false,
                'metadata' => [
                                'invoice_id' => 'INV-123'
                ]
        ],
        [
                'user_id' => 'b269451c-9625-5452-c9db-171ee559b2b6',
                'amount' => 2500,
                'platform' => 'ach',
                'account_id' => 'c369451c-a725-6552-d0ec-272ff669c3c7',
                'idempotency_key' => 'c3d4e5f6-g7h8-i9j0-k1l2-m3n4o5p6q7r8',
                'fund' => true,
                'tax_exempt' => false
        ]
    ],
    'metadata' => [
        'batch_type' => 'weekly_payouts',
        'week' => '2024-01'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Basic <encoded-value>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

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

func main() {

	url := "https://api.dots.dev/api/v2/payout-batches"

	payload := strings.NewReader("{\n  \"items\": [\n    {\n      \"user_id\": \"a169451c-8525-4352-b8ca-070dd449a1a5\",\n      \"amount\": 1000,\n      \"platform\": \"paypal\",\n      \"idempotency_key\": \"b2c3d4e5-f6g7-h8i9-j0k1-l2m3n4o5p6q7\",\n      \"fund\": true,\n      \"tax_exempt\": false,\n      \"metadata\": {\n        \"invoice_id\": \"INV-123\"\n      }\n    },\n    {\n      \"user_id\": \"b269451c-9625-5452-c9db-171ee559b2b6\",\n      \"amount\": 2500,\n      \"platform\": \"ach\",\n      \"account_id\": \"c369451c-a725-6552-d0ec-272ff669c3c7\",\n      \"idempotency_key\": \"c3d4e5f6-g7h8-i9j0-k1l2-m3n4o5p6q7r8\",\n      \"fund\": true,\n      \"tax_exempt\": false\n    }\n  ],\n  \"metadata\": {\n    \"batch_type\": \"weekly_payouts\",\n    \"week\": \"2024-01\"\n  }\n}")

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

	req.Header.Add("Authorization", "Basic <encoded-value>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.dots.dev/api/v2/payout-batches")
  .header("Authorization", "Basic <encoded-value>")
  .header("Content-Type", "application/json")
  .body("{\n  \"items\": [\n    {\n      \"user_id\": \"a169451c-8525-4352-b8ca-070dd449a1a5\",\n      \"amount\": 1000,\n      \"platform\": \"paypal\",\n      \"idempotency_key\": \"b2c3d4e5-f6g7-h8i9-j0k1-l2m3n4o5p6q7\",\n      \"fund\": true,\n      \"tax_exempt\": false,\n      \"metadata\": {\n        \"invoice_id\": \"INV-123\"\n      }\n    },\n    {\n      \"user_id\": \"b269451c-9625-5452-c9db-171ee559b2b6\",\n      \"amount\": 2500,\n      \"platform\": \"ach\",\n      \"account_id\": \"c369451c-a725-6552-d0ec-272ff669c3c7\",\n      \"idempotency_key\": \"c3d4e5f6-g7h8-i9j0-k1l2-m3n4o5p6q7r8\",\n      \"fund\": true,\n      \"tax_exempt\": false\n    }\n  ],\n  \"metadata\": {\n    \"batch_type\": \"weekly_payouts\",\n    \"week\": \"2024-01\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.dots.dev/api/v2/payout-batches")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"items\": [\n    {\n      \"user_id\": \"a169451c-8525-4352-b8ca-070dd449a1a5\",\n      \"amount\": 1000,\n      \"platform\": \"paypal\",\n      \"idempotency_key\": \"b2c3d4e5-f6g7-h8i9-j0k1-l2m3n4o5p6q7\",\n      \"fund\": true,\n      \"tax_exempt\": false,\n      \"metadata\": {\n        \"invoice_id\": \"INV-123\"\n      }\n    },\n    {\n      \"user_id\": \"b269451c-9625-5452-c9db-171ee559b2b6\",\n      \"amount\": 2500,\n      \"platform\": \"ach\",\n      \"account_id\": \"c369451c-a725-6552-d0ec-272ff669c3c7\",\n      \"idempotency_key\": \"c3d4e5f6-g7h8-i9j0-k1l2-m3n4o5p6q7r8\",\n      \"fund\": true,\n      \"tax_exempt\": false\n    }\n  ],\n  \"metadata\": {\n    \"batch_type\": \"weekly_payouts\",\n    \"week\": \"2024-01\"\n  }\n}"

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

200

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "created": "2023-11-07T05:31:56Z",
  "idempotency_key": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "metadata": "<string>"
}

Authorizations

Authorization · string · header · required

Basic authentication header of the form Basic <encoded-value>, where <encoded-value> is the base64-encoded string username:password.

Body

application/json

Request to create a batch of payouts

items · payout-batch-request-item · object[] · required

List of individual payouts to create in the batch.

Required array length: 1 - 5000 elements

Show child attributes

idempotency_key · string<uuid>

UUID that will be used to idempotently handle the batch request. Batches with existing idempotency keys will be rejected.

metadata · string object

Set of key-value pairs that you can attach to the batch. This can be useful for storing additional information about the batch in a structured format.

Response

200 - application/json

OK

The created payout batch.

id · string<uuid> · required

Unique identifier for the payout batch.

created · string<date-time> · required

Timestamp when the batch was created.

status · enum<string> · required

Current status of the batch processing.

Available options: created, processing, paying_out, completed

idempotency_key · string<uuid>

The idempotency key provided when creating the batch.

metadata · string object

The metadata attached to the batch.