Send payment transactions

Each payment your platform makes to a recipient is one income transaction on the recipient's account. Taxbit computes the amounts on their US information returns from the transactions you send.

By the end of this page you have sent a payment to Taxbit, know how to correct or remove one, and know how to send many safely.

Before you begin

• A bearer token. See Authenticate your tenant.
• The recipient's account. See Create account owners and accounts.
• The transaction types sheet from your kickoff, which maps each kind of payment on your platform to a transaction type and subtype.

Send the payment

Send one transaction per payment, identified by your own id for it. type is income, and subtype says what the payment was for: payment-goods, payment-services, nec, rent, and royalties are among the income subtypes, and your transaction types sheet says which ones you use. The amount paid goes in received, with a USD rate. Put any fee or commission you charge the recipient on the payment in fees.

curl -X POST $BASE_URL/v1/transactions/external-id \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "pmt_7c41e9a2",
    "account_id": "acct_5f2e7d10",
    "type": "income",
    "subtype": "payment-services",
    "datetime": "2026-03-14T18:22:05.000Z",
    "received": [
      {
        "asset_amount": {
          "asset": { "code": "USD", "type": "Fiat" },
          "amount": "904.10"
        },
        "rates": [
          { "asset": { "code": "USD", "type": "Fiat" }, "amount": "1.00" }
        ]
      }
    ],
    "fees": [
      {
        "asset_amount": {
          "asset": { "code": "USD", "type": "Fiat" },
          "amount": "27.12"
        },
        "rates": [
          { "asset": { "code": "USD", "type": "Fiat" }, "amount": "1.00" }
        ]
      }
    ]
  }'

{
  "status": "success",
  "message": "Transaction post successful."
}

A 201 means Taxbit accepted the transaction.

Send the amount the recipient was paid in received, before fees, and the fee in fees. When Taxbit builds the form, it subtracts a fee in the same asset from the amount, so don't net it yourself: a net received plus the fee counts the fee twice. A fee in a different asset is not subtracted.

Correct or remove a payment

Sending a transaction again with the same id updates it and returns 201 again, so you correct a payment by resending the whole transaction with the right values. You don't need to delete it first.

To remove a payment you sent in error, delete it by id. The request returns 200.

curl -X DELETE $BASE_URL/v1/transactions/external-id/pmt_7c41e9a2 \
  -H "Authorization: Bearer $TOKEN"

Send many payments

Send one request per transaction id at a time. Two requests for the same id in flight at once can fail with a 400 uniqueness error. Sent one after the other, the second updates the first.

For historical loads, the Taxbit Dashboard has a file uploader that takes CSV and JSONL instead of API calls; your implementation manager can walk you through it.

If the request fails

• 400. A field failed validation, or two requests for the same id were in flight at once. The body carries a message, or a messages array when there are several problems. Fix the field and resend; for a uniqueness error, resend once the other request has finished.
• 401. The bearer token is missing, invalid, or expired. Mint a new one and retry.
• 429. Too many requests. Slow down and retry.

The Errors page has every error shape, the rate limits, and which calls are safe to retry.

Parameters

Only the fields used above. The full schema, including every type and subtype, is in the API Reference.

Where to go next

Collect recipient tax data gets each recipient's W-9 or W-8 data to Taxbit, so their forms can be filed. If you are a digital asset broker and need Taxbit to compute cost basis, start in Cost Basis & Gains instead.