GuidesAPI ReferenceChangelog
API Reference

Payouts Guide

Send funds to bank accounts, crypto wallets, and 1Money accounts, with optional currency conversion and locked quotes.

1. Overview

Use Payouts v2 to send funds to a bank account, a crypto address, or another 1Money account. You can pay in the same currency or convert funds as part of the payment.

Choose the flow that fits your experience:

  • Standard Payout: send funds in the same currency.

  • Convert & Pay: fund a payment in one currency and deliver another, in one request.

  • Quote & Pay: lock in the payment fees, rates and amounts, review the quote, then submit the payout after confirmation.

2. Define your payment

Every direct payout describes who funds the payment, where it goes, and what amount to send:

  • from_account: the 1Money account whose balance funds the payout.

  • to_account: the destination. Use a 1Money account ID for an internal transfer, a blockchain address for a crypto payout, or a registered bank account ID for a fiat payout.

  • network: the payment rail used to deliver the funds.

  • source: the asset and amount debited from the funding account.

  • destination: the asset and amount the recipient receives.

Choose the amount to fix — Choose whether to fix the amount debited from the funding account or the amount the recipient receives. Supply exactly one amount:

  • Fix the debit: set source.amount. The API calculates how much the recipient receives after fees and any conversion.

  • Fix the receipt: set destination.amount. The API calculates the required debit, including fees and any conversion.

Example — request a USD 100 debit

POST /v2/payouts
{
  "source": {
    "asset": "USD",
    "amount": "100"
  },
  "destination": {
    "asset": "USD"
  }
}

Example — request a USD 100 receipt

POST /v2/payouts
{
  "source": {
    "asset": "USD"
  },
  "destination": {
    "asset": "USD",
    "amount": "100"
  }
}

3. Standard Payout

Send funds in the same currency.

Set the same asset in source and destination, and submit the payment using Create Payout (POST /v2/payouts).

3.1 Internal Transfer

Send funds to another 1Money account by setting network to 1MONEY_TRANSFER and placing the receiving account's ID in to_account.account_identifier.

Internal transfers are instant and have no withdrawal fees.

Example — send 100 USD

POST /v2/payouts
{
  "external_id": "PARTNER_TX_ID_0123",
  "source": {
    "asset": "USD",
    "amount": "100"
  },
  "destination": {
    "asset": "USD"
  },
  "network": "1MONEY_TRANSFER",
  "from_account": "BZ-7Q2K-M9XD",
  "to_account": {
    "account_identifier": "BZ-8W4N-6T3P"
  }
}
POST /v2/payouts
{
  "id": "PO-7Q2K-M9XD",
  "status": "SENT",
  "external_id": "PARTNER_TX_ID_0123",
  "purpose": null,
  "network": "1MONEY_TRANSFER",
  "quote_id": null,
  "source": {
    "asset": "USD",
    "amount": "100.00"
  },
  "destination": {
    "asset": "USD",
    "amount": "100.00"
  },
  "from_account": "BZ-7Q2K-M9XD",
  "to_account": {
    "account_identifier": "BZ-8W4N-6T3P",
    "recipient": {
      "name": "Example Destination LLC",
      "type": "BUSINESS"
    }
  },
  "on_behalf_of_account": null,
  "conversion": null,
  "withdrawal": {
    "id": "550e8400-e29b-41d4-a716-446655440101",
    "asset": "USD",
    "amount": {
      "gross": "100.00",
      "net": "100.00"
    },
    "fees": null,
    "memo": null,
    "tracking_number": null,
    "status": "SENT",
    "status_info": null
  },
  "created_at": "2026-11-12T12:00:00Z",
  "updated_at": "2026-11-12T12:00:05Z"​
}

conversion: null means no conversion was needed. withdrawal.fees: null means there are no withdrawal fees.

3.2 Crypto Payouts

Send funds to a blockchain address by specifying the asset, amount, receiving address, and network.

Example — recipient gets 100 USDC

POST /v2/payouts
{
  "external_id": "PARTNER_TX_ID_0123",
  "source": {
    "asset": "USDC"
  },
  "destination": {
    "asset": "USDC",
    "amount": "100"
  },
  "network": "BASE",
  "from_account": "BZ-7Q2K-M9XD",
  "to_account": {
    "account_identifier": "0x1234567890AbcdEF1234567890aBcdef12345678"
  }
}
POST /v2/payouts
{
  "id": "PO-8W4N-6T3P",
  "status": "PROCESSING",
  "external_id": "PARTNER_TX_ID_0123",
  "purpose": null,
  "network": "BASE",
  "quote_id": null,
  "source": {
    "asset": "USDC",
    "amount": "101.000000"
  },
  "destination": {
    "asset": "USDC",
    "amount": "100.000000"
  },
  "from_account": "BZ-7Q2K-M9XD",
  "to_account": {
    "account_identifier": "0x1234567890AbcdEF1234567890aBcdef12345678"
  },
  "on_behalf_of_account": null,
  "conversion": null,
  "withdrawal": {
    "id": "550e8400-e29b-41d4-a716-446655440102",
    "asset": "USDC",
    "amount": {
      "gross": "101.000000",
      "net": "100.000000"
    },
    "fees": {
      "platform": {
        "asset": "USDC",
        "amount": "0.750000"
      },
      "partner": {
        "asset": "USDC",
        "amount": "0.250000"
      }
    },
    "memo": null,
    "tracking_number": null,
    "status": "PROCESSING",
    "status_info": null
  },
  "created_at": "2026-11-12T12:00:00Z",
  "updated_at": "2026-11-12T12:00:00Z"
}

In this example, the account is debited 101 USDC so the recipient receives 100 USDC after a 1 USDC withdrawal fee. To fix the amount the debited instead, put the amount in source.amount and omit destination.amount.

3.3 FIAT Payouts

Send funds to a registered bank account. Specify the funding account, the registered bank account ID in to_account.account_identifier, and the asset and amount.

Example — send 100 USD

POST /v2/payouts
{
  "external_id": "PARTNER_TX_ID_0123",
  "memo": "Invoice 1001",
  "purpose": "TREASURY_TRANSFER",
  "source": {
    "asset": "USD",
    "amount": "100"
  },
  "destination": {
    "asset": "USD"
  },
  "from_account": "BZ-7Q2K-M9XD",
  "to_account": {
    "account_identifier": "550e8400-e29b-41d4-a716-446655440000"
  }
}
POST /v2/payouts
{
  "id": "PO-9R3K-8V2D",
  "status": "PROCESSING",
  "external_id": "PARTNER_TX_ID_0123",
  "purpose": "TREASURY_TRANSFER",
  "network": "ACH",
  "quote_id": null,
  "source": {
    "asset": "USD",
    "amount": "100.00"
  },
  "destination": {
    "asset": "USD",
    "amount": "99.45"
  },
  "from_account": "BZ-7Q2K-M9XD",
  "to_account": {
    "account_identifier": "550e8400-e29b-41d4-a716-446655440000",
    "account_number": "000123456789",
    "institution": {
      "identifier": "021000021",
      "name": "Example Bank",
      "address": {
        "country": "US"
      }
    },
    "recipient": {
      "id": "550e8400-e29b-41d4-a716-446655440003",
      "name": "Example Supplier LLC",
      "type": "BUSINESS",
      "first_party": false
    }
  },
  "on_behalf_of_account": null,
  "conversion": null,
  "withdrawal": {
    "id": "550e8400-e29b-41d4-a716-446655440103",
    "asset": "USD",
    "amount": {
      "gross": "100.00",
      "net": "99.45"
    },
    "fees": {
      "platform": {
        "asset": "USD",
        "amount": "0.35"
      },
      "partner": {
        "asset": "USD",
        "amount": "0.20"
      }
    },
    "memo": "Invoice 1001",
    "tracking_number": null,
    "status": "PROCESSING",
    "status_info": null
  },
  "created_at": "2026-11-12T12:00:00Z",
  "updated_at": "2026-11-12T12:00:00Z"
}

Some bank networks and destination countries require a supported purpose code when submitting a payout. See Payout Purposes for supported values. Include it at the request root when required; the API returns a field error if it is missing or invalid for the route.

Registering a bank destination

  • First-party flow: register the customer's own bank account with Create External Account at POST /v1/customers/{customer_id}/external-accounts. Once it is eligible for use, pass the returned external_account_id as to_account.account_identifier.

  • Third-party flow: use Create Recipient, then Add Bank Account to Recipient at POST /v1/customers/{customer_id}/recipients/{recipient_id}/bank_accounts. Once it is eligible for use, pass the returned bank account's external_account_id as to_account.account_identifier.

4. Convert & Pay

Fund a payment in one currency and deliver another.

Use Create Payout (POST /v2/payouts) with different source.asset and destination.asset values. 1Money creates and executes the conversion quote as part of the request.

Example — fund with 100 USDC, deliver in USD

POST /v2/payouts
{
  "external_id": "PARTNER_TX_ID_0123",
  "source": {
    "asset": "USDC",
    "amount": "100"
  },
  "destination": {
    "asset": "USD"
  },
  "from_account": "BZ-7Q2K-M9XD",
  "to_account": {
    "account_identifier": "550e8400-e29b-41d4-a716-446655440000"
  }
}
POST /v2/payouts
{
  "id": "PO-6T3P-7Q2K",
  "status": "PROCESSING",
  "external_id": "PARTNER_TX_ID_0123",
  "purpose": null,
  "network": "ACH",
  "quote_id": "PQ-6T3P-7Q2K",
  "source": {
    "asset": "USDC",
    "amount": "100.000000"
  },
  "destination": {
    "asset": "USD",
    "amount": "99.25"
  },
  "from_account": "BZ-7Q2K-M9XD",
  "to_account": {
    "account_identifier": "550e8400-e29b-41d4-a716-446655440000",
    "account_number": "000123456789",
    "institution": {
      "identifier": "021000021",
      "name": "Example Bank",
      "address": {
        "country": "US"
      }
    },
    "recipient": {
      "id": "550e8400-e29b-41d4-a716-446655440003",
      "name": "Example Supplier LLC",
      "type": "BUSINESS",
      "first_party": false
    }
  },
  "on_behalf_of_account": null,
  "conversion": {
    "id": "550e8400-e29b-41d4-a716-446655440002",
    "rate": "0.999",
    "from": {
      "asset": "USDC",
      "amount": "100.000000"
    },
    "to": {
      "asset": "USD",
      "amount": "99.80"
    },
    "fees": {
      "platform": {
        "asset": "USD",
        "amount": "0.10"
      }
    },
    "spread": {
      "platform": null,
      "partner": {
        "asset": "USDC",
        "amount": "0.100000"
      }
    },
    "status": "PROCESSING",
    "status_info": null
  },
  "withdrawal": {
    "id": "550e8400-e29b-41d4-a716-446655440104",
    "asset": "USD",
    "amount": {
      "gross": "99.80",
      "net": "99.25"
    },
    "fees": {
      "platform": {
        "asset": "USD",
        "amount": "0.35"
      },
      "partner": {
        "asset": "USD",
        "amount": "0.20"
      }
    },
    "memo": null,
    "tracking_number": null,
    "status": "CREATED",
    "status_info": null
  },
  "created_at": "2026-11-12T12:00:00Z",
  "updated_at": "2026-11-12T12:00:00Z"
}

The response shows the payment from start to finish:

  • source: the total debit of 100 USDC.

  • conversion: 100 USDC converts to USD 99.80 at the illustrated rate of 0.998.

  • withdrawal: a USD 0.55 fee leaves USD 99.25 to send.

  • destination: the final amount of USD 99.25.

Conversion fees and spreads are already reflected in the terms. Their breakdowns explain the price and should not be deducted again.

Conversion and withdrawal are separate steps. If the withdrawal fails after conversion completes, the conversion is not reversed; the converted funds remain in the funding account’s balance.

5. Quote & Pay

Review the payment terms before confirming.

Use a quote when you need to review the debit, receipt, and fees before paying. Quotes support both same-currency and cross-currency payments. Requesting a quote does not move funds.

Quote times are 30 seconds for cross-currency payments and 30 minutes for same-currency payments.

5.1 Request a quote

Send the payment terms using Create Payout Quote (POST /v2/payouts/quotes).

Example — quote 100 USDC to USD payout

POST /v2/payouts/quotes
{
  "source": {
    "asset": "USDC",
    "amount": "100"
  },
  "destination": {
    "asset": "USD"
  },
  "from_account": "BZ-7Q2K-M9XD",
  "to_account": {
    "account_identifier": "550e8400-e29b-41d4-a716-446655440000"
  }
}
POST /v2/payouts/quotes
{
  "id": "PQ-4N6T-8W3P",
  "status": "CREATED",
  "network": "ACH",
  "source": {
    "asset": "USDC",
    "amount": "100.000000"
  },
  "destination": {
    "asset": "USD",
    "amount": "99.25"
  },
  "to_account": {
    "account_identifier": "550e8400-e29b-41d4-a716-446655440000"
  },
  "conversion": {
    "rate": "0.999",
    "from": {
      "asset": "USDC",
      "amount": "100.000000"
    },
    "to": {
      "asset": "USD",
      "amount": "99.80"
    },
    "fees": {
      "platform": {
        "asset": "USD",
        "amount": "0.10"
      }
    },
    "spread": {
      "platform": {
        "asset": "USDC",
        "amount": "0.000000"
      },
      "partner": {
        "asset": "USDC",
        "amount": "0.100000"
      }
    }
  },
  "withdrawal": {
    "asset": "USD",
    "amount": {
      "gross": "99.80",
      "net": "99.25"
    },
    "fees": {
      "platform": {
        "asset": "USD",
        "amount": "0.35"
      },
      "partner": {
        "asset": "USD",
        "amount": "0.20"
      }
    }
  },
  "created_at": "2026-11-12T12:10:00Z",
  "expires_at": "2026-11-12T12:10:30Z"
}

Save the quote's id and submit it before the returned expires_at.

5.2 Confirm the payout

After the customer confirms, call Create Payout (POST /v2/payouts) with the returned quote_id.

POST /v2/payouts
{
  "external_id": "PARTNER_TX_ID_0123",
  "quote_id": "PQ-4N6T-8W3P"
}
POST /v2/payouts
{
  "id": "PO-4N6T-8W3P",
  "status": "PROCESSING",
  "external_id": "PARTNER_TX_ID_0123",
  "purpose": null,
  "network": "ACH",
  "quote_id": "PQ-4N6T-8W3P",
  "source": {
    "asset": "USDC",
    "amount": "100.000000"
  },
  "destination": {
    "asset": "USD",
    "amount": "99.25"
  },
  "from_account": "BZ-7Q2K-M9XD",
  "to_account": {
    "account_identifier": "550e8400-e29b-41d4-a716-446655440000",
    "account_number": "000123456789",
    "institution": {
      "identifier": "021000021",
      "name": "Example Bank",
      "address": {
        "country": "US"
      }
    },
    "recipient": {
      "id": "550e8400-e29b-41d4-a716-446655440003",
      "name": "Example Supplier LLC",
      "type": "BUSINESS",
      "first_party": false
    }
  },
  "on_behalf_of_account": null,
  "conversion": {
    "id": "550e8400-e29b-41d4-a716-446655440106",
    "rate": "0.999",
    "from": {
      "asset": "USDC",
      "amount": "100.000000"
    },
    "to": {
      "asset": "USD",
      "amount": "99.80"
    },
    "fees": {
      "platform": {
        "asset": "USD",
        "amount": "0.10"
      }
    },
    "spread": {
      "platform": {
        "asset": "USDC",
        "amount": "0.000000"
      },
      "partner": {
        "asset": "USDC",
        "amount": "0.100000"
      }
    },
    "status": "PROCESSING",
    "status_info": null
  },
  "withdrawal": {
    "id": "550e8400-e29b-41d4-a716-446655440105",
    "asset": "USD",
    "amount": {
      "gross": "99.80",
      "net": "99.25"
    },
    "fees": {
      "platform": {
        "asset": "USD",
        "amount": "0.35"
      },
      "partner": {
        "asset": "USD",
        "amount": "0.20"
      }
    },
    "memo": null,
    "tracking_number": null,
    "status": "CREATED",
    "status_info": null
  },
  "created_at": "2026-11-12T12:10:15Z",
  "updated_at": "2026-11-12T12:10:15Z"
}

The bank account is already bound to this quote, so to_account can be omitted. Omit source and destination entirely, including null values: the quote already defines those terms.

A quote can be executed only once, even if its payout later fails. A new execution attempt against an accepted quote returns 409.

To check a quote, use Get Payout Quote (GET /v2/payouts/quotes/{quote_id}). Quote statuses are:

  • CREATED means it is available for acceptance
  • EXPIRED means it can no longer be accepted
  • EXECUTED means it has been accepted for execution.

Check the payout to determine the payment outcome.

6. Payout Workflow

A payout has an overall status and separate statuses for its conversion, when needed, and withdrawal. Use these statuses to understand which step is in progress.

6.1 Payout

A payout typically progresses CREATED → PROCESSING → TRANSMITTING → SENT.

  • CREATED: 1Money has validated and accepted the request and will start processing the payout.

  • PROCESSING: the payout is being processed, including conversion or review when required.

  • TRANSMITTING: the payout is being transmitted to the destination network or rail.

  • SENT: submission to the destination network or rail is confirmed. The recipient's bank account may still be awaiting credit.

  • RFI_PENDING: more information is required to continue.

  • FAILED: the payout failed.

  • RETURNED: the recipient's bank returned the payout after it reached SENT.

6.2 Conversion

A conversion typically progresses CREATED → PROCESSING → COMPLETED.

  • CREATED: the conversion has been created and is waiting to be processed.

  • PROCESSING: the currency exchange is in progress.

  • COMPLETED: the currency exchange has completed.

  • FAILED: the conversion failed.

A completed conversion does not mean the payout has been sent. Check the root payout status for the overall outcome.

6.3 Withdrawal

A withdrawal typically progresses CREATED → PROCESSING → TRANSMITTING → SENT.

  • CREATED: the withdrawal is waiting to start, including waiting for conversion when required.

  • PROCESSING: the withdrawal is being prepared, including any required review.

  • TRANSMITTING: the withdrawal is being transmitted to the destination network or rail.

  • SENT: submission to the destination network or rail is confirmed. The recipient's bank account may still be awaiting credit.

  • RFI_PENDING: more information is required before the withdrawal can continue.

  • FAILED: the withdrawal failed.

  • RETURNED: the recipient's bank returned the withdrawal after it reached SENT.

  • CANCELLED: the withdrawal was cancelled because the required conversion failed.

If a separate conversion completes and the withdrawal later fails, the conversion remains COMPLETED and the overall payout becomes FAILED.

7. Pay on behalf of another account

Use on_behalf_of_account when the funding account pays out on behalf of another account it is authorized to act for. The funds come from the funding account, but the payout is made in the name of the on_behalf_of_account, for example a main account paying out for one of its sub-accounts.

The funding account and the on-behalf account play different roles:

  • from_account is the account that funds the payout. Its balance is debited, and the payout is listed under it.
  • on_behalf_of_account is the account the payout belongs to. It determines the terms and the destination:
    • Sender details: the on-behalf account’s name appears as the sender on the transaction receipt and in any recipient-facing details.
    • Destination: to_account.account_identifier must be a bank account or wallet registered under the on-behalf account. Destinations registered under the funding account are rejected.

Example — main account funds a sub-account’s payout

POST /v2/payouts
{
  "source": {
    "asset": "USD",
    "amount": "100"
  },
  "destination": {
    "asset": "USD"
  },
  "from_account": "BZ-7Q2K-M9XD",
  "to_account": {
    "account_identifier": "550e8400-e29b-41d4-a716-446655440010"
  },
  "on_behalf_of_account": "BZ-9R3K-8V2D"
}
POST /v2/payouts
{
  "id": "PO-5P8N-2R6K",
  "status": "PROCESSING",
  "external_id": null,
  "purpose": null,
  "network": "ACH",
  "quote_id": null,
  "source": {
    "asset": "USD",
    "amount": "100.00"
  },
  "destination": {
    "asset": "USD",
    "amount": "99.45"
  },
  "from_account": "BZ-7Q2K-M9XD",
  "to_account": {
    "account_identifier": "550e8400-e29b-41d4-a716-446655440010",
    "account_number": "000987654321",
    "institution": {
      "identifier": "021000021",
      "name": "Example Bank",
      "address": {
        "country": "US"
      }
    },
    "recipient": {
      "id": "550e8400-e29b-41d4-a716-446655440011",
      "name": "Example Customer Vendor Inc",
      "type": "BUSINESS",
      "first_party": false
    }
  },
  "on_behalf_of_account": "BZ-9R3K-8V2D",
  "conversion": null,
  "withdrawal": {
    "id": "550e8400-e29b-41d4-a716-446655440107",
    "asset": "USD",
    "amount": {
      "gross": "100.00",
      "net": "99.45"
    },
    "fees": {
      "platform": {
        "asset": "USD",
        "amount": "0.35"
      },
      "partner": {
        "asset": "USD",
        "amount": "0.20"
      }
    },
    "memo": null,
    "tracking_number": null,
    "status": "PROCESSING",
    "status_info": null
  },
  "created_at": "2026-11-12T12:20:00Z",
  "updated_at": "2026-11-12T12:20:00Z"
}

8. Track the payment

Follow a payout's progress by checking its status through the APIs or receiving updates through webhooks.

8.1 API

Use Get Payout to retrieve the payout using its root Payout PO-... ID:

GET /v2/payouts/PO-4N6T-8W3P

GET returns the same payout structure as POST, with the current status and available tracking details. Use the root status for the overall payment progress.

Use List Payouts to list payments for a specific funding account and your own payment reference:

GET /v2/payouts?account_id=BZ-7Q2K-M9XD&external_id=invoice-1001

8.2 Webhooks

Subscribe to Payout Webhooks to receive payment updates:

  • payout.transmitting

  • payout.sent

  • payout.failed

  • payout.returned

Conversion events include conversion.completed and conversion.failed. Conversion completion alone does not establish the payout outcome.

For example, a payout notification contains these fields:

{
  "event_name": "payout.sent",
  "resource": {
    "type": "PAYOUT",
    "id": "PO-4N6T-8W3P"
  },
  "data": {
    "from_account": "BZ-7Q2K-M9XD",
    "status": "SENT"
  }
}

Verify webhook signatures and handle duplicates. Retrieve the payout after a notification when you need its current state.