What is the Payment Gateway API

Dealer documentation¶

  • »
  • Better Payment Merchant Documentation

Last change: 05/17/2021 11:18 AM

This guide provides information on how to set up and use your online payment.

Our team for general SupportFor all matters of onboarding, contractual questions and topics relating to your dealer account, you can reach us at:

[email protected]

Our technical Help desk If you need support with the integration or to report a fault, you can reach us at:

[email protected]

We will create a ticket for you and try to clarify it as soon as possible.

Onboarding¶

The actual onboarding process consists of three steps. When registering, all necessary data is requested, which we then need to verify the legitimacy of the documents according to the KYC checklist (pdf) with evidence. Finally, the individual contracts still have to be signed.

This section will give you a detailed idea of ​​this process and help you to keep track of it during the process.

Note

Processing times: We will create your accounts and contracts as quickly as possible. Please note, however, that the respective contractual partner of the payment methods may take longer processing times.

Registration¶

Before the actual onboarding process starts, we ask interested parties to first request an offer using our offer form, in which an offer of our services and prices can be created with just a few details.

If you are satisfied with the offer, please fill out our registration form. Please specify here comprehensive information about your company, the beneficial owners, as well as the desired payment methods and services.

Information required for registration:

  • Company address

  • contact person

  • Website url

  • E-commerce sales

  • Description of the business model

  • Desired payment methods

  • Desired services

  • Bank details

  • Legally binding representation

  • Economic beneficiaries

As soon as you have completely entered your details in the registration form and sent us, you will receive a registration confirmation by e-mail with a Checklist for the proof to be sent to us for the legitimation check.

Legitimation check¶

Then we prepare you for the Legitimation check (KYC check) with the individual payment providers. You must provide evidence of the data you have provided. We therefore ask you to send the scanned copies of the required documents collectively to [email protected]

You can find which documents about the company and the relevant people you need to send us in our KYC checklist (pdf).

Danger

The providers check your shop before approving it. Please make sure, that:

  • at least 1 item is available

  • a checkout exists

  • the imprint has been published

  • the terms of use are in place

  • and the terms and conditions can be viewed.

Alternatively, a test system can be tested. Without a system for checking, however, no processing can take place and the entire onboarding process can therefore take longer.

Contract drawing¶

While your details and documents are being checked, we will send you the contracts for your individual payment selection. These are already filled in, mostly ready to be signed, and you only have to check for correctness and completeness.

With the Better Payment contracts and the signed contracts of the payment providers, you give us the starting signal to register with the individual payment providers. For this we ask you to send all signed documents as a scan via email to [email protected]

Depending on how many payment methods you want, you will receive more or fewer contracts. Here is a brief overview:

Contracts with us:

Service contract & order processing contract

Contracts with the payment providers:

Credit card, SOFORT, giropay, Paydirekt and Bonima

For PayPal there are no extra contracts. You have to set up your own PayPal business account, which we can then integrate for you.

comment

The following applies to the signing of the contract

  • Only persons registered as authorized to sign can also legally sign the contracts

  • If several persons are authorized to sign and no person has been granted sole management authority, all authorized persons must also sign

  • When signing, make sure to include the place and date on all contracts

If contracts are not signed properly, there will be delays in the process flow, as they have to be requested again and signed again.

You will find more detailed information on the individual contracts below. Please send us a scan of the signed contracts by email to [email protected]

Service contract (SV) ¶

The service contract (SV) regulates the general terms and conditions of the contractual relationship with Better Payment. This includes the stated conditions for technical payment processing and the use of the Better Payment Gateway.

1 document, 1 signature

Order processing contract (AV) ¶

The order processing contract (AV) is an agreement for the order processing of personal data according to Art. 28 GDPR for the technical processing and transmission of e-commerce payment data from credit and debit cards and other payment methods, as well as the mediation of credit card acceptance contracts with national and international Financial services.

1 document, 1 signature

Credit card acceptance¶

This is the credit card acceptance contract with the acquirer. You will receive all required documents, as well as information on required signatures and the dispatch from us by e-mail.

1 documents, 2 signatures

SOFORT contract¶

So that we can register you with SOFORT, we need an authorization from you. After successful activation, we will give you access to your SOFORT account.

1 document, 1 signature

Giropay contract¶

In order to activate giropay at GiroSolution GmbH, the SEPA direct debit mandate (1 signature) for the fee collection and the contract (1 signature) must be signed (page 2).

1 document, 2 signatures

Paydirekt contract¶

At Paydirekt, the contract documents consist of the merchant application via the concentrator (2x signature), as well as the participation and fee agreement (2x signature).

2 documents, 4 signatures

Please send the signed dealer application via concentrator to your bank.

Please send the signed participation and remuneration agreement as a scan by email to [email protected]

Bonima contract¶

Bonima is one of the possible partners for underwriting.

1 document, 1 signature

Go Live¶

As soon as the individual payment methods have been activated, we will inform you of this by email. With every single payment method going live, you are already able to accept payments with the activated payment method - You don't have to wait until all the planned payment methods have been activated.

Note

Accept payments as soon as possible

The KYC check takes different lengths of time depending on the payment service provider. If you want to accept payments as quickly as possible, the primary integration of the following payment methods is suitable:

  • Paypal: If you have already set up a PayPal account, we only need your API parameters for activation, as well as your access data.

  • SEPA direct debit: If you already have an account with GLS Bank, Volksbanken and Raiffeisenbanken, Postbank, Deutsche Bank or Commerzbank, the SEPA direct debit can be set up via the Service-Rechenzentrum (SRZ). Once the required order types (CDS, CCS and C53) have been activated, the SEPA direct debit payment method can be activated for you.

You will still receive a confirmation from us as soon as all payment methods have gone live and the onboarding process has been completed.

Log in¶

After registering, you will receive access to the Better Payment Test Dashboard by email from our help desk. As soon as we have received the online payment service contract you signed, we will also provide you with the live dashboard.

comment

You have not received our email with the login details? We would be happy to set up additional users for your account. For this we need: Names and email addresses of all users for the respective environments by email to [email protected]

Integration¶

Below you will find all the information you need to integrate the payment gateway via plug-in or API.

Note

You can do the following Text module for your terms and conditions use:

Your payment data will be passed on to payment service providers commissioned by us, who will process the payment (s). The payment gateway from Better Payment Germany GmbH is used for data transmission and processing. Furthermore, if necessary, data for processing in the context of fraud prevention, the credit check with credit agencies and the transmission of open / overdue claims to debt collection service providers are transmitted to Better Payment and processed by them.

Payment gateway¶

The Better Payment Gateway can be integrated either via plug-in or API.

Both for integration via the plugin and via API 3 individual keys needed for identification.

  • API key

  • Incoming key

  • Outgoing key

You can find these in the dashboard under My company.

Via plugin¶

For integration via a plugin, simply install the plugin that is suitable for your shop system. At our partner Sellxed you will find all the Better Payment plugins for the supported shop systems. Simply download the plugin you need from Sellxed and install it.

You will then need the aforementioned to configure the plug-in in your shop system 3 individual keys from your dashboard for identification.

Via API¶

The integration via API is carried out by you or your technicians. The detailed API documentation is available for this purpose. If you have any questions, our helpdesk development team ([email protected]) is also at your side.

Dashboard¶

There are two dashboards in the payment gateway, one for the test and one for the live environment.

The Test dashboard is part of the test system, where all transactions via the test API are displayed. Test payments can be made, viewed, managed and downloaded via the test dashboard.

in the Live dashboard all transactions are displayed that were transmitted to the payment gateway via the live API. The live data for payment processing for the respective payment methods are stored here. Live payments can be viewed, managed and downloaded.

Danger

Please note that the data and settings of your test dashboard, not automatically can be transferred to the live dashboard. You have to re-enter all the settings in the live environment.

The dashboard has two menu levels:

  • Navbar: Main menu in the blue horizontal line above, this includes:

  • Sidebar: Vertical submenu on the left that changes depending on the selected navbar menu.

comment

  • Search field: Here you can search for the data displayed in the search field, depending on the selected navbar menu.

  • Sort lists: You can sort the list by clicking on a column heading.

Log in¶

Note

The language the login page is set according to the language preferred in the browser settings.

You can log in with the access data we created (email address and password) via the URLs for the test & live dashboard:

  • Test dashboard:

  • Live dashboard:

comment

Have you forgotten your password?

The password can be reset when logging in at. The user receives an email with further instructions.

Dashboard (Navbar) ¶

Under the menu item of the navbar you will find an overview of all your data.

You can use the filter function to filter your data according to the following information:

  • Payment methods

  • status (Transaction status)

  • Go to (Selected period)

Note

Default values ​​of the filter function:

  • Payment methods - All (even if these are not shown as selected)

  • status - Successful, Pending & Refunded

  • Go to - Current month

The following subpages from the Sidebar give you detailed insights into your data:

Transactions¶

Below is the filterable list of all individual transactions.

The detailed list of all transactions is available for you (right).

comment

What meaning does each Transaction status has, see Transaction Status.

Recurring transactions¶

Under is the filterable list of all recurring payments.

The detailed list of all recurring transactions is also available to you.

Payouts¶

Below is the filterable list of payout transactions. These are transactions that were paid out to the customer by you (however, this includes no refunds meant).

Virtual Terminal¶

With the help of the virtual terminal, customer data can be recorded and payments can be made via Credit card or SEPA direct debit can be triggered even if a customer orders by phone or email (MO / TO). In this way, customer data is also recorded in your dashboard.

Then click on or and enter the required transaction data for the MO / TO order.

Pay now¶

The JetztZahlen application is available via a separate Pay Now Dashboard accessible by clicking on the menu item on your navbar. Then a new tab opens with the NowPaying dashboard.

My company (Navbar) ¶

Under you can view and edit details about your company.

Exports & imports¶

If you choose the payment method SEPA direct debit with an EBICS-enabled account, you can see an overview of the transfers of direct debit transactions to the bank and the retrieval of account statements for the purpose of updating the transaction status.

Data storage¶

Under you can set the retention period for the customer data in the transactions between 90 and 3650 days before they are irrevocably anonymized by the payment gateway. Otherwise, a standard value of 540 days is set by Better Payment.

My account¶

Under you can view and edit the details of your user profile. There you can adjust yours or change yours at any time.

Configuration¶

Below you will find all the information you need for the configuration of all payment methods and the risk assessment in the payment gateway.

Pay now¶

The environment of the JetztZahlen application is already embedded with the integration of the Better Payment Gateway and is thus natively connected to your payment account.

If you are interested in the JetztZahlen application and this has not yet been included in the conclusion of the contract, please contact our support ([email protected]).

As soon as the use of JetztZahlen is contractually regulated, you only need to be activated for the application by our support.

You can then access the Now Pay Dashboard via a new menu item in your Better Payment Dashboard.

Payment methods¶

The technical integration of the individual payment methods differs greatly from that of the individual providers. Therefore you will find the integration processes for the following payment methods below:

SEPA direct debit¶

In order to be able to collect SEPA direct debits from your account with Better Payment, please note the following information and the process described.

Important

You need one Creditor identification number (Creditor Identifier) ​​to be able to collect direct debits.

  • At company headquarters in Germany apply for this at the Deutsche Bundesbank

  • At company headquarters in foreign countries please contact your bank regarding the creditor identification number

Please inform your bank and Better Payment ([email protected]) of the creditor identification number immediately upon receipt.

There are two options for setting up SEPA direct debit:

  1. Setup via Better Payment as a service data center (SRZ)

  2. Setup via your own EBICS user

If you already have an account with one of the following banks, SEPA direct debit can be set up via Better Payment as a service data center (SRZ) (see 1. Setup via Better Payment as a service data center):

  • GLS Bank

  • Volksbanken and Raiffeisenbanken

  • Postbank

  • Deutsche Bank

  • Commerzbank

If your bank is not listed here, SEPA direct debit can only be set up via your own EBICS user (see 2. Setting up via your own EBICS user).

1. Setup via Better Payment as a service data center¶

If you have an account with one of the banks mentioned above, we will send you the SRZ-EBICS user data. Please have the SRZ-EBICS user activated at your bank for the required order types:

  • CDS for direct debits

  • CCS for transfers

  • C53 for payment reconciliation

As soon as the user has been activated for your account by your bank, please inform us. We will then activate the SEPA direct debit payment method for you. For this we need the following information from you:

  • Creditor identification number

  • IBAN of your account

  • BIC of your account

comment

Please ensure that the electronic account statements are split up by your bank via C53, i.e. individual payment transactions are shown. Otherwise the status of the SEPA direct debit transactions cannot be updated in the payment dashboard (e.g. to "successful").

2. Setup via your own EBICS user¶

If your bank does not appear in the above list, provide us with your EBICS user data, which will then be stored in the payment system. Your EBICS user must be activated for the following order types:

  • CDD for direct debits

  • CCT for transfers (optional) - used e.g. for refunds

  • C53 for payment reconciliation

comment

If not yet Direct Debit Collection Agreement with your bank, please contact your bank and request the relevant information and documents.

We have summarized the process for you below:

2.1 Request EBICS credentials

You will receive EBICS access data (EBICS credentials) for your EBICS-enabled account, if not already available, by sending a request to your bank for the participation agreement for online banking with EBICS (the name may vary from bank to bank).

In the agreement, you specify which order types and authorizations apply and for which processes the respective user is activated.

We recommend the e-signature (E as in individual disposal as opposed to the T-signature (transport)).

2.2 Send EBICS credentials

After you have received your EBICS access data (EBICS credentials) from your bank and this EBICS user is authorized for the required order types, we ask you for them PGP encrypted to send to us. You can obtain the corresponding public key from your Better Payment contact on request.

The EBICS credentials include, for example:

  • Host name: xxxx-xxxx

  • HOST customer ID: xxxxxxxx

  • Participant ID (s) xxxxxxxx E username

  • EBICS-URL: https: //ebicsurl.ihrer.bank.webform.xx

2.3 Receive public keys via INI letter

We create three keys in the following initialization process. We will send you a PDF document with a checksum, the INI letter. With the submitted EBICS credentials, the following procedures are used for onboarding / key setup:

  • INI: Send public key

  • HIA: Send Public Authentication (X002) and Encryption (E002) Keys

  • HPB: Download Public Bank Keys X002 and E002

2.4 Send the INI letter to the bank

Print out the INI letter, sign it and send it to your bank.

2.5 Information Better Payment

Your bank is processing the INI letter and should inform you when the processing is complete. Please inform our support ([email protected]) then. Depending on your bank, there may be different processes and the need for additional agreements.

2.6 Activation in the dashboard

As soon as you inform us that your bank has finished processing the INI letter, we will activate the SEPA direct debit payment method for you. For this we need the following information from you.

  • Creditor identification number

  • IBAN of your account

  • BIC of your account

Important

Adaptation of the GTC for direct debit on your website

Before you can collect direct debits, you must adapt your terms and conditions to the new payment method. At best, add the following to your paragraph on direct debit payments:

Payment by SEPA direct debit: The buyer can issue a SEPA basic mandate. The pre-notification period is shortened to one day. The buyer guarantees to provide sufficient funds for the account. Costs that arise due to non-cashing or chargeback of the direct debit are borne by the buyer as long as the non cashing or chargeback was not caused by.

PayPal¶

We would be happy to integrate your existing PayPal account. To do this, however, we need your PayPal API parameters, which you can request as follows:

  1. Log into your live or sandbox account.

  2. Click on My Profile at the top and select Account Settings from the drop-down menu.

  3. Click on Seller / Dealer.

  4. In the API Access area, click Update.

  5. Under NVP / SOAP API Integration, click Request API Permission.

Current changes to this process can be found in the PayPal Help Center.

If you have already generated an API signature, the API signature will be displayed. Click this option to view or remove your existing API signature.

To integrate PayPal, we need the following three values ​​from your PayPal account.

  • API username

  • API password

  • signature

Please send us the data that is displayed to you as text by copy & paste (not as a screenshot) to [email protected] Upon request, we will be happy to provide you with a PGP key to encrypt the data.

Giropay¶

After successfully registering with Giropay, you will receive an email with the access data from Girosolution GmbH. You can log in to Giropay and view all the invoices for the fees: https://www.girocockpit.de

Paydirect¶

After successfully registering with Paydirekt, you will receive an email with the access data from Paydirekt directly. You can log into your Paydirekt account: https://www.paydirekt.de/merchant/login

Risk assessment¶

Better Payment offers the possibility to carry out flexibly configurable risk assessments. The individual risk checks and test settings in the payment system are managed for you by Better Payment. All relevant interfaces are available via the Better Payment platform.

Below are the categories for the following risk assessment services:

  • Risk checks

    • Order restrictions

    • Address validation

    • identification

    • Credit check

  • Pre-checks

Risk checks¶

Better Payment configures the risk check for your account. The check is carried out when a transaction is submitted at the end of the ordering process. The transaction is approved or rejected based on the results of the check.

Risk checks are available for the following payment methods:

  • Purchase on invoice

  • SEPA direct debit

Pre-checks¶

In the pre-check, the risk assessment is carried out before a payment method has been selected by the customer. To do this, the required order information is sent to Better Payment before the payment option is made in the checkout.

According to the results of the risk assessment, a list of the permitted payment methods is returned to the shop by Better Payment. Based on this list, only the permitted payment methods are presented in the checkout.

comment

Using the pre-check functionality can result in multiple risk checks per order. If the buyers change relevant information that is relevant for the risk assessment, the risk assessment is restarted. The relevant information includes: name, date of birth, shopping cart value and other characteristics. This applies to both multi-step checkouts and one-page checkouts.

Test data¶

In order to test your newly integrated payment, we provide you with test data for each payment method. You can find this online in our API documentation.

Transaction status¶

In the following table you will find an overview of each possible transaction status and the corresponding description of the meaning.

code

status

description

1

Started

The transaction has started; the user was redirected to the aquirer's website.
Transactions that remain in this state for more than an hour should be carried out by the merchant
considered canceled.

2

Pending

payment with credit card: The user submitted the payment, but the acquirer has
marked the transaction as pending; this usually means that it is
Takes a longer than average time to complete the transaction.
Payments on account: The order has been accepted but payment has to be made by the merchant
manually confirmed or recorded via the API (depending on the acquirer).
The pending status is treated as a successful payment; the API gives a
successful status or redirects to the merchant's success URL.

3

Successful

payment with credit card: The acquirer has marked the transaction as successful.
Payments on account: The merchant marks pending transactions in the merchant portal
Payment is successful; the API returns a successful status or redirects to the

4

error

An error occurred in the transaction.
The API returns an error status or redirects to the shop's error URL.

5

Canceled

The user canceled the payment on the acquirer's website.
The API redirects to the error url or returns an aborted status.

6

Declined

The acquirer has marked the transaction as rejected. Payments that require an underwriting
require are marked as rejected if the underwriting fails.
The API returns a rejected status or redirects to the shop's error URL.

7

Refunded

Partial or full refunds are available for this transaction.
This status is usually not returned by the API, but it is in the dealer portal
visible after refunds are made.

8

Authorized

The payment was successfully authorized but not yet executed.
This payment should be recorded or reversed later.

9

Registered

A credit card was registered for this transaction, but the payment was not processed.
A successful pre-check was performed, but the transaction is not yet
This transaction should be concluded with the payment request.

10

Debt collection

A debt collection procedure has been initiated for this transaction.
The transaction has gone into debt collection; further status reports are still pending.

11

Debt_paid

The collection process for this transaction is complete.
The debt has been collected and the transaction is considered successful.

12

Canceled

The approval has been revoked (canceled).
The transaction is considered canceled.

13

Chargeback

A chargeback was issued for a successful or good looking transaction.

14

Factoring

The transaction is considered successful as it is assumed that the merchant will have the money
received from the factoring party.

15

Debt_rejected

The collection of debts was refused (e.g. due to insufficient data).

16

Factoring_rejected

Factoring was rejected (e.g. due to inadequate risk controls).

Glossary¶

API

An API (Application Programming Interface) can be distinguished very precisely from a user interface. While the user interface represents an interface between the program and the user of the software, the API corresponds to a machine-readable interface between two computers.

EBICS

The EBICS (Electronic Banking Internet Communication Standard) is a multi-bank standard for the transmission of payment transaction data over the Internet in various SEPA countries. More specifically, it is an open, internet-based communication protocol for the transmission of financial transactions between customers and their banks.

KYC

The know-your-customer principle (KYC) means checking the personal and business data of new customers of a credit institution to prevent money laundering and terrorist financing on the basis of the Money Laundering Act 2008.

MO / TO

The abbreviation stands for Mail Order / Telephone Order. This means orders that are processed by email or telephone.

Plugin

A plug-in is an optional software component that can be used to connect shop systems to Better Payment, for example.


© Copyright 2020-2021, Better Payment Germany GmbH