Payments

Staff have access to the API calls listed below if the Invoices tab is enabled for staff. Staff users can only access payments that belong to clients they are assigned to.

• payment.create
• payment.update
• payment.get
• payment.delete
• payment.list

payment.create

Create a new payment and returns the corresponding payment_id.

This function can have one of three possible effects depending on the presence of invoice_id and client_id:

• If you specify an invoice_id only, the payment will be recorded as an invoice payment.
• If you specify a client_id only, the payment will be recorded as a client credit.
• If you specify both an invoice_id and client_id, the payment will be recorded as an invoice payment, and the amount will be subtracted from the client’s credit.

Payment type must be one of: ‘Cash’, ‘Check’, ‘Credit’, ‘Credit Card’, ‘Bank Transfer’, ‘Debit’, ‘PayPal’, ’2Checkout’, ‘VISA’, ‘MASTERCARD’, ‘DISCOVER’, ‘NOVA’, ‘AMEX’, ‘DINERS’, ‘EUROCARD’, ‘JCB’ or ‘ACH’.

Note that ‘currency_code’ can only be provided when creating a credit, not a regular payment. Regular payments will default to the currency code of the invoice they are being made against.

Request

<?xml version="1.0" encoding="utf-8"?>
<request method="payment.create">
  <payment>
    <client_id>13</client_id>           <!-- Optional -->
    <invoice_id>207</invoice_id>        <!-- Associate this payment with an invoice (Optional) -->
    <date>2007-05-30</date>             <!-- Default value is today's date (Optional) -->
    <amount>129.88</amount>             <!-- Default is zero (Optional) -->
    <currency_code>CAD</currency_code>  <!-- Default is system's base currency (Optional) -->
    <type>Check</type>                  <!-- Default is Check (Optional) -->
    <notes>Prompt payment!</notes>      <!-- (Optional) -->
  </payment>
</request>

Response

<?xml version="1.0" encoding="utf-8"?>
<response xmlns="http://www.freshbooks.com/api/" status="ok">
  <payment_id>103</payment_id>
</response>

payment.update

Update an existing payment. All fields besides payment_id are optional – unpassed fields will retain their existing value.

Note that ‘currency_code’ can only be provided when updating a credit, not a regular payment. Regular payments will default to the currency code of the invoice they are being made against.

Request

<?xml version="1.0" encoding="utf-8"?>
<request method="payment.update">
  <payment>
    <payment_id>103</payment_id>
    <amount>0.00</amount>
    <notes>Payment refunded.</notes>
    <currency_code>CAD</currency_code>
  </payment>
</request>

Response

<?xml version="1.0" encoding="utf-8"?>
<response status="ok"/>

payment.get

Retrieve payment details according to payment_id.

Request

<?xml version="1.0" encoding="utf-8"?>
<request method="payment.get">
  <payment_id>322</payment_id>
</request>

Response

<?xml version="1.0" encoding="utf-8"?>
<response xmlns="http://www.freshbooks.com/api/" status="ok">
  <payment>
    <payment_id>109</payment_id>
    <client_id>13</client_id>
    <invoice_id>207</invoice_id>
    <date>2007-05-30 00:00:00</date>
    <amount>129.88</amount>
    <currency_code>CAD</currency_code> <!-- Only returned for credits -->
    <type>VISA</type>
    <notes>Prompt payment!</notes>
    <updated>2009-08-12 09:00:00</updated> <!-- (Read-only) -->
    <gateway_transaction> <!-- (Read-only) --> <!-- Only returned for online payments -->
        <reference_id>2156858189</reference_id>
        <gateway_name>Authorize.Net</gateway_name>
    </gateway_transaction>
  </payment>
</response>

payment.delete

Permanently delete a payment. This will modify the status of the associated invoice if required.

Request

<?xml version="1.0" encoding="utf-8"?>
<request method="payment.delete">
   <payment_id>321</payment_id>
</request>

Response

<?xml version="1.0" encoding="utf-8"?>
<response status="ok"/>

payment.list

Returns a list of recorded payments. You can optionally filter by invoice_id or client_id.

Note: This method uses pagination

Request

<?xml version="1.0" encoding="utf-8"?>
<request method="payment.list">
  <client_id>3</client_id>            <!-- Filter by client (Optional) -->
  <invoice_id>133</invoice_id>        <!-- Filter by invoice (Optional) -->
  <date_from>2007-01-01</date_from>   <!-- Return payments dated after this arg (Optional) -->
  <date_to>2007-04-01</date_to>       <!-- Return payments dated before this arg (Optional) -->
  <updated_from>2007-01-01</updated_from>   <!-- Return payments modified after this arg (Optional) -->
  <updated_to>2007-04-01</updated_to>       <!-- Return payments modified before this arg (Optional) -->

  <page>1</page>                      <!-- Page number to return, default is 1 (Optional) -->
  <per_page>10</per_page>             <!-- Number of results per page, default is 25 (Optional) -->
</request>

Response

<?xml version="1.0" encoding="utf-8"?>
<response xmlns="http://www.freshbooks.com/api/" status="ok">
  <payments page="1" per_page="10" pages="23" total="221">
    <payment>
      <payment_id>165</payment_id>
      <invoice_id>203</invoice_id>
      <date>2007-03-02 12:04:11</date>
      <type>VISA</type>
      <notes></notes>
      <client_id>43</client_id>
      <currency_code>CAD</currency_code> <!-- Only returned for credits -->
      <updated>2009-08-12 09:00:00</updated> <!-- (Read-only) -->
      <gateway_transaction> <!-- (Read-only) --> <!-- Only returned for online payments -->
          <reference_id>2156858189</reference_id>
          <gateway_name>Authorize.Net</gateway_name>
      </gateway_transaction>
      <amount>301.21</amount>
    </payment>
    ...
  </payments>
</response>