InvoiceCreated Request

The "invoiceCreated" request is used to set the customer's payment due date ("invoice" and "transaction credit CHE") / start the debit process ("Direct Debit" and "PayLater"). This process is called the "activation" of the debt and has to be triggered for each order prior to the invoice being printed. Only if the BillPay XML service response indicates no error (error_code="0"), is all the necessary data for the invoice document available. For the payment methods Direct Debit and PayLater, this process will set the debit date for the funds to be drawn from the customer's bank account.

XML Header

<?xml version="1.0" encoding="UTF-8"?>

Data Node

Attribute Typ Mögliche Werte Details
version String - Version number of the API
<data api_version="1.5.11">
    <!-- Request Daten -->
</data>

Default Params Node

Attribute Typ Details
mid Int Your merchant ID
pid Int Your portal ID
bpsecure String MD5 hash of the security key generated for this portal. (generated and delivered by BillPay)
    <default_params 
        mid="4441" 
        pid="6021" 
        bpsecure="25d55ad283aa400af464c76d713c07ad"/>

Invoice Params Node

Attribute Mandatory? Type Possible Values Details
carttotalprice + Int N..7 net value of the order total (1,00 EUR = 100)
carttotalgross + Int N..7 Current gross total order value (1,00 EUR = 100)
rebate + Int N..7 positive net value of all rebates, coupons and all other positions that affect the order total value (1,00 EUR = 100)
rebategross + Int N..7 positive gross value of all rebates, coupons and all other positions that affect the order total value (1,00 EUR = 100)
shippingname + String AN..50 Shipping method name (e.g. "Express")
shippingprice + Int N..7 net value of all order specific (shipping) fees (e.g. shipping, express fee) (1,00 EUR = 100)
shippingpricegross + Int N..7 gross value of all order specific (shipping) fees (e.g. shipping, express fee) (1,00 EUR = 100)
currency + String Vorgabe ISO 4217 3-digit currency code (e.g. "EUR")
reference + String AN..40 Unique order ID in the merchant system (allowed characters: 0-9,a-z,A-Z,.,-,_,/)
delayindays + Int N..3 Amount of days that will be added to the payment due date (e.g. in case of delayed shipping)
is_partial + Boolean N..1 0: Shipping/Activation of the full order
1: Partial shipment / partial activation
invoice_number + (by partial activation) String AN..40 Merchant’s partially shipped invoice number
article_data + (by partial activation) Parent node containing the articles
articleid + (by partial activation) String AN..20 Unique article ID
articlequantity + (by partial activation) Int N..7 Article quantity
articlename + (by partial activation) String AN..50 Article name
articleprice + (by partial activation) Int N..7 Article net price (smallest currency unit; 1,00 EUR = 100)
articlepricegross + (by partial activation) Int N..7 Article gross price (smallest currency unit; 1,00 EUR = 100)

*Please Note: Using the standard configuration and integration, only full orders can be activated. If you need to activate only parts of the total order value / parts of the shopping cart, the following flag needs to be set and the feature needs to be activated for you by the BillPay integration support team.

Partial Shipment (partial activation) is only possible for the following payment methods:

Payment Method ID Payment Method
1 Invoice
2 Direct Debit

    <invoice_params 
      carttotalgross="43000" 
      currency="EUR" 
      reference="1773673332" 
      delayindays="0" />

Full XML example (activation of full cart)

<?xml version="1.0" encoding="UTF-8"?>
<data api_version="1.5.11">
   <default_params mid="4441" pid="6021" bpsecure="25d55ad283aa400af464c76d713c07ad" />
   <invoice_params carttotalgross="43000" currency="EUR" reference="1773673332" delayindays="0" />
</data>   

Full XML example (partial activation of article #1234)

<?xml version="1.0" encoding="UTF-8"?>
<data api_version="1.5.11">
   <default_params mid="4441" pid="6021" bpsecure="25d55ad283aa400af464c76d713c07ad" />
   <invoice_params carttotalgross="23000" currency="EUR" reference="1773673332" delayindays="0" is_partial="1" invoice_number="INV551202291" shippingname="Express Versand" shippingprice="840" shippingpricegross="1000" rebate="1681" rebategross="2000" carttotalprice="19327" />
  <article_data>
    <article articleid="1234" articlequantity="2" articlename="Shirt" articleprice="10084" articlepricegross="12000" />
  </article_data>    
</data>   

InvoiceCreated Response

For the payment methods "invoice" and "transaction credit Switzerland", the "InvoiceCreated" response contains the BillPay bank account data and the payment due date to be printed on the invoice for the customer. This bank information, in combination with the payment due date and the transaction purpose, needs to be sent to the customer, so they can pay their invoice in a timely fashion.

For the payment methods "PayLater" and "Direct Debit", these parameters have no meaning and can be ignored. Instead, a more static text (as seen in the invoice examples in the section "Downloads") can be printed on the document.

Attribute Mandatory? Type Possible Values Details
account_holder + String AN..255 Account holder for the debt
account_number + String AN..40 BillPay IBAN
bank_code + String AN..16 BillPay BIC
bank_name + String AN..255 Name der BillPay bank
invoice_reference + String AN..255 Transaction purpose
invoice_duedate + Int N..8 Payment due date in the format: YYYYMMDD
activation_performed + Boolean 0/1 1: The debt has been activated
0: The debt has been activated before; no additional activation performed.
<?xml version="1.0" encoding="UTF-8" ?>
<data api_version="1.5.11" 
      customer_message="" 
    error_code="0" 
    merchant_message="">
   <invoice_bank_account 
    account_holder="Billpay GmbH" 
    account_number="DE1200TEST333222110000492152" 
    activation_performed="1" 
    bank_code="TESTBIC0001" 
    bank_name="BillPay Test Bank" 
    invoice_duedate="20160324" 
    invoice_reference="BP1773673332/3042"/>
</data>