Fees & reports
Use these endpoints to read a company's wallet fees, get credit and debit totals for a connected company, and email tax forms to an individual recipient.
The Reports endpoint, TransferTaxInformation, generates an individual recipient's tax forms from their Xtrm profile data and sends them to the recipient's registered email address.
#Get a company's wallet fees
/API/v4/Fund/GetCompanyFeesReturns the fees set by Xtrm for paying into a wallet, read from the fee schedule of the company account in BeneficiaryAccountNumber. To read your own company's fees, send your own SPN there. The response has a flat fee, a percentage fee, and a cap fee for paying into a company wallet (SendtoCompany) and into an individual's wallet (sendtoIndividual). It returns no other fee types. Only USD is supported: any other CurrencyCode is refused with This currency fee is not available currently. Please use USD fees.
Body parameters
GetCompanyFeesobjectRequiredRequest wrapper.
Child parameters1
RequestobjectRequiredThe fee query.
Child parameters3
IssuerAccountNumberstringRequiredYour company's Xtrm account number, starting with
SPN. This is the company account associated with the credentials you use for the API call. If you use pseudo credentials, use theSPNof the company on whose behalf you are making the call.BeneficiaryAccountNumberstringRequiredXtrm account number, starting with
SPN, of the company whose fee schedule is returned: your own company, or a company connected to yours. Send your ownSPNto read your own fees.CurrencyCodestringRequiredThree-letter ISO 4217 currency code. Only
"USD"is supported.
Response fields
GetCompanyFeesResponseobjectResponse wrapper.
Child parameters1
GetCompanyFeesResultobjectThe result of the fee query.
Child parameters2
CompanyFeesobjectThe fees set for the company.
Child parameters1
SendFeesobjectFees for paying into wallets, by recipient type.
Child parameters2
SendtoCompanyobjectFees for paying a business recipient's wallet.
Child parameters3
FlatFeenumberThe fixed flat fee applied when you pay a business recipient's wallet.
PercentageFeenumberThe percentage-based fee applied when you pay a business recipient's wallet.
CapFeenumberThe maximum capped fee applied when you pay a business recipient's wallet.
sendtoIndividualobjectFees for paying an individual recipient's wallet.
Child parameters3
FlatFeenumberThe fixed flat fee applied when you pay an individual recipient's wallet.
PercentageFeenumberThe percentage-based fee applied when you pay an individual recipient's wallet.
CapFeenumberThe maximum capped fee applied when you pay an individual recipient's wallet.
OperationStatusobjectThe outcome of the operation.
Child parameters2
SuccessbooleanWhether the operation succeeded (
true/false).Errorsstring[]Error messages when the call fails, as an array of strings. On success it's
nullor an empty array[], so decide withSuccess.
#Get credit and debit totals for a connected company
/API/v4/Fund/GetConnectedCompanyFundRequestRetrieves the fund request details for a connected company within a date range that you specify with FromDate and ToDate. Page through results with Pagination.
The response is a CSV report, not JSON, with the columns Account Number, Name, Credits, Debits, and Currency. Credits and Debits are the totals for the date range, with one row per currency. They cover every credit and debit in the connected company's wallets, not only payments from your company. Both FromDate and ToDate are included in the range.
Note
The CSV starts with the header row, Account Number,Name,Credits,Debits,Currency, with no line before it. Each following line is one currency's totals.
Body parameters
GetConnectedFundRequestDetailsobjectRequiredRequest wrapper.
Child parameters1
requestobjectRequiredThe report query.
Child parameters6
IssuerAccountNumberstringRequiredYour company's Xtrm account number, starting with
SPN. This is the company account associated with the credentials you use for the API call. If you use pseudo credentials, use theSPNof the company on whose behalf you are making the call.BeneficiaryAccountNumberstringRequiredXtrm account number of the connected business recipient, starting with
SPN.PaymentTypestringRequiredWhich totals to return:
Creditsreturns only credits (Debitsreads0.00),Debitsonly debits, andAllboth. Any other value also returns both.FromDatestringRequiredStart date of the query, formatted strictly as
MM/DD/YYYY, e.g."01/31/2023".ToDatestringRequiredEnd date of the query, formatted strictly as
MM/DD/YYYY, e.g."12/31/2023".PaginationobjectRequiredPagination settings.
Child parameters2
RecordsToSkipstringRequiredPage number to return, as an integer string:
"1"for the first page,"2"for the next, and so on. Despite its name, it isn't a record offset.RecordsToTakestringRequiredMaximum number of results to return per page, as an integer string, e.g.
"25".
Response fields
Account NumberstringCSV column. Xtrm account number of the connected company, starting with
SPN.NamestringCSV column. Registered name of the connected company.
CreditsstringCSV column. Total credited amount for the date range, e.g.
53.73.DebitsstringCSV column. Total debited amount for the date range, e.g.
85.88.CurrencystringCSV column. Three-letter ISO 4217 currency code for the totals, e.g.
USD.
Related: List business recipients · Get the connection status of an account · List company wallet transactions
#Email tax forms to an individual recipient
/API/v4/Report/TransferTaxInformationEmails tax forms to the address that an individual recipient registered with Xtrm. Identify the recipient with BeneficiaryAccountNumber (starting with PAT) and the reporting period with TaxYear and TaxYearStartMonth.
Xtrm sends the email immediately when you make the call, with a CSV statement of the recipient's transactions for the tax year. For a recipient in the United States, it also attaches Form 1099-K, so the recipient's profile needs their:
- First and last name
- Tax ID (SSN or TIN)
- Date of birth
- Full address: street, city, state, postal code and country
That is, the recipient's AccountIdentityLevel is Standard or Advanced. Recipients outside the United States are sent the CSV statement only.
Use EmailBody to add your own text, such as specific instructions or context, to the body of the email. Xtrm sends it as plain text, so HTML isn't rendered.
The response Message confirms that the email was sent. When a US recipient's profile is missing any of this data, the call fails with 400, and Errors holds Missing profile information. Please ensure profile is complete. When the recipient has no transactions in the tax year, the call fails with 400 and Tax information is not available for the year followed by your TaxYear, and no email is sent.
Note
For a recipient in the United States, the tax form that Xtrm generates is Form 1099-K, sent with a CSV statement of their transactions. A recipient outside the United States gets the CSV statement only.
Body parameters
TransferTaxInformationobjectRequiredOperation wrapper.
Child parameters1
RequestobjectRequiredThe request object.
Child parameters5
IssuerAccountNumberstringRequiredThe unique Xtrm account identifier, starting with
SPN, for the company account associated with the credentials you use for the API call. If you use pseudo credentials, this is theSPNof the company on whose behalf you make the call.BeneficiaryAccountNumberstringRequiredThe unique Xtrm account identifier of the individual recipient who receives the tax forms, starting with
PAT.TaxYearStartMonthstringRequiredThe starting month of the tax year as a numeric string, for example
"1"for January or"12"for December.TaxYearstringRequiredThe four-digit reporting tax year for the requested tax forms, as a string, e.g.
"2024".EmailBodystringRequiredYour own text, added to the body of the email sent to the recipient, for example specific instructions or context. Xtrm sends it as plain text, so HTML isn't rendered.
Response fields
TransferTaxInformationResponseobjectResponse wrapper.
Child parameters1
TransferTaxInformationResultobjectThe result of the request.
Child parameters2
MessagestringA system message describing the outcome, such as a confirmation that the email was sent.
OperationStatusobjectThe outcome of the operation.
Child parameters2
SuccessbooleanWhether the operation succeeded (
true) or failed (false).Errorsstring[]Error messages when the call fails, as an array of strings. On success it's
nullor an empty array[]([]in the example), so decide withSuccess.
Related: List individual recipients · Check whether an individual recipient exists · Create an individual recipient · Update an individual recipient