The Invoice generator API includes 2 services:

• Document creation
• Document re-generation

REQUIREMENTS

DOCUMENT CREATION

Service endpoints

There are two endpoints (base URLs) to which you can make your API calls:

• Stage, if you are testing your integration,
• and Production, when you have finished testing and want your application to go live.

To create an invoice, you must send these 4 mandatory parameters in your Document creation request:

• file_destination
• layout_reference
• document_name
• reference_value

Please note: the “file_destination” parameter enables you to choose the document destination:

• “sftp”
• or “binary”
• or “sftp|binary”

Request example

{
   "layout_reference": "My_Layout_8",
   "document_name": "Invoice_245876",
   "sending": {
       "file_destination": "binary"
   },
   "document": {
       "information": {
           "label": "General information",
           "type_label": "Document type",
           "type_value": "Invoice",
           "reference_label": "Reference",
           "reference_value": "INV_P_2018_07_11_MCHx_Shop_01",
           "date_label_1": "Printing date",
           "date_value_1": "04/07/2018",
           "date_label_2": "Processing date",
           "date_value_2": "03/07/2018"
       },
       "header": {
           "logo_1": "Image1_MerchantX_64-64.png",
           "page_number": {
               "display": true,
               "prefix_label": "Page number:"
           },
           "description_1": "ABC COMPANY, the leader in its field",
           "description_2": "30 locations worldwide"
       },
       "page_header": {
           "display_on_first_page": true,
           "logo_1": "Image4_MerchantA_64-64.png",
           "logo_2": null,
           "logo_3": null,
           "page_number": {
               "display": false
           },
           "description_1": "ABC COMPANY",
           "description_2": "Confidential"
       },
       "order_information": {
           "label": "Order information",
           "reference_label_1": "Customer reference",
           "reference_value_1": "XA34",
           "reference_label_2": "Merchant reference",
           "reference_value_2": "MCH37",
           "date_label": "Order date",
           "date_value": "02/07/2018",
           "total_ht_label": "Excl. tax amount",
           "total_ht_value": "€100",
           "total_vat_label": "Tax amount",
           "total_vat_value": "€20",
           "total_ttc_label": "Incl. tax amount",
           "total_ttc_value": "€120"
       },
       "customer_information": {
           "label": "Account information",
           "type_label": "Offer",
           "type_value": "Premium",
           "reference_label": "ID",
           "reference_value": "12345"
       },
       "customer_communication": {
           "label_1": "Special offer",
           "value_1": "10% discount between 01/03/2018 and 15/03/2018",
           "label_2": "Important information",
           "value_2": "From 20/05/2018, shipping fees will be applicable for all orders under €5."
       },
       "payment_instruction": {
           "label": "Payment instructions",
           "payment_term_label": "Payment conditions:",
           "payment_term_value": "30 days from reception",
           "payment_method_label": "Payment method",
           "payment_method_value": "Transfer on IBAN",
           "total_to_pay_label": "Amount to be paid",
           "total_to_pay_value": "120 EUR",
           "due_date_label": "To be paid before:",
           "due_date_value": "31/05/2018",
           "iban_label": "IBAN:",
           "iban_value": "FR 32 5000 4699XXXX89",
           "bic_label": "SWIFT/BIC code:",
           "bic_value": "XXXXIE2D"
       },
       "sender": {
           "label_1": "Sender information",
           "label_2": "Administrative information",
           "company_name": "ABC COMPANY",
           "address_1": "123 Main Street",
           "address_2": "City",
           "address_3": "Postal code",
           "address_4": "COUNTRY",
           "address_5": null,
           "registration_number": "1234 5678 9",
           "contact_name": "Contact @ ABC Company: John DOE",
           "email": "Email: john@abccompany.fr",
           "tel_number_1": "Phone number: XXX-XXX-XXXX",
           "tel_number_2": null,
           "website": "http://www.abc.company.fr",
           "additional_information_1": "Twitter ID: @abccompany",
           "additional_information_2": null
       },
       "on_behalf_of": {
           "label_1": "OBO information",
           "label_2": "Administrative information",
           "company_name": "OBO company",
           "address_1": "123 Main Street",
           "address_2": "POSTAL CODE CITY",
           "address_3": "COUNTRY",
           "share_capital": "Share capital of X,XXX,XXX.XX euros",
           "legal_form": "SAS",
           "rcs": "RCS Paris 123 456 789",
           "vat_identification_number": "Intracommunity VAT: FR91 123 456 789",
           "national_registration_id_1": "SIREN: 123 456 789",
           "national_registration_id_2": "SIRET: 123 456 789 000 06",
           "contact_name": "Jane DOE",
           "email": "jane.doe@obocompany.fr",
           "tel_number_1": "Main number: 01 23 45 67 89",
           "tel_number_2": null,
           "website": "www.obocompany.fr",
           "additional_information_1": null,
           "additional_information_2": null
       },
       "recipient": {
           "general": {
               "label_1": "Customer information",
               "label_2": "Detailed information",
               "company_name": "Company XYZ",
               "civility": "Ms.",
               "first_name": "Jane",
               "last_name": "DOE",
               "address_1": "2 Anystreet",
               "address_2": "POSTAL CODE CITY",
               "address_3": "COUNTRY",
               "address_4": null,
               "address_5": null,
               "registration_number": null,
               "share_capital": "Share capital of X,XXX,XXX.XX euros",
               "legal_form": "LLC",
               "rcs": "RCS Paris 234 567 890",
               "vat_identification_number": "Intracommunity VAT: FR91 234 567 890",
               "national_registration_id_1": "SIREN: 234 567 890",
               "national_registration_id_2": "SIRET: 234 567 890 000 06",
               "contact_name": "Ms. Jane DOE",
               "email": "janedoe@gmail.com",
               "tel_number_1": "01 23 45 67 89",
               "tel_number_2": null,
               "website": "www.companyxyz.fr",
               "additional_information_1": null,
               "additional_information_2": null
           },
           "billing": {
               "label_1": "Customer information",
               "label_2": "Billing information",
               "company_name": "Sohenso Corporation",
               "civility": "Mr",
               "first_name": "Joe",
               "last_name": "SOHENSO",
               "address_1": "3 Anystreet",
               "address_2": "POSTAL CODE CITY",
               "address_3": "COUNTRY",
               "registration_number": null,
               "share_capital": "Share capital of X,XXX,XXX.XX euros",
               "legal_form": "SAS",
               "rcs": "RCS Paris 345 678 901",
               "vat_identification_number": "Intracommunity VAT: FR91 345 678 901",
               "national_registration_id_1": "SIREN: 345 678 901",
               "national_registration_id_2": "SIRET: 345 678 901 000 06",
               "contact_name": "Mr Joe SOHENSO",
               "email": "joesohenso@gmail.com",
               "tel_number_1": "01 23 45 67 89",
               "tel_number_2": null,
               "website": null,
               "additional_information_1": null,
               "additional_information_2": null
           },
           "shipping": {
               "label_1": "Customer information",
               "label_2": "Shipping information",
               "company_name": "Sohenso Corporation",
               "civility": "Ms.",
               "first_name": "Jane",
               "last_name": "SOHENSO",
               "address_1": "2 Anystreet",
               "address_2": "Building 3C",
               "address_3": "POSTAL CODE CITY",
               "address_4": "COUNTRY",
               "registration_number": null,
               "share_capital": "Share capital of X,XXX,XXX.XX euros",
               "legal_form": "LLC",
               "rcs": "RCS Paris 234 567 890",
               "vat_identification_number": "Intracommunity VAT: FR91 234 567 890",
               "national_registration_id_1": "SIREN: 234 567 890",
               "national_registration_id_2": "SIRET: 234 567 890 000 06",
               "contact_name": "Ms. Ann HAGRAM",
               "tel_number_1": "01 23 45 67 89"
           }
       },
       "shipping_precisions": {
           "label": "Shipping detailed information",
           "shipping_mode_label": "Mode:",
           "shipping_mode_value": "DHL express",
           "delivery_area_label": "Zone:",
           "delivery_area_value": "Europe",
           "volume_label": "Volume:",
           "volume_value": "< 1 cubic meter",
           "weight_label": "Weight:",
           "weight_value": "< 5 kg",
           "packages_number_label": "Number of packages:",
           "packages_number_value": "1"
       },
       "summary": {
           "label": "Summary of amounts",
           "header": ["Title", "Excl. Tax Amount", "Tax Amount", "Incl. Tax Amount"],
           "values": [{
                   "lineType": "default",
                   "data": ["Product1", "50 EUR", "10 EUR", "60 EUR"]
               },
               {
                   "lineType": "default",
                   "data": ["Product2", "50 EUR", "10 EUR", "60 EUR"]
               },
               {
                   "lineType": "default",
                   "data": ["Total", "100 EUR", "20 EUR", "120 EUR"]
               }
           ]
       },
       "items": {
           "label": "Product details",
           "header": ["Title", "Reference", "Quantity", "Excl. Tax Amount"],
           "values": [{
                   "lineType": "default",
                   "data": ["Product1", "T2E11", "1", "50.00 EUR"]
               },
               {
                   "lineType": "default",
                   "data": ["Product2", "L9R13", "1", "50.00 EUR"]
               },
               {
                   "lineType": "Total",
                   "data": ["Total amount", " ", " ", "100.00 EUR"]
               }
           ]
       },
       "invoice_summary": {
           "label": "Summary table",
           "header": ["Total Excl. Tax Amount", "Total Tax Amount", "Total Incl. Tax Amount"],
           "values": [{
               "lineType": "default",
               "data": ["100 EUR", "20 EUR", "120 EUR"]
           }]
       },
       "custom_items": {
           "label": "Detail of taxes and social contributions",
           "header": ["Excl. Tax Amount including :"],
           "values": [{
                   "lineType": "default",
                   "data": ["Social tax : 2.20 EUR"]
               },
               {
                   "lineType": "default",
                   "data": ["Other tax : 1.50 EUR"]
               }
           ]
       },

      "page_footer": {
           "logo_1": null,
           "logo_2": null,
           "logo_3": null,
           "page_number": {
               "display": false,
               "prefix_label": "Page"
           },
           "description_1": "ABC COMPANY 123\n Main Street\n City \n Postal code\n COUNTRY",
           "description_2": "Payment conditions and terms of sale\n\nLate payment: late payment penalties shall apply. Minimum annual interest rate (3.03%)\nfixed by law plus a €40 flat-rate compensation."
       }
   }
}

Response status codes 

Here is the list of return codes:

In case of a 400, 403 or 409 response, the document is not created.

DOCUMENT RE-GENERATION

Invoices can be re-generated within 60 days upon document creation.

Service endpoints

The {reference} of the document you want to re-generate must be specified in the endpoint URL.

It must correspond to the mandatory field “reference_value” sent in the Document creation request.

If you call the API Production endpoint to re-generate a document created through the API Stage endpoint, the API will return a 404 response code (reference not found).

You can choose if the re-generated document keeps its “document_name” (by default) or you can change it.

Request example

{
     "document_name": "New document name", /* complementary parameter */
     "sending" : {
         "file_destination": "binary" /* sftp and/or binary */
     }
}

Response status codes

Here is the list of return codes:

In case of a 400, 403 or 404 response, the document is not re-generated.

POSSIBLE ERROR RETURNS

Invalid JSON

Description: Received data do not seem to be in JSON or JSON input is invalid.

Return code: 400

Response example:

{
 "document_reference"       : null,
 "document_name"            : null,
 "layout_reference"         : null,
 "file_destination"         : null,
 "generation_status"        : "FAILURE",
 "generation_error_code"    : "INVALID_JSON",
 "generation_error_message" : "Provided data must be in valid JSON format.",
 "generation_error_details" : null
}

Missing or invalid required field

Description: Some required information is missing or invalid in the provided data.

Return code: 400

Response example:

{
 "document_reference"       : "INV_2081200001",
 "document_name"            : "inv@l!d nam€",
 "layout_reference"         : "My_Layout_8",
 "file_destination"         : "binary",
 "generation_status"        : "FAILURE",
 "generation_error_code"    : "MISSING_OR_INVALID_REQUIRED_FIELD",
 "generation_error_message" : "Missing or invalid required field",
 "generation_error_details" : [
   {
     "property" : "document_name",
     "message" : "Does not match the regex pattern ^{a-zA-Z0-9._-}*$"
   },
   {
     "property" : "document.information",
     "message" : "The property information is required"
   }
 ]
}

The “generation_error_details” field will vary depending on the provided data. Its format will remain the same and consists of an array of the errors in received data.  

Each array item is an object containing two properties represented by the following keys:

• “property”: name of the field containing errors
• “message”: error message associated with the field

List of possible errors:

File download not enabled

Description: The “File download” option has not been enabled on your account.

Return code: 403

Response example:

{
 "document_reference"       : "INV_2081200001",
 "document_name"            : "My_Custom_doc_name",
 "layout_reference"         : "My_Layout_8",
 "file_destination"         : "sftp",
 "generation_status"        : "FAILURE",
 "generation_error_code"    : "FILE_DOWNLOAD_NOT_ENABLED",
 "generation_error_message" : "File download is not activated on your account. Please ask the HiPay team to enable it.",
 "generation_error_details" : null
}

Layout not found

Description: The selected layout does not exist.

Return code: 404

Response example:

{
 "document_reference"       : "INV_2081200001",
 "document_name"            : "My_Custom_doc_name",
 "layout_reference"         : "My_Layout_100",
 "file_destination"         : "sftp",
 "generation_status"        : "FAILURE",
 "generation_error_code"    : "LAYOUT_NOT_FOUND",
 "generation_error_message" : "Layout not found",
 "generation_error_details" : "Layout reference \"My_Layout_100\" does not exist"
}

Invalid document data

Description: Document data contain errors.

Return code: 400

Response example:

{
 "document_reference"       : "INV_2081200001",
 "document_name"            : "My_Custom_doc_name",
 "layout_reference"         : "My_Layout_8",
 "file_destination"         : "sftp",
 "generation_status"        : "FAILURE",
 "generation_error_code"    : "INVALID_DOCUMENT_DATA",
 "generation_error_message" : "Invalid document data",
 "generation_error_details" : [
   {
     "property" : "items.values",
     "message" : "NULL value found, but an array is required"
   },
   {
     "property" : "",
     "message" : "The property customs_azerty is not defined and the definition does not allow additional properties"
   },
   {
     "property" : "order_information.reference_value_1",
     "message" : "The property reference_value_1 is required"
   },
   {
     "property" : "summary",
     "message" : "The property summary is required"
   }
 ]
}

The “generation_error_details” field will vary depending on the provided data. Its format will remain the same and consists of an array of the errors in received data.  

Each array item is an object containing two properties represented by the following keys:

• “property”: name of the field containing errors
• “message”: error message associated with the field

List of possible errors:  

List of possible errors for an invoice layout:

Document with same data already exists

Description: A document with the same data already exists.

Return code: 409

Response example:

{
 "document_reference"       : "INV_2081200001",
 "document_name"            : "My_Custom_doc_name",
 "layout_reference"         : "My_Layout_8",
 "file_destination"         : "binary",
 "generation_status"        : "FAILURE",
 "generation_error_code"    : "DOCUMENT_WITH_SAME_DATA_ALREADY_EXISTS",
 "generation_error_message" : "Document with same data already exists",
 "generation_error_details" : null
}

REQUIRED INFORMATION FOR INVOICE LAYOUT

To generate invoices through our API, merchants must provide us beforehand with:

• a document (e.g.: in Excel or Word format) indicating all the fields (with their exact name and position in the layout) they want to appear on API generated invoices;
• an actual invoice, with all the formatting to replicate on API generated invoices.

FULL LIST OF REQUEST PARAMETERS