API reference

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

POST/API/v4/Fund/GetCompanyFees

Returns 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

  • GetCompanyFeesobjectRequired

    Request wrapper.

    Child parameters1
    • RequestobjectRequired

      The fee query.

      Child parameters3
      • IssuerAccountNumberstringRequired

        Your 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 the SPN of the company on whose behalf you are making the call.

      • BeneficiaryAccountNumberstringRequired

        Xtrm account number, starting with SPN, of the company whose fee schedule is returned: your own company, or a company connected to yours. Send your own SPN to read your own fees.

      • CurrencyCodestringRequired

        Three-letter ISO 4217 currency code. Only "USD" is supported.

Response fields

  • GetCompanyFeesResponseobject

    Response wrapper.

    Child parameters1
    • GetCompanyFeesResultobject

      The result of the fee query.

      Child parameters2
      • CompanyFeesobject

        The fees set for the company.

        Child parameters1
        • SendFeesobject

          Fees for paying into wallets, by recipient type.

          Child parameters2
          • SendtoCompanyobject

            Fees for paying a business recipient's wallet.

            Child parameters3
            • FlatFeenumber

              The fixed flat fee applied when you pay a business recipient's wallet.

            • PercentageFeenumber

              The percentage-based fee applied when you pay a business recipient's wallet.

            • CapFeenumber

              The maximum capped fee applied when you pay a business recipient's wallet.

          • sendtoIndividualobject

            Fees for paying an individual recipient's wallet.

            Child parameters3
            • FlatFeenumber

              The fixed flat fee applied when you pay an individual recipient's wallet.

            • PercentageFeenumber

              The percentage-based fee applied when you pay an individual recipient's wallet.

            • CapFeenumber

              The maximum capped fee applied when you pay an individual recipient's wallet.

      • OperationStatusobject

        The outcome of the operation.

        Child parameters2
        • Successboolean

          Whether the operation succeeded (true / false).

        • Errorsstring[]

          Error messages when the call fails, as an array of strings. On success it's null or an empty array [], so decide with Success.

#Get credit and debit totals for a connected company

POST/API/v4/Fund/GetConnectedCompanyFundRequest

Retrieves 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

  • GetConnectedFundRequestDetailsobjectRequired

    Request wrapper.

    Child parameters1
    • requestobjectRequired

      The report query.

      Child parameters6
      • IssuerAccountNumberstringRequired

        Your 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 the SPN of the company on whose behalf you are making the call.

      • BeneficiaryAccountNumberstringRequired

        Xtrm account number of the connected business recipient, starting with SPN.

      • PaymentTypestringRequired

        Which totals to return: Credits returns only credits (Debits reads 0.00), Debits only debits, and All both. Any other value also returns both.

      • FromDatestringRequired

        Start date of the query, formatted strictly as MM/DD/YYYY, e.g. "01/31/2023".

      • ToDatestringRequired

        End date of the query, formatted strictly as MM/DD/YYYY, e.g. "12/31/2023".

      • PaginationobjectRequired

        Pagination settings.

        Child parameters2
        • RecordsToSkipstringRequired

          Page 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.

        • RecordsToTakestringRequired

          Maximum number of results to return per page, as an integer string, e.g. "25".

Response fields

  • Account Numberstring

    CSV column. Xtrm account number of the connected company, starting with SPN.

  • Namestring

    CSV column. Registered name of the connected company.

  • Creditsstring

    CSV column. Total credited amount for the date range, e.g. 53.73.

  • Debitsstring

    CSV column. Total debited amount for the date range, e.g. 85.88.

  • Currencystring

    CSV 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

POST/API/v4/Report/TransferTaxInformation

Emails 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
  • Email
  • 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

  • TransferTaxInformationobjectRequired

    Operation wrapper.

    Child parameters1
    • RequestobjectRequired

      The request object.

      Child parameters5
      • IssuerAccountNumberstringRequired

        The 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 the SPN of the company on whose behalf you make the call.

      • BeneficiaryAccountNumberstringRequired

        The unique Xtrm account identifier of the individual recipient who receives the tax forms, starting with PAT.

      • TaxYearStartMonthstringRequired

        The starting month of the tax year as a numeric string, for example "1" for January or "12" for December.

      • TaxYearstringRequired

        The four-digit reporting tax year for the requested tax forms, as a string, e.g. "2024".

      • EmailBodystringRequired

        Your 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

  • TransferTaxInformationResponseobject

    Response wrapper.

    Child parameters1
    • TransferTaxInformationResultobject

      The result of the request.

      Child parameters2
      • Messagestring

        A system message describing the outcome, such as a confirmation that the email was sent.

      • OperationStatusobject

        The outcome of the operation.

        Child parameters2
        • Successboolean

          Whether the operation succeeded (true) or failed (false).

        • Errorsstring[]

          Error messages when the call fails, as an array of strings. On success it's null or an empty array [] ([] in the example), so decide with Success.

Related: List individual recipients · Check whether an individual recipient exists · Create an individual recipient · Update an individual recipient