Payouts

Create payouts

Creates 1 to 100 payouts in one call and groups them in a batch. Infinity validates every item, prices each payout at the current rate, reserves the total debit_amount in the wallet you name, and sends each payout whose payee is active.

Payee active: the payout starts as pending.
Payee not ready: the payout starts as awaiting_payee, with its funds reserved. It’s released at the daily release (09:00 IST) after the payee becomes active, and expires after the account’s hold_expiry_days.

The call is atomic: if any item is invalid, or the wallet’s available amount doesn’t cover the total, the request fails and no batch, payout or reservation is created. The response is the batch, with the payouts it created in payouts, in request order.

POST

payouts

Create payouts

curl --request POST \
  --url https://sandbox-api.infinityapp.in/v1/payouts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "wallet_id": "wallet_7t4m9k2qx8d3hn5r",
  "items": [
    {
      "payee_id": "payee_c8pnahcrxqzd3z8d",
      "amount": "500.00",
      "currency": "eur",
      "reference": "inv-1042",
      "metadata": {
        "invoice": "inv-1042"
      }
    }
  ],
  "name": "October invoices",
  "description": "Contractor invoices, October",
  "reference": "run-2026-10",
  "metadata": {
    "invoice": "inv-1042"
  }
}
'

{
  "id": "batch_fcb4cuwtd6fcbmwr",
  "number": "PB-2026-21",
  "name": "October invoices",
  "description": "October invoices",
  "status": "processing",
  "wallet_id": "wallet_7t4m9k2qx8d3hn5r",
  "debit_currency": "usd",
  "total_debit": "1136.70",
  "total_fee": "20.00",
  "payee_count": 2,
  "payout_summary": {
    "total": 2,
    "pending": 0,
    "processing": 1,
    "paid": 0,
    "failed": 0,
    "returned": 0,
    "awaiting_payee": 1,
    "awaiting_funds": 0,
    "canceled": 0,
    "expired": 0
  },
  "payouts": [
    {
      "id": "payout_4kz9xq7m2w8dn3ra",
      "batch_id": "batch_fcb4cuwtd6fcbmwr",
      "wallet_id": "wallet_7t4m9k2qx8d3hn5r",
      "payee_id": "payee_c8pnahcrxqzd3z8d",
      "amount": "500.00",
      "currency": "eur",
      "debit_amount": "568.35",
      "debit_currency": "usd",
      "fee": "10.00",
      "fee_bearer": "account",
      "rate": "0.8955",
      "payee_amount": "500.00",
      "payee_currency": "eur",
      "status": "pending",
      "failure_code": null,
      "failure_message": null,
      "hold_expires_at": null,
      "description": "October invoice",
      "reference": "inv-1042",
      "metadata": {
        "invoice": "inv-1042"
      },
      "created_at": "2026-10-26T10:05:00Z",
      "updated_at": "2026-10-26T10:05:00Z"
    }
  ],
  "reference": "run-2026-10",
  "metadata": {
    "invoice": "inv-1042"
  },
  "created_at": "2026-10-26T10:05:00Z",
  "updated_at": "2026-10-26T10:05:00Z"
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_payout_request",
    "message": "amount has more than 2 decimals for eur.",
    "param": "amount",
    "request_id": "req_4f4b2bjc4mamxuxm",
    "timestamp": "2026-10-29T10:00:00Z"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "wrong_environment",
    "message": "This is a live key. Use it on api.infinityapp.in.",
    "param": null,
    "request_id": "req_4f4b2bjc4mamxuxm",
    "timestamp": "2026-10-29T10:00:00Z"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_payout_request",
    "message": "amount has more than 2 decimals for eur.",
    "param": "amount",
    "request_id": "req_4f4b2bjc4mamxuxm",
    "timestamp": "2026-10-29T10:00:00Z"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_payout_request",
    "message": "amount has more than 2 decimals for eur.",
    "param": "amount",
    "request_id": "req_4f4b2bjc4mamxuxm",
    "timestamp": "2026-10-29T10:00:00Z"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_payout_request",
    "message": "amount has more than 2 decimals for eur.",
    "param": "amount",
    "request_id": "req_4f4b2bjc4mamxuxm",
    "timestamp": "2026-10-29T10:00:00Z"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_payout_request",
    "message": "amount has more than 2 decimals for eur.",
    "param": "amount",
    "request_id": "req_4f4b2bjc4mamxuxm",
    "timestamp": "2026-10-29T10:00:00Z"
  }
}

Authorizations

Authorization

string

header

required

Your secret key: sk_test_… on the sandbox host, sk_live_… on live. A key on the wrong host gets a 401 wrong_environment. Keys are secret. Keep them on your server, never in a browser or app.

Headers

Idempotency-Key

string

required

Any unique string up to 255 characters, such as a UUID or your own invoice id. Retrying with the same key and body within 24 hours returns the original response instead of paying twice.

Maximum string length: 255

Example:

"inv-1042-attempt-1"

Body

application/json

wallet_id

string

required

The wallet that pays. Its available amount must cover the total debit_amount.

Example:

"wallet_7t4m9k2qx8d3hn5r"

items

object[]

required

The payouts to create, one per payee.

Required array length: 1 - 100 elements

Show child attributes

name

string

The batch name shown on your dashboard. Defaults to API batch followed by the UTC date and time.

Maximum string length: 255

Example:

"October invoices"

description

string

Applied to every payout in the batch.

Maximum string length: 500

Example:

"Contractor invoices, October"

reference

string

Your identifier for the batch.

Maximum string length: 100

Example:

"run-2026-10"

metadata

object

Up to 20 key-value pairs of your own. Keys up to 40 characters, values up to 500, strings only.

Show child attributes

Example:

{ "invoice": "inv-1042" }

Response

The new batch and its payouts.

string

required

Example:

"batch_fcb4cuwtd6fcbmwr"

number

string

required

Your account's running count, as on the dashboard.

Example:

"PB-2026-21"

name

string

required

The name sent on creation, or API batch plus the UTC date and time.

Example:

"October invoices"

description

string | null

required

Example:

"October invoices"

status

enum<string>

required

Worked out from the batch's payouts, so it can move more than once.

Available options:

pending,

processing,

completed,

partially_completed,

failed,

awaiting_payees,

awaiting_funds,

canceled

Example:

"processing"

wallet_id

string

required

The wallet that paid.

Example:

"wallet_7t4m9k2qx8d3hn5r"

debit_currency

string

required

The currency of the paying wallet.

Example:

"usd"

total_debit

string

required

The sum of its payouts' debit_amount.

Example:

"1136.70"

total_fee

string | null

required

Example:

"20.00"

payee_count

integer

required

Example:

2

payout_summary

object

required

How many of the batch's payouts are in each status.

Show child attributes

payouts

object[]

required

The batch's payouts in request order.

Show child attributes

reference

string | null

required

Example:

"run-2026-10"

metadata

object

required

Up to 20 key-value pairs of your own. Keys up to 40 characters, values up to 500, strings only.

Show child attributes

Example:

{ "invoice": "inv-1042" }

created_at

string<date-time>

required

Example:

"2026-10-26T10:05:00Z"

updated_at

string<date-time>

required

Example:

"2026-10-26T10:05:00Z"

Create payouts

curl --request POST \
  --url https://sandbox-api.infinityapp.in/v1/payouts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "wallet_id": "wallet_7t4m9k2qx8d3hn5r",
  "items": [
    {
      "payee_id": "payee_c8pnahcrxqzd3z8d",
      "amount": "500.00",
      "currency": "eur",
      "reference": "inv-1042",
      "metadata": {
        "invoice": "inv-1042"
      }
    }
  ],
  "name": "October invoices",
  "description": "Contractor invoices, October",
  "reference": "run-2026-10",
  "metadata": {
    "invoice": "inv-1042"
  }
}
'

{
  "id": "batch_fcb4cuwtd6fcbmwr",
  "number": "PB-2026-21",
  "name": "October invoices",
  "description": "October invoices",
  "status": "processing",
  "wallet_id": "wallet_7t4m9k2qx8d3hn5r",
  "debit_currency": "usd",
  "total_debit": "1136.70",
  "total_fee": "20.00",
  "payee_count": 2,
  "payout_summary": {
    "total": 2,
    "pending": 0,
    "processing": 1,
    "paid": 0,
    "failed": 0,
    "returned": 0,
    "awaiting_payee": 1,
    "awaiting_funds": 0,
    "canceled": 0,
    "expired": 0
  },
  "payouts": [
    {
      "id": "payout_4kz9xq7m2w8dn3ra",
      "batch_id": "batch_fcb4cuwtd6fcbmwr",
      "wallet_id": "wallet_7t4m9k2qx8d3hn5r",
      "payee_id": "payee_c8pnahcrxqzd3z8d",
      "amount": "500.00",
      "currency": "eur",
      "debit_amount": "568.35",
      "debit_currency": "usd",
      "fee": "10.00",
      "fee_bearer": "account",
      "rate": "0.8955",
      "payee_amount": "500.00",
      "payee_currency": "eur",
      "status": "pending",
      "failure_code": null,
      "failure_message": null,
      "hold_expires_at": null,
      "description": "October invoice",
      "reference": "inv-1042",
      "metadata": {
        "invoice": "inv-1042"
      },
      "created_at": "2026-10-26T10:05:00Z",
      "updated_at": "2026-10-26T10:05:00Z"
    }
  ],
  "reference": "run-2026-10",
  "metadata": {
    "invoice": "inv-1042"
  },
  "created_at": "2026-10-26T10:05:00Z",
  "updated_at": "2026-10-26T10:05:00Z"
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_payout_request",
    "message": "amount has more than 2 decimals for eur.",
    "param": "amount",
    "request_id": "req_4f4b2bjc4mamxuxm",
    "timestamp": "2026-10-29T10:00:00Z"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "wrong_environment",
    "message": "This is a live key. Use it on api.infinityapp.in.",
    "param": null,
    "request_id": "req_4f4b2bjc4mamxuxm",
    "timestamp": "2026-10-29T10:00:00Z"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_payout_request",
    "message": "amount has more than 2 decimals for eur.",
    "param": "amount",
    "request_id": "req_4f4b2bjc4mamxuxm",
    "timestamp": "2026-10-29T10:00:00Z"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_payout_request",
    "message": "amount has more than 2 decimals for eur.",
    "param": "amount",
    "request_id": "req_4f4b2bjc4mamxuxm",
    "timestamp": "2026-10-29T10:00:00Z"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_payout_request",
    "message": "amount has more than 2 decimals for eur.",
    "param": "amount",
    "request_id": "req_4f4b2bjc4mamxuxm",
    "timestamp": "2026-10-29T10:00:00Z"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_payout_request",
    "message": "amount has more than 2 decimals for eur.",
    "param": "amount",
    "request_id": "req_4f4b2bjc4mamxuxm",
    "timestamp": "2026-10-29T10:00:00Z"
  }
}

Account

Wallets

Funding addresses

Deposits

Currencies

Exchange rates

Payees

Payee addresses

Bank requirements

Quotes

Payouts

Batches

Webhook endpoints

Events

API Reference

Create payouts

Authorizations

Headers

Body

Response