# Send EHF Invoice

The **Send EHF Invoice** endpoint allows merchants to generate and send standardized electronic invoices (EHF) to corporate customers in Norway. EHF invoices conform to national and PEPPOL regulations, enabling seamless delivery to customer accounting systems and public sector entities. This API integrates Front Payment’s digital invoicing with your order workflow — encapsulating products, billing details, due dates, and delivery preferences into an EHF-enabled invoice.  
 
Upon success, you'll receive an `orderUuid` and `customerUuid` to track the invoice lifecycle. To check invoice status [go to `Get Order Status By UUID` page](https://docs.frontpayment.no/books/fpgo-connect/page/get-order-status-by-uuid)

### Key Benefits
- **Automate invoicing workflows** and reduce manual billing overhead.  
- **Ensure compliance** with Norwegian EHF (PEPPOL) standards.  
- **Deliver invoices directly** to recipients' systems via the PEPPOL network.  
- **Monitor invoice status** or reconcile with callbacks or queries.  

### Prerequisites

Before you start the integration, make sure you have:

**1. API Access:**
* A valid API key and Bearer Token from Front Payment
* Access to the demo and production environments

**2. Technical Requirements:**
* Ability to make HTTPS API calls
* Secure storage of tokens and keys
* Callback endpoints to handle payment status updates

**3. Test Environment:**
* For testing, contact `nafees.faraz@frontpayment.no` to gain access to the demo environment

### Endpoint

```
POST https://demo-api.frontpayment.no/api/v1/connect/orders/ehf/create
```


#### Authorization


Include a **Bearer Token** in the `Authorization` header. You can obtain this token from **Front Payment**.

**Example:**  
```
Authorization: Bearer YOUR_FRONTPAYMENT_BEARER_TOKEN
```

### Request Payload

Send the following parameters as a JSON object in the request body:

```json
{
    "products": [
        {
            "name": "Hair Wash",
            "productId": "VFDDF",
            "quantity": "1",
            "rate": 51,
            "discount": 0,
            "tax": "0",
            "amount": 51
        }
    ],
    "orderSummary": {
        "subTotal": "51.00",
        "totalTax": "0.00",
        "totalDiscount": "0.00",
        "grandTotal": "51.00"
    },
    "orderDate": "1703040812",
    "customerDetails": {
        "countryCode": "+47",
        "msisdn": "46567468",
        "email": "test@yopmail.com",
        "name": "Kari Nordmann",
        "preferredLanguage": "en",
        "organizationId": "123456789,
        "address": {
            "street": "Luramyrveien 65",
            "zip": "4313",
            "city": "Sandnes",
            "country": "NO"
        }
    },
    "invoiceInterval": 0,
    "invoiceMaturity": 10,
    "invoiceFeeApplicable": true,
    "separateInvoices": true,
    "referenceNo": null,
    "customerReference": null,
    "callback": {
        "callbackUrl": "https://example.com/callback-url"
    }
}
```

### Validation Rules

Make sure your request meets the following requirements:

<table style="width: 100%">
  <thead>
    <tr>
      <th style="width: 260px">Field</th>
      <th style="width: 80px">Type</th>
      <th>Description</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><code>products.*.name</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> Name of the product.</td>
    </tr>
    <tr>
      <td><code>products.*.productId</code></td>
      <td><code>string</code></td>
      <td><strong>Optional</strong> Unique identifier for the product.</td>
    </tr>
    <tr>
      <td><code>products.*.quantity</code></td>
      <td><code>numeric</code></td>
      <td><strong>Required</strong> Quantity of the product.</td>
    </tr>
    <tr>
      <td><code>products.*rate</code></td>
      <td><code>numeric</code></td>
      <td><strong>Required</strong> Rate per unit of the product.</td>
    </tr>
    <tr>
      <td><code>products.*.discount</code></td>
      <td><code>numeric</code></td>
      <td><strong>Optional</strong> Discount applied to the product.</td>
    </tr>
    <tr>
      <td><code>products.*.tax</code></td>
      <td><code>numeric</code></td>
      <td><strong>Required</strong> Tax rate must be (e.g., <code>0</code>, <code>12</code>, <code>15</code>, <code>25</code>), Unless you have other configuration.</td>
    </tr>
    <tr>
      <td><code>products.*.amount</code></td>
      <td><code>numeric</code></td>
      <td><strong>Required</strong> Total amount for the product line item.</td>
    </tr>
    <tr>
      <td><code>orderSummary.subTotal</code></td>
      <td><code>numeric</code></td>
      <td><strong>Required</strong> Subtotal of all products before tax and discount.</td>
    </tr>
    <tr>
      <td><code>orderSummary.totalTax</code></td>
      <td><code>numeric</code></td>
      <td><strong>Required</strong> Total tax for the order.</td>
    </tr>
    <tr>
      <td><code>orderSummary.totalDiscount</code></td>
      <td><code>numeric</code></td>
      <td><strong>Required</strong> Total discount for the order.</td>
    </tr>
    <tr>
      <td><code>orderSummary.grandTotal</code></td>
      <td><code>numeric</code></td>
      <td><strong>Required</strong> Grand total of the order.</td>
    </tr>
    <tr>
      <td><code>orderDate</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> Unix timestamp for the Date of the order.</td>
    </tr>
    <tr>
      <td><code>customerDetails.countryCode</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> Country code for the customer's phone number (e.g., "+47").</td>
    </tr>
    <tr>
      <td><code>customerDetails.msisdn</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> Mobile Subscriber ISDN Number (phone number).</td>
    </tr>
    <tr>
      <td><code>customerDetails.email</code></td>
      <td><code>email</code></td>
      <td><strong>Required</strong> Customer's email address.</td>
    </tr>
    <tr>
      <td><code>customerDetails.name</code></td>
      <td><code>email</code></td>
      <td><strong>Required</strong> Customer's full name.</td>
    </tr>
    <tr>
      <td><code>customerDetails.preferredLanguage</code></td>
      <td><code>string</code></td>
      <td><strong>Optional</strong> Customer preferred language. Available languages are <code>en</code>, <code>no</code>, <code>sv</code>, <code>da</code>, <code>de</code>. If nothing is given it will set default to <code>no</code>.</td>
    </tr>
    <tr>
      <td><code>customerDetails.organizationId</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> Organization identification number, must contain only numbers and cannot contain spaces</td>
    </tr>
    <tr>
      <td><code>customerDetails.address.street</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> Street address of the customer.</td>
    </tr>
    <tr>
      <td><code>customerDetails.address.zip</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> Zip code of the customer's address.</td>
    </tr>
    <tr>
      <td><code>customerDetails.address.city</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> City of the customer's address.</td>
    </tr>
    <tr>
      <td><code>customerDetails.address.country</code></td>
      <td><code>string</code></td>
      <td><strong>Required</strong> ISO Alpha-2 country code (e.g., <code>NO</code>). Custom validation <code>IsoAlpha2Country</code> applies.</td>
    </tr>
    <tr>
      <td><code>invoiceInterval</code></td>
      <td><code>numeric</code></td>
      <td><strong>Optional</strong> Default value is = <code>0</code>. You can change it to <code>0</code>, <code>1</code>, <code>2</code>. Daily = <code>0</code>, Once a month = <code>1</code>, Twice a month = <code>2</code>.</td>
    </tr>
    <tr>
      <td><code>invoiceFeeApplicable</code></td>
      <td><code>boolean</code></td>
      <td><strong>Required</strong> Default value is <code>true</code>.</td>
    </tr>
    <tr>
      <td><code>invoiceMaturity</code></td>
      <td><code>numeric</code></td>
      <td><strong>Optional</strong> Default value is <code>14</code>. if you want to set the value then give <code>14</code>, <code>30</code> or <code>45</code>.</td>
    </tr>
    <tr>
      <td><code>separateInvoices</code></td>
      <td><code>boolean</code></td>
      <td><strong>Optional</strong> Default value is <code>true</code>.</td>
    </tr>
    <tr>
      <td><code>referenceNo</code></td>
      <td><code>string</code></td>
      <td><strong>Nullable</strong> Any reference number.</td>
    </tr>
    <tr>
      <td><code>customerReference</code></td>
      <td><code>string</code></td>
      <td><strong>Nullable</strong> Any value for customer reference.</td>
    </tr>
    <tr>
      <td><code>callback.callbackUrl</code></td>
      <td><code>url</code></td>
      <td><strong>Required</strong> To receive real-time notifications on order state changes, you must provide a callback url. This is an server-to-server <code>HTTP GET</code> request.</td>
    </tr>
  </tbody>
</table>


### Response

A successful request will return a `201 Created` status with the following JSON payload:

```json
{
    "status_code": 201,
    "status_message": "OK",
    "message": "orderAddedSuccessfully",
    "is_data": false,
    "data": {
        "uuid": "ODR3506777330",
        "customerUuid": "CSRT3463048878"
    }
}
```

API returns a `500` or `510` error, it means something failed on the server side

```json
{
    "status_code": 500,
    "status_message": "Internal Dependency Error",
    "message": "internalErrorOccurredPleaseTryAgainLater",
    "is_error": true,
    "errors": {
        "happenedAt": "String",
        "internalErrorDetails": "Array"
    }
}
```

```json
{
    "status_code": 510,
    "status_message": "Execution Exception Occurred",
    "message": "somethingWentWrong",
    "is_error": true,
    "errors": "Array"
}
```

### Notifications via Callback URL

The `callbackUrl` is an endpoint on your server that our system will call via an `HTTP GET` request whenever the status of the specified order changes from its initial state. 

See the link below to understand how to work with the callback URL on your side and how to verify the request sent from our side.

[Go to `Notication Via Callback Url` Page](https://docs.frontpayment.no/books/fpgo-connect/page/notifications-via-callback-url)