alt

Important information

The API reference is now available here.
The deprecated API reference is available here.

Unzer

Customize the plugin

Customize the Shopware 5 plugin to suit your unique business requirements.

As an agency or developer, you can customize the plugin according to your requirements.

Before you begin

Set your language preferences for payment methods

The Heidelpay CD-Edition plugin by Unzer for Shopware 5 delivers the text snippets for German (DE) and English (EN) language by default. Go to Configuration > Snippet administration > Snippet administration.

Select Namespace and then the relevant folder for which you want to update the snippets.

Snippets configuration

You can add custom translations in the Namespace folder with the various options available, including:

  • frontend/payment_heidelpay
  • frontend/checkout/finish
  • frontend/register/hp_payment
  • backend/heidelBackend

You can use the search option to easily find and edit each text snippet.

Edit Checkout success payment data texts

For secured payment methods, you can modify the text displayed on the checkout-finish page. This is required for printing the bank details on the invoice that the customer can refer to for making the payment.

Checkout success page Shopware 5

  1. In Shopware backend, go to Configuration > Snippets.
  2. Search for the frontend/payment_heidelpay/success namespace.
  3. Edit the snippet that you want to customize.
  4. Edit the templates for the following payment methods:
Payment methodTemplateStandard text
Prepayment

Invoice

Invoice secured / factoring / B2B
PrepaymentTextBitte überweisen Sie uns den Betrag von <strong>{AMOUNT} {CURRENCY}</strong> auf folgendes Konto: Land: {CONNECTOR_ACCOUNT_COUNTRY} Kontoinhaber: {CONNECTOR_ACCOUNT_HOLDER} Konto-Nr.: {CONNECTOR_ACCOUNT_NUMBER} Bankleitzahl: {CONNECTOR_ACCOUNT_BANK} IBAN: {CONNECTOR_ACCOUNT_IBAN} BIC: {CONNECTOR_ACCOUNT_BIC} Geben Sie als Verwendungszweck bitte ausschließlich diese Identifikationsnummer an: <strong>{IDENTIFICATION_SHORTID}</strong>
Rechnungskauf SantanderPrepaymentSanTextBitte überweisen Sie den Betrag von <strong>{AMOUNT} {CURRENCY}</strong> mit Zahlungsziel innerhalb von 30 Tagen auf folgendes Konto: Land: {CONNECTOR_ACCOUNT_COUNTRY} Kontoinhaber: {CONNECTOR_ACCOUNT_HOLDER} Konto-Nr.: {CONNECTOR_ACCOUNT_NUMBER} Bankleitzahl: {CONNECTOR_ACCOUNT_BANK} IBAN: {CONNECTOR_ACCOUNT_IBAN} BIC: {CONNECTOR_ACCOUNT_BIC} Geben Sie als Verwendungszweck bitte ausschließlich diese Identifikationsnummer an: <strong>{CONNECTOR_ACCOUNT_USAGE}</strong>
Rechnungskauf PayolutionPrepaymentIvpdTextBitte überweisen Sie den Betrag von <strong>{AMOUNT} {CURRENCY}</strong> mit Zahlungsziel innerhalb von 30 Tagen auf folgendes Konto: Land: {CONNECTOR_ACCOUNT_COUNTRY} Kontoinhaber: {CONNECTOR_ACCOUNT_HOLDER} IBAN: {CONNECTOR_ACCOUNT_IBAN} BIC: {CONNECTOR_ACCOUNT_BIC} Geben Sie als Verwendungszweck bitte ausschließlich diese Identifikationsnummer an: <strong>{CONNECTOR_ACCOUNT_USAGE}</strong>
  1. Select Save.
  2. Clear the caches and compile the themes.

Edit Customer Account payment data texts

The Unzer plugin displays the customer’s account order page as shown in the following example.

Shopware customer account page orders

You can modify the text displayed on customer’s account order overview in Order details > Communication tab.

  1. In Shopware back end, go to Customers > Orders, edit the order to see the Order details window and select the Communication tab.
  2. Add the details in the Your comment section and then click Save external comments. Order details tab communication

Edit the additional email with payment data

For the following payment methods, you can add one more email in addition to the confirmation email where you can send the payment details:

  • Invoice
  • Prepayment
  • SEPA Direct Debit

To modify the corresponding email templates:

  1. Go to Configuration > E-mail management > E-mail templates > User E-Mails, where you can see the templates in the Plain text and HTML tabs. Email templates

  2. Add your modifications in the Plain text and HTML tabs.

  3. Update the other details as required, and then click Save template.

Do not modify the variables written in curly braces “{ }”.

Modify payment data on the invoice document

If an invoice document is generated within the Shopware backend, the data for the money transfer is automatically added to the invoice PDF for payment methods Invoice (all types) and prepayment. Example invoice for Shopware 5

To modify the text:

  1. Open the database table s_core_documents_box in your preferred database tool
  2. Search within the s_core_documents_box table for an entry where name=Hgw_IV_contend_info.
  3. Edit the column style and value. Database table s core documents box

The following list describes the standard values for each payment method:

Payment methodTemplate NameStyleValue
Prepayment

Invoice

Invoice secured / factoring / B2B
Hgw_IV_Content_Info.payment_instruction, .payment_instruction td, .payment_instruction tr{ margin: 0; padding: 0; border: 0; font-size:10px; font: inherit; vertical-align: baseline; } .payment_note{ font-size: 10px; color: #333; } .payment_account{ margin: 5px 0 5px 5px; padding: 0; } .payment_account tr, .payment_account td{ margin: 0; padding: 0; border: 0; font-size:10px; font: inherit; vertical-align: baseline; } .payment_account td{ padding: 0 5px 0 0; }<br/><div>Bitte &uuml;berweisen Sie uns den Rechnungsbetrag auf folgendes Konto:<table class="payment_account"><tr><td>Kontoinhaber:</td><td>{$instruction.holder}</td></tr><tr><td>IBAN:</td><td>{$instruction.iban}</td></tr><tr><td>BIC:</td><td>{$instruction.bic}</td></tr></table>Geben Sie als Verwendungszweck bitte ausschlie&szlig;lich diese Identifikationsnummer an: <strong>{$instruction.shortId}</strong></div>
Rechnungskauf SantanderHgw_SAN_Content_Info.payment_instruction, .payment_instruction td, .payment_instruction tr{ margin: 0; padding: 0; border: 0; font-size:10px; font: inherit; vertical-align: baseline; } .payment_note{ font-size: 10px; color: #333; } .payment_account{ margin: 5px 0 5px 5px; padding: 0; } .payment_account tr, .payment_account td{ margin: 0; padding: 0; border: 0; font-size:10px; font: inherit; vertical-align: baseline; } .payment_account td{ padding: 0 5px 0 0; }<br/><div>Bitte &uuml;berweisen Sie uns den Rechnungsbetrag auf folgendes Konto:<table class="payment_account"><tr><td>Kontoinhaber:</td><td>{$instruction.holder}</td></tr><tr><td>IBAN:</td><td>{$instruction.iban}</td></tr><tr><td>BIC:</td><td>{$instruction.bic}</td></tr></table>Geben Sie als Verwendungszweck bitte ausschlie&szlig;lich diese Identifikationsnummer an: <strong>{$instruction.shortId}</strong></div>
Rechnungskauf PayolutionHgw_IVPD_Content_Info.payment_instruction, .payment_instruction td, .payment_instruction tr{ margin: 0; padding: 0; border: 0; font-size:10px; font: inherit; vertical-align: baseline; } .payment_note{ font-size: 10px; color: #333; } .payment_account{ margin: 5px 0 5px 5px; padding: 0; } .payment_account tr, .payment_account td{ margin: 0; padding: 0; border: 0; font-size:10px; font: inherit; vertical-align: baseline; } .payment_account td{ padding: 0 5px 0 0; }<br/><div>Bitte &uuml;berweisen Sie den Rechnungsbetrag mit Zahlungsziel innerhalb von 7 Tagen auf folgendes Konto:<table class="payment_account"><tr><td>Kontoinhaber:</td><td>{$instruction.holder}</td></tr><tr><td>IBAN:</td><td>{$instruction.iban}</td></tr><tr><td>BIC:</td><td>{$instruction.bic}</td></tr></table>Geben Sie als Verwendungszweck bitte ausschlie&szlig;lich diese Identifikationsnummer an: <strong>{$instruction.connectorAccountUsage}</strong></div>

Registered payment data

The references to stored payment data of the buyers are available in the s_plugin_hgw_regdata table.

  • The reference IDs (column uid) is used for your own subscription integration.
  • The shipping hash is generated to prohibit users to use stored payment types when the shipping address changed. Which should reduce the risk of fraudulent use of customer accounts.
  • The column userID is a reference to the Shopware customer entity.

Database table plugin registered data

Stored log files

You can find the log file entries of the plugin within your Shopware Backend log.
Go to Configuration > Logfile > Backend log.

Shopware administration log files

Styling of Credit Card and Debit Card payment methods

The plugin delivers a CSS file which adapts the unzer-payment form to the Shopware’s style.
This CSS file can be found in following directories:

  • For Shopware version higher than or equal to 5.2 file:
    engine/Shopware/Plugins/Community/Frontend/HeidelGateway/Views/responsive/-frontend/_public/src/less/hpf_style.less
  • For Shopware version less than 5.2 file:
    engine/Shopware/Plugins/Community/Frontend/HeidelGateway/Views/frontend/-_resources/styles/hpf_style.less

You can also specify your own CSS-file within plugin basic configuration.

Plugin basic configuration

Update error messages for the payment

In case of a declined transaction, the customer gets redirected to the shop’s frontend and a failure message is displayed. Error messages are displayed according to the error code which was sent in response to the transaction.
You can edit the error messages via the text snippets you can find here: Configuration > Snippets.
The most common error messages are already stored in the namespace frontend/payment_heidelpay/error.
You can also find them by searching for HPError.

Text snippet configuration

For all non-existing messages, you can add new entries in this table for each language set.
Use the following conventions for adding new error messages:

  • Namespace: frontend/payment_heidelpay/error
  • Name format: Word “HPError-” followed by the 9-digit failure code from Unzer payment system. For example, “HPError-100.100.303”

Activate Push messages

Push messages are used to update payment states in your shop automatically.
If, for example, a customer completes a prepayment by transferring the money, the push message to shop is sent to update the payment state from reserved to completely paid.

Contact the Unzer support team to activate the push message feature for your shop.

Next Steps