Payout Deliveries (Overførselsservice)

Upload Overførselsservice (OS) bill files for payout scenarios where you need to send money to customers or partners. This section covers creating and uploading OS bill files for money transfers.

Overview

Overførselsservice bills are used for payout scenarios where you need to send money to customers or partners. They use the same Bill format as standard bills but include additional payment means information for bank transfers.

OS Bill Format Requirements

Prerequisites

X-API-KEY: Merchant API key from FarPay settings page
XSD Schema: Available at https://app.farpay.io/xsd/bills/bills.xsd
Base64 Encoding: Bill files must be base64 encoded
Overførselsservice Access: Requires special access to Overførselsservice functionality

Creating OS Bill Deliveries

Step-by-Step Process

Get the XSD document and create an OS bill file
Encode the PDF document into base64 format
Put the base64 string into the EncodedDocument container
Add PaymentMeans section with Overførselsservice configuration
Convert the entire XML document into base64 string
Create a Delivery with the following data:
- DeliveryType = Bill
- DeliveryFormat = XML
- File containing the base64 encoded OS bill

OS Bill Example

<?xml version="1.0" encoding="UTF-8"?>
<FarPayXml xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://app.farpay.io/xsd/bills.xsd">
    <Delivery>
        <Count>1</Count>
    </Delivery>
    <Bills>
        <Bill>
            <InvoiceTypeCode>PCM</InvoiceTypeCode>
            <InvoiceNumber>INV-12345</InvoiceNumber>
            <EncodedDocument>JVBERi0xLjcNCiW1t......olJUVPRg==</EncodedDocument>
            <CustomerNumber>CUST-67890</CustomerNumber>
            <Name>John Doe</Name>
            <Street>Main Street</Street>
            <HouseNumber>42</HouseNumber>
            <PostalZone>12345</PostalZone>
            <CityName>Example City</CityName>
            <Country>CountryName</Country>
            <EmailAddress>[email protected]</EmailAddress>
            <PaymentDueDate>2025-02-01</PaymentDueDate>
            <Currency>DKK</Currency>
            <ToBePayedAmount>123.45</ToBePayedAmount>
            <PaymentMeans>
                <TypeCodeID>BankTransfer</TypeCodeID>
                <PaymentChannelCode>OVERFØRSELSSERVICE</PaymentChannelCode>
                <ExtensibleContent>
                    <FarPay>
                        <PaymentMethod>Payout</PaymentMethod>
                        <Payout>
                            <SenderIdentifier scheme="BANK">rrrr:nnnnnnnn</SenderIdentifier>
                            <ReceiverIdentifier scheme="BANK">rrrr:nnnnnnnn</ReceiverIdentifier>
                        </Payout>                         
                    </FarPay>
                </ExtensibleContent>
            </PaymentMeans>
        </Bill>
    </Bills>
</FarPayXml>

API Request

POST https://api.farpay.io/v2/deliveries

Request Body:

{
  "DeliveryType": "Bill",
  "DeliveryFormat": "XML",
  "File": {
    "Filename": "os_bills.xml",
    "Data": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbm......+DQo8L0ZhclBheVhtbD4="
  }
}

Payout Identifier Schemes

Scheme	Description	Format	Example
`BANK`	Bank account details	`rrrr:aaaaaaaa`	`1234:12345678`
`CVR`	Company registration number	8 digits	`12345678`
`CPR`	Personal identification number	10 digits	`0102889999`

Payout Details

SenderIdentifier: Optional - specify if you have multiple Overførselsservice creditors
ReceiverIdentifier: Required - specifies where to send the money
Scheme: Determines the format of the identifier

OS Bill Properties

Core Bill Properties

Property	Type	Description	Required
`InvoiceTypeCode`	string	Invoice type code	Yes
`InvoiceNumber`	string	Unique invoice number	Yes
`EncodedDocument`	string	Base64 encoded PDF document	Yes
`CustomerNumber`	string	Customer reference number	Yes
`Name`	string	Customer name	Yes
`Street`	string	Street address	Yes
`HouseNumber`	string	House/building number	Yes
`PostalZone`	string	Postal code	Yes
`CityName`	string	City name	Yes
`Country`	string	Country name	Yes
`EmailAddress`	string	Customer email	Yes
`PaymentDueDate`	date	Payment due date (YYYY-MM-DD)	Yes
`Currency`	string	Currency code	Yes
`ToBePayedAmount`	decimal	Amount to be paid	Yes

Payment Means Properties (OS Bills)

Property	Type	Description	Required
`TypeCodeID`	string	Payment type (BankTransfer)	Yes
`PaymentChannelCode`	string	Payment channel (OVERFØRSELSSERVICE)	Yes
`PaymentMethod`	string	Method (Payout)	Yes
`SenderIdentifier`	object	Sender bank details	No
`ReceiverIdentifier`	object	Receiver identification	Yes

File Upload Process

Two-Step Upload for Large Files

For large OS bill files, use the two-step upload process:

Step 1: Create Delivery

{
  "DeliveryType": "Bill",
  "DeliveryFormat": "XML",
  "File": {
    "Filename": "large_os_bills.xml"
  }
}

Step 2: Upload File

PUT {FileUploadUri}

Required Headers:

x-ms-blob-type: blockblob
Content-Type: application/octet-stream

Implementation Examples

JavaScript Example

// Convert PDF to base64
const fs = require('fs');
const pdfContent = fs.readFileSync('payout_invoice.pdf');
const base64Pdf = pdfContent.toString('base64');

// Create OS bill XML
const osBillXml = `<?xml version="1.0" encoding="UTF-8"?>
<FarPayXml xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://app.farpay.io/xsd/bills.xsd">
    <Delivery>
        <Count>1</Count>
    </Delivery>
    <Bills>
        <Bill>
            <InvoiceTypeCode>PCM</InvoiceTypeCode>
            <InvoiceNumber>OS-${Date.now()}</InvoiceNumber>
            <EncodedDocument>${base64Pdf}</EncodedDocument>
            <CustomerNumber>CUST-67890</CustomerNumber>
            <Name>John Doe</Name>
            <Street>Main Street</Street>
            <HouseNumber>42</HouseNumber>
            <PostalZone>12345</PostalZone>
            <CityName>Example City</CityName>
            <Country>Denmark</Country>
            <EmailAddress>[email protected]</EmailAddress>
            <PaymentDueDate>2025-02-01</PaymentDueDate>
            <Currency>DKK</Currency>
            <ToBePayedAmount>123.45</ToBePayedAmount>
            <PaymentMeans>
                <TypeCodeID>BankTransfer</TypeCodeID>
                <PaymentChannelCode>OVERFØRSELSSERVICE</PaymentChannelCode>
                <ExtensibleContent>
                    <FarPay>
                        <PaymentMethod>Payout</PaymentMethod>
                        <Payout>
                            <SenderIdentifier scheme="BANK">1234:12345678</SenderIdentifier>
                            <ReceiverIdentifier scheme="BANK">5678:87654321</ReceiverIdentifier>
                        </Payout>                         
                    </FarPay>
                </ExtensibleContent>
            </PaymentMeans>
        </Bill>
    </Bills>
</FarPayXml>`;

// Convert XML to base64
const base64Xml = Buffer.from(osBillXml).toString('base64');

// Create delivery
const delivery = {
  DeliveryType: "Bill",
  DeliveryFormat: "XML",
  File: {
    Filename: "os_bills.xml",
    Data: base64Xml
  }
};

const response = await fetch('https://api.farpay.io/v2/deliveries', {
  method: 'POST',
  headers: {
    'X-API-KEY': 'your-api-key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(delivery)
});

Python Example

import base64
import requests

# Read PDF file
with open('payout_invoice.pdf', 'rb') as pdf_file:
    pdf_content = pdf_file.read()
    base64_pdf = base64.b64encode(pdf_content).decode('utf-8')

# Create OS bill XML
os_bill_xml = f'''<?xml version="1.0" encoding="UTF-8"?>
<FarPayXml xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://app.farpay.io/xsd/bills.xsd">
    <Delivery>
        <Count>1</Count>
    </Delivery>
    <Bills>
        <Bill>
            <InvoiceTypeCode>PCM</InvoiceTypeCode>
            <InvoiceNumber>OS-12345</InvoiceNumber>
            <EncodedDocument>{base64_pdf}</EncodedDocument>
            <CustomerNumber>CUST-67890</CustomerNumber>
            <Name>John Doe</Name>
            <Street>Main Street</Street>
            <HouseNumber>42</HouseNumber>
            <PostalZone>12345</PostalZone>
            <CityName>Example City</CityName>
            <Country>Denmark</Country>
            <EmailAddress>[email protected]</EmailAddress>
            <PaymentDueDate>2025-02-01</PaymentDueDate>
            <Currency>DKK</Currency>
            <ToBePayedAmount>123.45</ToBePayedAmount>
            <PaymentMeans>
                <TypeCodeID>BankTransfer</TypeCodeID>
                <PaymentChannelCode>OVERFØRSELSSERVICE</PaymentChannelCode>
                <ExtensibleContent>
                    <FarPay>
                        <PaymentMethod>Payout</PaymentMethod>
                        <Payout>
                            <SenderIdentifier scheme="BANK">1234:12345678</SenderIdentifier>
                            <ReceiverIdentifier scheme="BANK">5678:87654321</ReceiverIdentifier>
                        </Payout>                         
                    </FarPay>
                </ExtensibleContent>
            </PaymentMeans>
        </Bill>
    </Bills>
</FarPayXml>'''

# Convert XML to base64
base64_xml = base64.b64encode(os_bill_xml.encode('utf-8')).decode('utf-8')

# Create delivery
delivery = {
    "DeliveryType": "Bill",
    "DeliveryFormat": "XML",
    "File": {
        "Filename": "os_bills.xml",
        "Data": base64_xml
    }
}

response = requests.post(
    'https://api.farpay.io/v2/deliveries',
    headers={
        'X-API-KEY': 'your-api-key',
        'Content-Type': 'application/json'
    },
    json=delivery
)

Error Handling

Common Error Responses

Status Code	Description
`400`	Bad request - Invalid OS bill format
`401`	Unauthorized - Invalid API key or no OS access
`404`	Not found - Delivery doesn't exist

Common OS Bill Errors

Error	Description	Solution
`Invalid XML structure`	Malformed XML content	Validate against XSD schema
`Missing PaymentMeans`	OS bills require PaymentMeans section	Add PaymentMeans with Overførselsservice config
`Invalid identifier scheme`	Unsupported identifier format	Use BANK, CVR, or CPR schemes
`Missing ReceiverIdentifier`	Required for payouts	Specify receiver bank details

Best Practices

Validate XML structure - Use the XSD schema for validation
Proper identifier formats - Ensure bank account numbers follow correct format
Unique invoice numbers - Use unique identifiers for each OS bill
Handle large files - Use two-step upload for files > 10MB
Monitor processing - Check delivery status after upload
Test thoroughly - Test with small files before production
Verify OS access - Ensure your account has Overførselsservice access

Related Endpoints

Bill Deliveries - Standard bill deliveries
Deliveries - General delivery management
Payments - Payment tracking and processing