Estimate a payout

POST /payouts/estimate calculates what a recipient would receive for an amount and a payment method. It stores nothing, reserves nothing, and locks no exchange rate. Use it to show the recipient an amount before a cash-out, or to compare payment methods. It needs payouts:write.

The request does not refer to a payout, so you can call it before the payout exists. This is the only moment for it when you create, approve, and pay in one request with andThen: "approve_and_pay".

Estimate for a counterpartyCopy Anchor Link

You pay directly, so the counterparty has a saved payment method. Send the amount, the currency, and the counterparty:

curl -X POST "$BASE_URL/payouts/estimate" \
  -H "Authorization: Bearer $TALENTIR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "84.03",
    "currency": "EUR",
    "counterpartyId": "counterparty_7c1d2f30-…"
  }'

The counterparty is paid by SWIFT, and the recipient pays the transfer fee of 5.38 EUR:

{
  "object": "payout_estimate",
  "amount": "84.03",
  "currency": "EUR",
  "vat": "0.00",
  "paymentMethod": { "type": "swift", "currency": "EUR" },
  "settlement": { "amount": "78.65", "currency": "EUR", "asset": null }
}

counterpartyId is the counterparty id or your customId. The estimate uses the saved payment method and the VAT status of the counterparty. A counterparty that Talentir keeps for a recipient who claimed before (recipientManaged: true) works the same way: the estimate uses the method the recipient chose last.

Estimate for a payment methodCopy Anchor Link

You pay with a payout link, so the recipient chooses the payment method on the claim page. Before that, you do not know the method. Send paymentMethod in place of counterpartyId, one request for each method you want to show:

curl -X POST "$BASE_URL/payouts/estimate" \
  -H "Authorization: Bearer $TALENTIR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "230.00",
    "currency": "EUR",
    "paymentMethod": { "type": "crypto", "asset": "eip155:8453/erc20:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" }
  }'

{
  "object": "payout_estimate",
  "amount": "230.00",
  "currency": "EUR",
  "vat": "0.00",
  "paymentMethod": { "type": "crypto", "asset": "eip155:8453/erc20:0x8335…", "currency": "USD" },
  "settlement": { "amount": "254.230000", "currency": "USD", "asset": "eip155:8453/erc20:0x8335…" }
}

paymentMethod names the rail and what it settles in, without account details: type and currency for a fiat rail, type: "crypto" and asset for a token. Read the types, their currencies, and the tokens from GET /payment-method-types. A currency the rail does not take, or a token Talentir does not pay out, is 400 VALIDATION_FAILED.

To compare methods for one counterparty, send counterpartyId and paymentMethod together. The method in the request then replaces the saved one, and the VAT status still comes from the counterparty.

Read the resultCopy Anchor Link

settlement.amount is the amount to show to the recipient. It is amount plus vat, converted to the settlement currency or token, minus the transfer fee when the recipient pays it.

• settlement is the same object as settlement on a transaction. After the payout is delivered, the transaction carries the amount that arrived.
• The conversion uses the current rate with Talentir's exchange margin. There is no conversion when the recipient is paid in currency.
• The transfer fee is already taken off settlement.amount when the recipient pays it. Your team sets who pays, for each type of transfer, in the payout settings of the dashboard.
• vat is the VAT that the recipient's invoice adds to amount, for example for a recipient in your country who is registered for VAT. The recipient receives it with the payout. It is 0.00 for a payout with withInvoice: false, and without counterpartyId, because the VAT status of the recipient is then not known.
• paymentMethod is the method the estimate is for.

The fees that your team pays are not part of the estimate. They leave your account as fee transactions.

An estimate, not a quoteCopy Anchor Link

The payout settles at the exchange rate and the fees of the moment it is paid. The delivered amount can differ from the estimate for these reasons:

• The exchange rate moves. With andThen: "approve_and_pay", estimate immediately before the request: the payout is paid seconds later. With a claim link, the recipient can claim days later.
• The recipient chooses a different method on the claim page.
• Payouts go out together. The estimate is for a payout that is paid alone. Payouts to one recipient that are paid in one request, or claimed together, go out as one transfer and pay the transfer fee one time.
• Your team's transfers included in the month are used up, or your team changes who pays the transfer fee.
• The counterparty changes its address or its VAT status.

Label the amount as an estimate in your product. For the amount that arrived, read settlement on the payout's transaction.

ErrorsCopy Anchor Link

The request changes nothing, so it takes no Idempotency-Key, and you can repeat it freely.

For every parameter and the full response schema, see the reference.