Create payments

Create a Roots payment instruction from an eligible account to an eligible counterparty or other permitted destination.

See API versions and Beta status before using this workflow for production money movement.

Before you begin

• Confirm that the source account is eligible for the intended activity.
• Confirm that the destination counterparty is active.
• Check the account's available balance.
• Store an external_id that uniquely identifies the payment in your system.

Create a payment

Create a payment with POST /frontoffice/payments. The API derives the payment type and rail from the source and destination objects.

For an account or counterparty, provide its Roots ID.

{
  "kind": "account",
  "id": "account_123"
}

Create a withdrawal from an account to a counterparty:

{
  "external_id": "payout_20260803_001",
  "source": {
    "kind": "account",
    "id": "account_123"
  },
  "destination": {
    "kind": "counterparty",
    "id": "counterparty_123"
  },
  "amount": 1250.5,
  "purpose": "supplier_payment",
  "description": "August inventory payment"
}

Handle invalid instructions

The endpoint returns 400 when the source and destination form an invalid pair. Validate the selected source and destination in your application before creating the instruction, and surface the error without automatically retrying the same invalid payload.

A payment response is the start of a lifecycle, not confirmation that funds were delivered. See Track payment status after creating an instruction.

Next steps

• Manage accounts for source-account controls.
• Manage counterparties for destination screening.
• Track payment status to reconcile the payment outcome.