Sandbox.Invoice Service - Invoice Service 
Page of - last modified by Fredrik Köhler on 2018/12/07 12:59 
Invoice Service 

Fredrik Köhler

2018/12/07 12:59
Table of Contents
Introduction
What you need before you get started
What you should do, step by step
Step 1 Create CUSIN file
Create file
Add CUSIN Header
Distribution Date
CUSINInfo
Customer info
Invoices
Transfer the file
Step 2: Response Files
Bill Journal
Customer Journal
Step 3: Accounting and Disbursement
Accounting Detail
Balance Report
PayEx Connect API

 The Invoice Service documentation is incomplete. Please beware that the information given here is subject to change at any time, that information might be missing and even be incorrect. Use with caution!
Introduction
PayEx CUSIN is a file format for customers to send customer and invoice information to PayEx. The documentation targets technical system integrators and developers implementing PayEx Invoice Service.
Invoice Service includes
�	Invoicing
�	Accounts Receivable
�	Distribution
�	Collection
Supporting the following features
�	Accounting
�	Reports & statistics
�	PayEx 360 (web based interface)
�	PayEx Connect (API)
What you need before you get started
�	sFTP Client
�	Agreement that includes PayEx Invoice Service (CUSIN)
�	Obtained credentials from PayEx
�	Basic understanding of file name convention and file format limitations
To get a grasp of what we expect of your implementation when you are finished, we recommend that you take a peek at the following diagram before you get started.
What you should do, step by step
Below is an example provided in .XML
Note that the example is for a basic usage of the file format. It is provided to help understanding the file format and give the implementation a head start. For more extensive usage of the file format, head over to the API reference.
If you encounter any problem with the implementation, please visit the troubleshooting section.
Step 1 Create CUSIN file
Create file
Create a file with extension .XML and UTF-8 encoding. Name it according to the filename convention.
Add a row on root level with XML declaration, with XML-version 1.0 and UTF-8 encoding.
    <︖xml version="1.0" encoding="utf-8"︖>
You can read more about this here.
Add CUSIN Header
Add a CUSIN Header at root level with the following attributes.
�	XSD version
�	Createion date and time
�	Company number
�	Company name
  <︖xml version="1.0" encoding="utf-8"︖>
  <CUSIN Version="2.0" CreatedDateTime="2017-12-07T14:54:55" CompanyName="Test Company" CompanyNo="9999">
  </CUSIN>
You can read more about this here.
Distribution Date
Set your distribution date.
Add a child element DistributionDate. This can be set to a date (in the future) of your choosing or you can leave it up to us.
In this example we have set the value toAsSoonAsPossible.
<︖xml version="1.0" encoding="utf-8"︖>
<CUSIN Version="2.0" CreatedDateTime="2017-12-07T14:54:55" CompanyName="Test Company" CompanyNo="9999">
<DistributionDate>
  <AsSoonAsPossible />
</DistributionDate>
</CUSIN>
You can read more about this here.  
CUSINInfo
Define CUSINInfo per customer.
In order to define the CUSINInfo per customer you need to do add the following child elements:
Add CustomerNo, CustomerInfo and Invoices to the CUSINInfo parent.
<︖xml version="1.0" encoding="utf-8"︖>
<CUSIN Version="2.0" CreatedDateTime="2017-12-07T14:54:55" CompanyName="Test Company" CompanyNo="9999">
<DistributionDate>
  <AsSoonAsPossible />
</DistributionDate>
<CUSINInfo>
  <CustomerNo>1</CustomerNo>
  <CustomerInfo/>
  <Invoices/>
</CUSINInfo>
</CUSIN>
You can read more about this here.
We will go into more details related to CustomerInfo element and Invoices element in the coming steps.
Customer info
In order to define the CustomerInfo per customer you need to do add the following child elements:
Add Name, RegNo, DistributionAddressInfo, PaymentInfo and   DistributionInfo to the CustomerInfo parent.
<︖xml version="1.0" encoding="utf-8"︖>
<CUSIN Version="2.0" CreatedDateTime="2017-12-07T14:54:55" CompanyName="Test Company" CompanyNo="9999">
    <DistributionDate>
          <AsSoonAsPossible />
    </DistributionDate>
    <CUSINInfo>
          <CustomerNo>1</CustomerNo>
          <CustomerInfo>
                <Name>Firstname Lastname</Name>
                <RegNo CountryCode="SE">400513-0564</RegNo>
                <DistributionAddressInfo>
                      <Addresses>
                            <Address AddressType="LegalAddress">
                                  <Addressee>Firstname Lastname</Addressee>
                                  <StreetAddress>Street 2</StreetAddress>
                                  <ZipCode>12345</ZipCode>
                                  <City>Big city</City>
                                  <CoAddress>CoAdress</CoAddress>
                                  <CountryCode>SE</CountryCode>
                            </Address>
                            <Address AddressType="BillingAddress">
                                  <Addressee>Firstname Lastname</Addressee>
                                  <StreetAddress>Another street 10</StreetAddress>
                                  <ZipCode>53214</ZipCode>
                                  <City>Big city</City>
                                  <CoAddress>CoAdress</CoAddress>
                                  <CountryCode>SE</CountryCode>
                            </Address>
                      </Addresses>
                      <E-MailAddress>test@test.com</E-MailAddress>
                </DistributionAddressInfo>
                <PaymentInfo>
                      <Set>
                            <PaymentRules>
                                  <PaymentRule Rule="UseBGAGSE">
                                        <Value>1</Value>
                                  </PaymentRule>
                            </PaymentRules>
                      </Set>
                </PaymentInfo>
                <DistributionInfo>
                      <Set>
                            <BillTypes>
                                  <BillType DistributionBillType="I_Invoice">
                                        <DistributionType>PostalService</DistributionType>
                                  </BillType>
                            </BillTypes>
                      </Set>
                </DistributionInfo>
          </CustomerInfo>
          <Invoices/>
    </CUSINInfo>
</CUSIN>
You can read more about this here.
Invoices
In order to define the Invoice(s) per customer you need to do add the following child elements:
Add InvoiceNo, InvoiceDate, Amount and   DistributionInfo to the Invoices parent.

<︖xml version="1.0" encoding="utf-8"︖>
<CUSIN Version="2.0" CreatedDateTime="2017-12-07T14:54:55" CompanyName="Test Company" CompanyNo="9999">
    <DistributionDate>
          <AsSoonAsPossible />
    </DistributionDate>
    <CUSINInfo>
          <CustomerNo>1</CustomerNo>
          <CustomerInfo>
                <Name>Firstname Lastname</Name>
                <RegNo CountryCode="SE">400513-0564</RegNo>
                <DistributionAddressInfo>
                      <Addresses>
                            <Address AddressType="LegalAddress">
                                  <Addressee>Firstname Lastname</Addressee>
                                  <StreetAddress>Street 2</StreetAddress>
                                  <ZipCode>12345</ZipCode>
                                  <City>Big city</City>
                                  <CoAddress>CoAdress</CoAddress>
                                  <CountryCode>SE</CountryCode>
                            </Address>
                            <Address AddressType="BillingAddress">
                                  <Addressee>Firstname Lastname</Addressee>
                                  <StreetAddress>Another street 10</StreetAddress>
                                  <ZipCode>53214</ZipCode>
                                  <City>Big city</City>
                                  <CoAddress>CoAdress</CoAddress>
                                  <CountryCode>SE</CountryCode>
                            </Address>
                      </Addresses>
                      <E-MailAddress>test@test.com</E-MailAddress>
                </DistributionAddressInfo>
                <PaymentInfo>
                      <Set>
                            <PaymentRules>
                                  <PaymentRule Rule="UseBGAGSE">
                                        <Value>1</Value>
                                  </PaymentRule>
                            </PaymentRules>
                      </Set>
                </PaymentInfo>
                <DistributionInfo>
                      <Set>
                            <BillTypes>
                                  <BillType DistributionBillType="I_Invoice">
                                        <DistributionType>PostalService</DistributionType>
                                  </BillType>
                            </BillTypes>
                      </Set>
                </DistributionInfo>
          </CustomerInfo>
          <Invoices>
                <InvoiceWithDistribution>
                      <InvoiceNo>3210</InvoiceNo>
                      <InvoiceDate>2017-12-07</InvoiceDate>
                      <Amount Currency="SEK">
                            <AmountExclVat>1000.00</AmountExclVat>
                            <VatAmount>250.00</VatAmount>
                      </Amount>
                      <DistributionInfo>
                            <InvoicePrintInfo>
                                  <InvoicePrintBlocks>
                                        <StandardPrintBlock>
                                              <BasePrintBlock>
                                                    <SubOrderBlocks>
                                                          <SubOrderBlock TableType="A7">
                                                                <ColumnHeadLine>
                                                                      <Columns>
                                                                            <Column ColumnNo="1">
                                                                                  <Text>Article</Text>
                                                                            </Column>
                                                                            <Column ColumnNo="2">
                                                                                  <Text>Description</Text>
                                                                            </Column>
                                                                            <Column ColumnNo="3">
                                                                                  <Text>Quantity</Text>
                                                                            </Column>
                                                                            <Column ColumnNo="4">
                                                                                  <Text>Unit</Text>
                                                                            </Column>
                                                                            <Column ColumnNo="5">
                                                                                  <Text>Unit Price</Text>
                                                                            </Column>
                                                                            <Column ColumnNo="6">
                                                                                  <Text>Discount</Text>
                                                                            </Column>
                                                                            <Column ColumnNo="7">
                                                                                  <Text>Amount</Text>
                                                                            </Column>
                                                                      </Columns>
                                                                </ColumnHeadLine>
                                                                <Rows>
                                                                      <Row>
                                                                            <Columns>
                                                                                  <Column ColumnNo="1">
                                                                                        <Text>231</Text>
                                                                                  </Column>
                                                                                  <Column ColumnNo="2">
                                                                                        <Text>Monthly fee</Text>
                                                                                  </Column>
                                                                                  <Column ColumnNo="3">
                                                                                        <Text>1.00</Text>
                                                                                  </Column>
                                                                                  <Column ColumnNo="4">
                                                                                        <Text></Text>
                                                                                  </Column>
                                                                                  <Column ColumnNo="5">
                                                                                        <Text>1000,00</Text>
                                                                                  </Column>
                                                                                  <Column ColumnNo="6">
                                                                                        <Text></Text>
                                                                                  </Column>
                                                                                  <Column ColumnNo="7">
                                                                                        <Text>1000,00</Text>
                                                                                  </Column>
                                                                            </Columns>
                                                                      </Row>
                                                                      <Row>
                                                                            <Columns>
                                                                                  <Column ColumnNo="1">
                                                                                        <Text> </Text>
                                                                                  </Column>
                                                                            </Columns>
                                                                      </Row>
                                                                </Rows>
                                                          </SubOrderBlock>
                                                          <SubOrderBlock TableType="A3">
                                                                <Rows>
                                                                      <Row>
                                                                            <Columns>
                                                                                  <Column ColumnNo="2">
                                                                                        <Text>Amount excl. VAT</Text>
                                                                                  </Column>
                                                                                  <Column ColumnNo="3">
                                                                                        <Text>1000,00</Text>
                                                                                  </Column>
                                                                            </Columns>
                                                                      </Row>
                                                                      <Row>
                                                                            <Columns>
                                                                                  <Column ColumnNo="2">
                                                                                        <Text>VAT</Text>
                                                                                  </Column>
                                                                                  <Column ColumnNo="3">
                                                                                        <Text>250,00</Text>
                                                                                  </Column>
                                                                            </Columns>
                                                                      </Row>
                                                                      <Row>
                                                                            <Columns>
                                                                                  <Column ColumnNo="2">
                                                                                        <Text>VAT 25%</Text>
                                                                                  </Column>
                                                                                  <Column ColumnNo="3">
                                                                                        <Text>250,00 (1000,00)</Text>
                                                                                  </Column>
                                                                            </Columns>
                                                                      </Row>
                                                                </Rows>
                                                          </SubOrderBlock>
                                                    </SubOrderBlocks>
                                              </BasePrintBlock>
                                        </StandardPrintBlock>
                                  </InvoicePrintBlocks>
                            </InvoicePrintInfo>
                      </DistributionInfo>
                </InvoiceWithDistribution>
          </Invoices>
    </CUSINInfo>
</CUSIN>
You can read more about this here.

The XML-file must be validated with the lastest XML Schema Definition (XSD).
The XSD-file is found here.

Transfer the file
When you have transferred the file via FTP you'll get a receipt and an errorlog if something went wrong.

When Cusin is processed, a receipt will be created showing numbers of processed customers, numbers of processed invoices and total amount.
�	Record Description
�	Example file
�	XSD

If errors occur during processing of the Cusin-file an errorlog will be created. Errors may refer to insufficient customer information, invoice information or format errors.
�	Example file
�	XSD
Step 2: Response Files
Bill Journal
Bill Journal is the format used to notify changes in invoice status, i.e. claim level, invoice status (closed), complaint, respite,   etc.
�	Record Description
�	Example file
�	XSD
Customer Journal
Customer Journal is the format used to notify changes in customer information, i.e. new legal address, activation/cancellation of consent, customer status "deceased", etc
�	Record Description
�	Example file
�	XSD
Step 3: Accounting and Disbursement
Accounting Detail
Bookkeeping data is produced on two levels. Files are exported from PayEx on a daily schedule.
l describes the accounting records on a   transaction level. Includes invoice number, book account, amount, value date, etc.
�	Record Description
�	Example file
�	XSD
 describes the accounting records on an aggregated level. Includes total amounts per book account.
�	Record Description (SE)
�	Record Description (EN)
�	Example file
Balance Report
Balance Report (Client Asset Disbursement) includes:
�	Summary and specification of total amount to be paid out
�	Each record of "Client asset disbursement" in the Balance Report is equal to the total amount of Accounting Detail for the specified period.
�	Fees deducted from amount to be paid out, or (when applicable) fees to be invoiced separatly.

�	Example file

�	Example file
PayEx Connect API
PayEx Connect is a Web Service system that enables integrated access to PayEx services in a controlled and secure manner.
Access to this services requires explicit permissions on a company level and on a method level.
Manual Common describes the prerequisites needed before you start to integrate a system with PayEx Connect.
Manual Sample Service describes web methods used in sample scenarios.
External Services describes Invoice Services covering the following methods:
�	Get Invoice Information
�	Get Invoice document in the format of PDF
�	Get Customer Information