HiPay Enterprise – Invoice generator API
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
}
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
