Overview

Within the Payment API merchants may create and send out invoices to customers. These invoices will appear within a customer's email with a direct link to a secure hosted payment page, where customers will then be prompted to enter their payment details to complete the transaction.

This article will go over how to create, update, send and close an invoice all through the Payment API. 

Creating an Invoice

In order to create and send an invoice via the Payment API you will need to build a proper invoicing request and post this to your Payment API endpoint. The API endpoint may be found within the Payment API section of the integration portal.

For invoice requests you will need to submit 4 required parameters, which are, invoicing, security_key, amount and email. These parameters will be needed in order to build a proper invoice request within the API.  There are additional variables which you may use within your request to better customize the required information you gather from customers, however, those parameters would be considered optional. You may find all the available variables for creating invoices within the invoicing section of the Payment API documentation.

Here is an example request to create and send an invoice with the Payment API:

POST: /api/transact.php
  
PARAMS: [
    security_key : your_security_key
    invoicing : add_invoice
    amount : 100.00
    email : "Customer's email address to send the invoice"
]

Once you have submitted the request the Payment API will return an invoice_id parameter. The integration will need to store this as this parameter will later need to be used in order to resend, update or close the invoice.

Update an Invoice

If needed the Payment API allows for integrations to update any already created invoices. This request should be used in case any information or invoicing details need to be changed. (i.e Changing the amount or email address).

For invoice update requests you will need to submit 3 required parameters, which are, invoicing, security_key and invoice_id. These parameters will be needed in order to call to the proper invoice and make the requested changes. Once you have added the required parameter you will additionally need to include any parameters which you would like to update. 

Here is an example request to update the amount of an already created invoice with the Payment API:

POST: /api/transact.php
  
PARAMS: [
    security_key : your_security_key
    invoicing : update_invoice
    invoice_id : "The invoice ID to be updated."
    amount : 150.00
]

The above request will find the appropriate invoice and update the amount of the invoice to 150.00. 

Send an Invoice

Although when first creating an invoice it is automatically sent if the email variable is provided within the request, there may be use cases where an invoice may be requested again. The Payment API allows users to send out already created invoices in these cases.

To send out an invoice which has already been created you will need to utilize the invoicing, security_key, email and invoice_id parameters. These parameters will ensure that the appropriate invoice is being sent to the correct customer/requestor.

Here is an example request to send an already created invoice with the Payment API:

POST: /api/transact.php
  
PARAMS: [ 
  
  security_key : your_security_key 
  
  invoicing : send_invoice
  
  invoice_id : "The invoice ID to be updated." 
  
  email : "Customer's email address to send the invoice"

  ]

**Note: If email is not provided, the invoice will be sent to the billing email address assigned to the invoice.

Close an Invoice

For any reason should an invoice need to be closed, the Payment API will allow you to submit a request to close an invoice. Whether an order was cancelled or an invoice was paid in full you should close the invoice once its cycle has been completed.

In order to close an invoice you will need to utilize the invoicing, security_key and invoice_id parameters. These parameters will ensure that the appropriate invoice is being closed/completed.

Here is an example request to close an invoice with the Payment API:

POST: /api/transact.php
  
PARAMS: [ 
  
    security_key : your_security_key 
  
    invoicing : close_invoice
  
    invoice_id : "The invoice ID to be updated." 
  
]