Invoice Extensions

Overview

The Invoice Delivery Extension allows you to override default conventions for:

Distribution methods (email, print, SMS, E-boks, etc.)
Payment flow (default, manual, automatic)

This is particularly useful when working with OIOUBL format invoices that need custom delivery or payment behavior.

Extension Schema

The extension schema is available at:

https://app.farpay.io/xsd/common/extension.xsd

Extension Types

Force Send Method

Override the default send method for an invoice.

Force Payment Method

Force a manual payment method when the customer already has an agreement.

Implementation

Basic Extension Structure

<ExtensibleContent>
    <FarPay>
        <!-- Extension configuration here -->
    </FarPay>
</ExtensibleContent>

Force Send Method Example

<ExtensibleContent>
    <FarPay>
        <ForceSendMethod>
            <Channel>Email</Channel>
            <ToAddress>[email protected]</ToAddress>
            <Note>Custom delivery note</Note>
        </ForceSendMethod>
    </FarPay>
</ExtensibleContent>

Force Payment Method Example

<ExtensibleContent>
    <FarPay>
        <ForcePaymentMethod>
            <Method>Manual</Method>
            <Reason>Customer requested manual payment</Reason>
        </ForcePaymentMethod>
    </FarPay>
</ExtensibleContent>

Extension Properties

Force Send Method Properties

Property	Type	Description	Values
`Channel`	string	Delivery channel	Email, SMS, Print, XML
`ToAddress`	string	Delivery address	Email, phone, GLN, etc.
`Note`	string	Additional note	Custom message

Force Payment Method Properties

Property	Type	Description	Values
`Method`	string	Payment method	Manual, Automatic, Default
`Reason`	string	Reason for override	Custom explanation

Use Cases

Custom Email Delivery

<ExtensibleContent>
    <FarPay>
        <ForceSendMethod>
            <Channel>Email</Channel>
            <ToAddress>[email protected]</ToAddress>
            <Note>Please forward to appropriate department</Note>
        </ForceSendMethod>
    </FarPay>
</ExtensibleContent>

Manual Payment Override

<ExtensibleContent>
    <FarPay>
        <ForcePaymentMethod>
            <Method>Manual</Method>
            <Reason>Customer has payment agreement but requested manual processing</Reason>
        </ForcePaymentMethod>
    </FarPay>
</ExtensibleContent>

SMS Notification

<ExtensibleContent>
    <FarPay>
        <ForceSendMethod>
            <Channel>SMS</Channel>
            <ToAddress>+4512345678</ToAddress>
            <Note>Your invoice is ready for payment</Note>
        </ForceSendMethod>
    </FarPay>
</ExtensibleContent>

Integration with OIOUBL

When using OIOUBL format invoices, the extension is added to the invoice structure:

<cac:Invoice xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2">
    <!-- Standard OIOUBL content -->
    <cbc:ID>INV-001</cbc:ID>
    <cbc:IssueDate>2023-01-15</cbc:IssueDate>
    
    <!-- FarPay Extension -->
    <cac:AdditionalDocumentReference>
        <cbc:ID>FarPayExtension</cbc:ID>
        <cac:Attachment>
            <cbc:EmbeddedDocumentBinaryObject>
                <ExtensibleContent>
                    <FarPay>
                        <ForceSendMethod>
                            <Channel>Email</Channel>
                            <ToAddress>[email protected]</ToAddress>
                        </ForceSendMethod>
                    </FarPay>
                </ExtensibleContent>
            </cbc:EmbeddedDocumentBinaryObject>
        </cac:Attachment>
    </cac:AdditionalDocumentReference>
</cac:Invoice>

Delivery Integration

When creating deliveries with extensions:

{
  "DeliveryType": "Invoice",
  "DeliveryFormat": "XML",
  "File": {
    "Filename": "invoice_with_extension.xml",
    "Data": "base64_encoded_content"
  }
}

Error Handling

Common Extension Errors

Error	Description	Solution
`Invalid extension format`	Malformed extension XML	Validate against XSD schema
`Unsupported channel`	Channel not supported	Check available channels
`Invalid address format`	Address format incorrect	Verify address format
`Extension conflict`	Conflicting extensions	Remove conflicting extensions

Best Practices

Validate extensions - Always validate against the XSD schema
Test thoroughly - Test extensions in development environment
Document reasons - Always provide clear reasons for overrides
Monitor usage - Track extension usage and effectiveness
Fallback gracefully - Ensure system works without extensions

Related Endpoints

Deliveries - General delivery management
Invoices - Invoice creation and management