Enabling Online Payments On An Invoice

So you’re looking to enable online payments on an Invoice via our API? Well, you’ve come to the right place.

To get started, you’ll need:

FreshBooks account with Advanced Payments
FreshBooks Payments or Stripe account
Postman or familiarity with cURL

Here’s a quick example of why you would need this tutorial: Let’s imagine you’re a business owner who sends out a lot of invoices each month. You’d like to enable online payments on these invoices so you can get paid faster.

In this tutorial, we’ll look at how to find the available payment gateway options, as well as how you can enable online payments on an invoice.

NOTE: You will need Advanced Payments on New FreshBooks to enable this. If you don’t have it, click “Add-ons” in the left-hand navigation bar, find “Advanced Payments”, and select “Get Add-on”, or call 1.833.333.1128.

1. Create an Invoice

Let’s start by creating an invoice for your client.

I’m going to make a POST request to:

https://api.freshbooks.com/accounting/account/{{account_id}}/invoices/invoices

Keep note of account_id and invoice_id from the response because you’re going to need those later.

Now that we have an invoice, let’s find out the payment options that are available to your business.

2. Check Available Online Payment Gateways

In this step, you’ll check which payment gateways have been enabled by the business owner using the FreshBooks UI.

https://api.freshbooks.com/payments/account/{{accountId}}/payment_options?entity_type=invoice

NOTE: FbPay (WePay) is available only in Canada and the USA. Stripe and PayPal are available globally.

As shown in the response, the gateway_name “fbpay” is available. We’ll need this value in the next step.

3. Add Payment Gateway to the Invoice

In this step, we’ll add the payment gateway to the invoice created earlier using a POST request. Note that has_credit_card is set to true.

https://api.freshbooks.com/payments/account/<account_id>/invoice/<invoice_id>/payment_options

Underlined fields are required on creation.

Field	Type	Description
gateway_name	string	Payment gateway name. The available gateway_names are as follows: - WePay: "fbpay" - Stripe: "stripe" - PayPal: "paypal"
has_credit_card	bool	If the invoice can accept credit cards
has_ach_transfer	bool	If the invoice can accept ACH bank transfers
has_bacs_debit	bool
has_sepa_debit	bool
has_paypal_smart_checkout	bool
allow_partial_payments	bool	If the client can use the gateway to pay part of the invoice or only the full amount.
entity_type	string	Eg. "invoices"
entity_id	int	invoice_id of the connected invoice
gateway_info	object	Additional gateway details

Request body:

Response body:

You have now successfully enabled online payment on the invoice.

4. Check for Payment Gateways Applied to an Existing Invoice

To check whether online payments are enabled on an invoice, use the following API call:

Response body:

5. Disable an Online Payment on an Existing Invoice

If you need to disable online payments on an existing invoice, use the following POST call with the correct invoice ID and entity type.

Request body:

Still have questions? Something isn’t working right? Don’t hesitate to reach out to api@freshbooks.com. We’ll respond as quickly as we can.

Create Invoice

Request: POST "https://api.freshbooks.com/accounting/account/<account_id>/invoices/invoices"

{
  "invoice":{
    "customerid":34903,
    "create_date":"2021-02-18",
    "lines":[
      {
        "type":0,
        "description":"",
        "taxName1":"",
        "taxAmount1":0,
        "name":"Paperwork",
        "qty":1,
        "taxName2":"",
        "taxAmount2":0,
        "unit_cost":{
          "amount":"5000.00",
          "code":"USD"
        }
      }
    ]
  }
}



Response:

 {
  "response":{
    "result":{
      "invoice":{
        "accountid":"d93xx2",
        "accounting_systemid":"d93xx2",
        "address":"",
        "amount":{
          "amount":"5000.00",
          "code":"USD"
        },
        "auto_bill":false,
        "autobill_status":null,
        "basecampid":0,
        "city":"",
        "code":"",
        "country":"United States",
        "create_date":"2021-02-18",
        "created_at":"2021-02-22 09:06:00",
        "currency_code":"USD",
        "current_organization":"Dummy Company LTD",
        "customerid":34903,
        "date_paid":null,
        "deposit_amount":null,
        "deposit_percentage":null,
        "deposit_status":"none",
        "description":"",
        "discount_description":null,
        "discount_total":{
          "amount":"0.00",
          "code":"USD"
        },
        "discount_value":"0",
        "display_status":"draft",
        "dispute_status":null,
        "due_date":"2021-02-18",
        "due_offset_days":0,
        "estimateid":0,
        "ext_archive":0,
        "fname":"Test",
        "fulfillment_date":null,
        "generation_date":null,
        "gmail":false,
        "id":21507,
        "invoice_number":"0000002",
        "invoiceid":21507,
        "language":"en",
        "last_order_status":null,
        "lname":"Company",
        "net_paid_amount":{
          "amount":"0.00",
          "code":"USD"
        },
        "notes":"",
        "organization":"Dummy Company LTD",
        "outstanding":{
          "amount":"5000.00",
          "code":"USD"
        },
        "ownerid":1,
        "paid":{
          "amount":"0.00",
          "code":"USD"
        },
        "parent":0,
        "payment_details":"",
        "payment_status":"unpaid",
        "po_number":null,
        "province":"",
        "return_uri":null,
        "sentid":1,
        "show_attachments":true,
        "status":1,
        "street":"",
        "street2":"",
        "template":"clean-grouped",
        "terms":"",
        "updated":"2021-02-22 09:06:00",
        "v3_status":"draft",
        "vat_name":"",
        "vat_number":"",
        "version":"2021-02-22 09:06:00.236628",
        "vis_state":0
      }
    }
  }
}

Check Online Payment gateways available

Request: GET "https://api.freshbooks.com/payments/account/<account_id>/payment_options?entity_type=invoice"

Response:

{
  "payment_options":{
    "gateway_name":"fbpay",
    "has_credit_card":true,
    "has_ach_transfer":false,
    "has_bacs_debit":false,
    "has_sepa_debit":false,
    "has_acss_debit":false,
    "has_paypal_smart_checkout":false,
    "allow_partial_payments":false,
    "entity_type":"invoice",
    "entity_id":"15867",
    "gateway_info":null
  }
}

Add payment gateway to the invoice

Request: POST https://api.freshbooks.com/payments/account/<account_id>/invoice/<invoice_id>/payment_options

{
    "has_credit_card": true,
    "gateway_name": "fbpay"
}



Response:

{
  "payment_options":{
    "gateway_name":"fbpay",
    "has_credit_card":true,
    "has_ach_transfer":false,
    "has_bacs_debit":false,
    "has_sepa_debit":false,
    "has_acss_debit":false,
    "has_paypal_smart_checkout":false,
    "allow_partial_payments":false,
    "entity_type":"invoice",
    "entity_id":"21507",
    "gateway_info":{
      "id":"156c483c9a1a4bde8fbe8de701efc33c",
      "account_id":"1694807511",
      "country":"US",
      "user_publishable_key":null,
      "currencies":[
        "USD"
      ],
      "bank_transfer_enabled":true,
      "gateway_name":"fbpay",
      "can_process_payments":true
    }
  }
}

Get Payment options on an Invoice

Request: GET https://api.freshbooks.com/payments/account/<account_id>/invoice/<invoice_id>/payment_options

Response:

{
  "payment_options":{
    "gateway_name":"fbpay",
    "has_credit_card":true,
    "has_ach_transfer":false,
    "has_bacs_debit":false,
    "has_sepa_debit":false,
    "has_acss_debit":false,
    "has_paypal_smart_checkout":false,
    "allow_partial_payments":false,
    "entity_type":"invoice",
    "entity_id":"21507",
    "gateway_info":{
      "id":"156c483c9a1a4bde8fbe8de701efc33c",
      "account_id":"1694807511",
      "country":"US",
      "user_publishable_key":null,
      "currencies":[
        "USD"
      ],
      "bank_transfer_enabled":true,
      "gateway_name":"fbpay",
      "can_process_payments":true
    }
  }
}