BillPay Techdocs
Navbar

BillPay Off-Line Solutions

The integration of BillPay in your point of sale or call center solution is much like a direct integration in your online channel (ecommerce and travel). There are, however, a few points that are specific to to point of sale and call center implementations.

Call Center Agents

It is important that your customers are aware that they have the ability to select payment methods that are offered by BillPay. We recommend the following text:

Payment in Instalments

For the instalment payment method, it is legally required that the customer review the instalment contract and European Standard Information (ESI) document before the order is finalized.

  • For call center orders, the customer needs to be provided said documents (e.g. via email) and acknowledge that they have reviewed them prior to the order being completed.
  • For point of sale orders, where the customer is physically present, the intalment contract needs to be signed and the ESI document needs to be reviewed by the customer prior to order being completed.

Because of above requirements, it is required for call center and point of sales solutions to implement a “two-step order creation” process - preauthorize request with manualcapture = “1” followed by a capture request.

BillPay makes the instalment contract and ESI documents available via our Document Service.

This service is secured by BasicAuthentication. The required credentials should be sent in the request header and are comprised of the following:

Username: The Portal ID for the request
Password: The hashed API Password (the same as used in the passwordhash for the API requests).

getDocument

Retrieves a document response or streams a PDF document, based upon the given parameters.

/getDocument?type=[document type]&transactionId=[transaction ID]&download=[download]&paymentMethod=[payment method] /getDocument?type=[document type]&orderReference=[oreder reference]

URLs

Test System: https://test-resources.billpay.de/getDocument?
Live System: https://resources.billpay.de/getDocument?

Parameter Description Examples Validation
type Document type pdf_standard_eupdf_contract required
transactionId Order transaction ID (UUID format) 7ec8977f-7cc8-4848-988f-30d8d9a6eeaa EITHER transactionId OR orderReference is required
orderReference merchant_order_id 100411544
download boolean flag to stream file instead of getting its absolute path in the response true / false not required (default=true)
paymentMethod The payment method that this order will have. Is relevant in case the document is fetchedbefore the order is fully placed (Payment Page) UNKNOWN
PAYLATER
PAYLATER_COLLATERAL_PROMISE
Not required. If it is absent and the order does not yet have a payment method, the document generation will fail.
rateCount The rate count for prescore in order to calculate the rate again and add it to the standard information and rate contract pdf document integer not required, (require for prescore order)

Response

If the download get variable is set to “true”:

  • Success: The file is pushed to output stream with response content-type (application/pdf).
  • Failure: Document Response expressing the failure and the filepath if available.

If the download get variable is set to “false”:

{
    "status": 0,
    "message" : "Success",
    "localPath" : "/data/spool/mypdf.pdf"
}

sendDocument

Creates an event that will send an email, based on the given parameters.

/sendDocument?mediaType=email&type=[document type]&transactionId=[transaction ID]&paymentMethod=[payment method]

URLs

Test System: https://test-resources.billpay.de/sendDocument?
Live System: https://resources.billpay.de/sendDocument?

Parameter Description Examples Validation
mediaType Type of media to send EMAIL required
type Document type pdf_standard_eu required
transactionId Order transaction ID (UUID format) 7ec8977f-7cc8-4848-988f-30d8d9a6eeaa EITHER transactionId OR orderReference is required
orderReference merchant_order_id 100411544
paymentMethod The payment method that this order will have. Is relevant in case the document is fetchedbefore the order is fully placed (Payment Page) UNKNOWN
PAYLATER
PAYLATER_COLLATERAL_PROMISE
not requiredIf it is absent and the order does not have a payment method yet, the generation will fail.
rateCount The rate count for pre score order to calculate rate again and add in the standard information and rate contract pdf document integer not required, (require for prescore order)

Response

{
    "status": 0,
    "message" : "Success",
    "localPath" : null
}

Version history

[2.2.0] - 2017-10-04

The version 2.2.0 is not fully backwards compatible to 2.1.0

Added

  • Request: getOrderDetails.xsd

  • Response: getOrderDetails.xsd

  • Request: prescore.xsd

    • attribute expecteddaystillshipping

Changed

  • Request: shiftDueDate.xsd
    • changed attribute newduedate from type date to the name shiftdatesby from the type integer in the range 1 to 90

[2.1.0] - 2017-06-19

The version 2.1.0 is not fully backwards compatible to 2.0.0

Changed

  • Request: preauthorize.xsd
  • Request: prescore.xsd

    • allowed values from attribute historicaltripcurrency changed from char to enum
  • Response: invoiceCreated.xsd

    • element name has been changed from “invoice_numbers” to “assigned_invoice_number”. Only the invoice_number node for the currently activated suborder is returned.

[2.0.0] - 2017-07-03

Added

  • Notificatons: asyncCapture.xsd

  • Request: cancel.xsd

  • Request: capture.xsd

  • Request: editCartContent.xsd

  • Request: getBillPayBankData.xsd

  • Request: invoiceCreated.xsd

  • Request: partialCancel.xsd

  • Request: preauthorize.xsd

  • Request: prescore.xsd

  • Request: reportCustomerPayment.xsd

  • Request: shiftDueDate.xsd

  • Request: updateOrder.xsd

  • Response: cancel.xsd

  • Response: capture.xsd

  • Response: editCartContent.xsd

  • Response: getBillPayBankData.xsd

  • Response: invoiceCreated.xsd

  • Response: partialCancel.xsd

  • Response: preauthorize.xsd

  • Response: prescore.xsd

  • Response: reportCustomerPayment.xsd

  • Response: shiftDueDate.xsd

  • Response: updateOrder.xsd

Should you have any questions relating to this manual and/or integrating BillPay payment methods, please feel free to contact us via support@billpay.de.