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 know your way around a cURL request

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 you can click on “Add-ons” on the left-hand navigation bar. Look for “Advanced Payments” and click “Get Add-on”, or you can call our friendly account managers at 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 accountid 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 Payments Gateways

In this step, you’re going to check which payment gateways have been enabled by the business owner using the FreshBooks UI. We’re going to perform a GET call using the account_id to get the list of available payment gateways.

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 to everyone.

As you notice in our response, we have the gateway_name as “fbpay” available. We will need this in our next call where we add this payment gateway to our invoice.

3. Add Payment Gateway to the Invoice

In this step, we’ll add the payment gateway received in the above step to the invoice we created earlier. This will be achieved via a POST api call. Notice that we are setting the value for “has_credit_card” 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. – 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

In case you want to check if online payments have been enabled on an invoice, you can use the below API call to find out.

Response body:

5. Disable an Online Payment on an Existing Invoice

Additionally, if you need to disable the online payment on an existing invoice, you can use the below post call to disable the gateway on the invoice. All you need to provide is the correct invoice id in the URL and provide the entity type in the request body.

Request body:

Still have questions? Something isn’t working right? Don’t hesitate to reach out to [email protected].
We’ll respond to your request 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
    }
  }
}