# Submit Instalment Bill

This operation accepts a PDF along with the business case information, which is to be included as XML attachment. The provided PDF must not contain an XML attachment. Ideally the PDF conforms to the PDF/A-3b, if not, conversion is attempted. Please note that PDF format conversion may fail due to various technical reason.

Endpoint: POST /api/v1/business-cases/instalment-bill
Version: 1.1
Security: X-API-Key

## Query parameters:

  - `processingMode` (string, required)
    STAGE: BusinessCase gets validated and staged (proceed via web UI), DELIVER: BusinessCase gets validated, processed and delivered to the bill recipient
    Enum: "STAGE", "DELIVER"

## Request fields (application/json):

  - `pdf` (string)

  - `businessCase` (object)
    Instalment Bill

  - `businessCase.referenceNumber` (string, required)

  - `businessCase.businessCaseDate` (string, required)

  - `businessCase.totalAmount` (object, required)
    The amount of the business case (amount incl. VAT + currency code, e.g. CHF 1183.46).
Must be matching with the total amount (totalAmount), if business case is an invoice, reminder or donation inquiry.

  - `businessCase.totalAmount.value` (number)
    - max. 99'999'999.99 for invoices, payments by instalments, reminders, credit notes and donation inquiries
- min. - 99'999'999.99, max 99'999'999.99 for advices
- Amount must be greater than 0 for invoices, payments by instalments, reminders and donation inquiries.
- Amount must be ≥ 0 for credit notes.
- If an IBAN or QR-IBAN is used for invoices or payments by instalments, the amount does not have to be supplied (compatibility QR invoice).

  - `businessCase.totalAmount.currencyCode` (string, required)
    Currency code according to ISO 4217. When using QR-IBAN, only CHF and EUR are allowed.

  - `businessCase.referencedBill` (object)

  - `businessCase.billRecipient` (object, required)

  - `businessCase.billRecipient.emailAddress` (string)

  - `businessCase.billRecipient.enterpriseIdentificationNumber` (string)

  - `businessCase.billRecipient.billRecipientSixId` (string)

  - `businessCase.billRecipient.name` (string, required)

  - `businessCase.billRecipient.address` (object, required)

  - `businessCase.billRecipient.address.structuredAddress` (object)

  - `businessCase.billRecipient.address.structuredAddress.street` (string)

  - `businessCase.billRecipient.address.structuredAddress.buildingNumber` (string)

  - `businessCase.billRecipient.address.structuredAddress.city` (string, required)

  - `businessCase.billRecipient.address.structuredAddress.postalCode` (string, required)

  - `businessCase.billRecipient.address.structuredAddress.countryCode` (string, required)
    Two-letter ISO country code according to ISO 3166-1.

  - `businessCase.paymentsByInstalments` (object, required)

  - `businessCase.paymentsByInstalments.paymentByInstalments` (array, required)

  - `businessCase.paymentsByInstalments.paymentByInstalments.externalPaymentByInstalmentsId` (string, required)

  - `businessCase.paymentsByInstalments.paymentByInstalments.description` (string)

  - `businessCase.paymentsByInstalments.paymentByInstalments.isTotalAmountHidden` (boolean)

  - `businessCase.paymentsByInstalments.paymentByInstalments.isTotalPaymentOption` (boolean)

  - `businessCase.paymentsByInstalments.paymentByInstalments.instalments` (object, required)

  - `businessCase.paymentsByInstalments.paymentByInstalments.instalments.instalment` (array, required)

  - `businessCase.paymentsByInstalments.paymentByInstalments.instalments.instalment.externalInstalmentId` (string, required)

  - `businessCase.paymentsByInstalments.paymentByInstalments.instalments.instalment.paymentInformation` (object, required)

  - `businessCase.paymentsByInstalments.paymentByInstalments.instalments.instalment.paymentInformation.accountAndReference` (object, required)
    Information about the account and reference of the invoice issuer.

  - `businessCase.paymentsByInstalments.paymentByInstalments.instalments.instalment.paymentInformation.accountAndReference.accountHolder` (object)
    In case the account holder differs from the biller use this element to provide the account holder name and address.

  - `businessCase.paymentsByInstalments.paymentByInstalments.instalments.instalment.paymentInformation.accountAndReference.accountHolder.name` (string, required)
    Name of the account holder.

  - `businessCase.paymentsByInstalments.paymentByInstalments.instalments.instalment.paymentInformation.accountAndReference.generic` (object, required)

  - `businessCase.paymentsByInstalments.paymentByInstalments.instalments.instalment.paymentInformation.accountAndReference.generic.referenceType` (string, required)
    Enum: "QRR", "SCOR", "NON"

  - `businessCase.paymentsByInstalments.paymentByInstalments.instalments.instalment.paymentInformation.accountAndReference.generic.referenceStructured` (string)
    Reference number, structured payment reference.
Note: the reference is either a QR reference or creditor reference (ISO 11649).

QR Reference: 27 characters, numerical; check digit computation with Modulus 10 recursive (27th position of the reference).

Creditor Reference (ISO 11649): up to 25 characters, alphanumeric.

When using QR-IBAN, this element must be filled with the QR Reference.
When using IBAN and referenceType SCOR, this element must be filled with the Creditor Reference.
When using IBAN and referenceType NON, this element is not permitted to be filled.

  - `businessCase.paymentsByInstalments.paymentByInstalments.instalments.instalment.paymentInformation.accountAndReference.generic.referenceUnstructured` (string)
    Unstructured message

  - `businessCase.paymentsByInstalments.paymentByInstalments.instalments.instalment.paymentInformation.accountAndReference.generic.iban` (string, required)
    Credit account of the invoice issuer (IBAN or QR-IBAN). See also ISO 13616-1.
The usage of IBAN or QR-IBAN is only permitted with country codes CH or LI and 21 alphanumeric characters.

Example:    CH9300762011623852957
LI21088100002324013AA

Must contain country code CH or LI, otherwise the business case will be denied.
Must be matching with a credit account that is specified in the infrastructure in the master data of the invoice issuer, otherwise the business case will be denied.
    Example: "CH9300762011623852957"

  - `businessCase.paymentsByInstalments.paymentByInstalments.instalments.instalment.paymentInformation.amount` (object, required)
    The amount of the business case (amount incl. VAT + currency code, e.g. CHF 1183.46).
Must be matching with the total amount (totalAmount), if business case is an invoice, reminder or donation inquiry.

  - `businessCase.paymentsByInstalments.paymentByInstalments.instalments.instalment.paymentInformation.dueDate` (string, required)
    Due date. In the case of donation inquiries, the due date acts as a proposal for the payment date.

At time of submission, cannot be set to more than 3 years in the future (1095 days) for payment mode ebill.
At time of submission, cannot be set to more than 30 days in the future for payment mode ebill debit.
At time of submission, cannot be older than 90 days.

  - `businessCase.paymentsByInstalments.paymentByInstalments.instalments.instalment.paymentInformation.payableAmountCanBeModified` (boolean, required)
    If true, then the provided invoice amount is permitted to be altered. If the invoice amount is not provided, the value must be set to true.

  - `businessCase.workflow` (object)
    Information about the workflow. Auxiliary data that can be used for pre-registering a business case in bill recipients ERP/bookkeeping.

  - `businessCase.workflow.vatEnterpriseIdentificationNumbers` (object)
    Value Added Tax Enterprise Identification Numbers (VAT-UIDs) of the invoice issuer

  - `businessCase.workflow.vatEnterpriseIdentificationNumbers.vatEnterpriseIdentificationNumber` (array)
    VAT-UID of the invoice issuer. Presentation without punctuation (e.g. CHE123456789MWST).

  - `businessCase.workflow.deliveryDateStart` (string)
    Start date of the service provision, in case it is different than deliveryDateEnd

  - `businessCase.workflow.deliveryDateEnd` (string)
    Delivery date or end date of the service provision

  - `businessCase.workflow.netAmount` (object)
    Total invoice amount without VAT (e.g. CHF 1095.80)

  - `businessCase.workflow.amountPaid` (object)
    Sum of the amount that was paid by the invoice recipient in advance (without VAT-relevant advance invoice). The outstanding total invoice amount to be paid corresponds to the element "totalAmount".

  - `businessCase.workflow.vatRates` (object)
    Grouping of VAT rates

  - `businessCase.workflow.vatRates.vatRate` (array, required)
    VAT information per VAT rate

  - `businessCase.workflow.vatRates.vatRate.percentage` (number)
    VAT rate in percent (example: 8%)

  - `businessCase.workflow.vatRates.vatRate.taxBaseAmount` (object)
    Tax base amount (example: CHF 1095.80)

  - `businessCase.workflow.vatRates.vatRate.taxAmount` (object)
    Amount of a tax to be owed (example: CHF 87.66)

  - `businessCase.workflow.caseReferenceForBillRecipient` (string)
    Association reference to be used by the invoice recipient to allocate the business case in his bookkeeping.

## Response 201 fields (application/json):

  - `id` (integer, required)
    A unique SIX ID for this business case. Property must not be given when creating a new business case.
    Example: "BCID0FB909852BBC4D06AD8336AAE87D7FC9"

  - `type` (string, required)
    the type of the business case
    Enum: "Bill", "InstalmentBill", "Advice", "CreditNote", "Reminder", "DonationInquiry"

  - `billerSixId` (string, required)
    Biller SIX ID
    Example: "BIID0000123456"

  - `referenceNumber` (string)
    A business case reference given by the biller. Must be unique in combination with the billerId.
    Example: "2018-123456-22"

  - `referencedBill` (object)
    The business case can only reference bills or instalment bills.

  - `referencedBill.businessCaseSixId` (string)
    Business Case SIX ID
    Example: "BCID0FB909852BBC4D06AD8336AAE87D7FC9"

  - `referencedBill.referenceNumber` (string, required)
    The reference number of the referenced bill.
    Example: "2018-123456-22"

  - `businessCaseDate` (string, required)
    The business case date (ISO-8601 format), can not be more than 90 days in the past on the date it was created. Cannot be in the future.
    Example: "Fri Dec 22 01:00:00 CET 2017"

  - `status` (string)
    the status of the business case
    Enum: "OPEN", "APPROVED", "REJECTED", "COMPLETED"

  - `processingStatus` (string)
    the processing status of the business case
    Enum: "STAGED", "INVALID", "PROCESSING", "FAILED", "DELIVERED"

  - `totalAmount` (object, required)
    An amount whose value may be omitted.

  - `totalAmount.value` (number)
    The amount value. Take care when using JavaScript libraries to parse this value - it should be treated as a financial amount and therefore not as a floating point number but rather using a precise decimal representation (like BigDecimal in Java).  :   :
    Example: 99.99

  - `totalAmount.currencyCode` (string, required)
    The amount currency code according to ISO-4217.
    Example: "CHF"

## Response 400 fields (application/json):

  - `status` (integer)
    The HTTP status code generated by the origin server for this occurrence of the problem.
    Example: 400

  - `message` (string)
    A human readable explanation specific to this occurrence of the problem.
    Example: "The submitted request contains invalid or missing data which can not be processed."

  - `fieldErrors` (array)

  - `fieldErrors.fieldName` (string)
    the name of the field with the error
    Example: "localizedData.ger.address.city"

  - `fieldErrors.message` (string)
    the message describing the error
    Example: "size must be between 1 and 35"

  - `fieldErrors.rejectedValue` (string)
    the provided value which was rejected if available
    Example: "Very Long Invalid City Name Which Is Rejected"