Enabling Online Payments On An Invoice
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 api@freshbooks.com.
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
}
}
}