Navbar
Shell Ruby Php

About

Payment Gateway is the system, which mediates and manages all payment requests, that are used to perform different functionalities and operations. To get started, please make sure that you already have an account registered with us and head to Quick Start page.

Quick Start

To jump right into implementation, please head to Authentication Section and later over to API Reference for details of API endpoints.

We also suggest to read Payment Methods section in case you would like information on specific payment methods and their integration. API Reference does not get into very details of each payment method.

You can also refer to Transaction Statuses, Errors as well as Receiving transaction notifications through Postbacks.

Test Data can be found over Appendix.

Authentication

There are two ways of authenticating with our API. We strongly suggest to use BASIC AUTH authentication to speed up the development time. Checksum authentication is considered legacy.

For developers who still use the legacy way of authenticating using checksums, we still provide the documentation below.

Prior to authenticating, make sure to have your API and OUTGOING keys at hand. If you already have an account with us, please navigate to My Company section in your dashboard to view and manage authentication keys.

BASIC AUTH

Basic authentication is a simple authentication scheme built into the HTTP protocol. The client sends HTTP requests with the Authorization header that contains the word Basic followed by a space and a base64-encoded string username:password. For example, to authorize as demo / p@55w0rd the client would send following HTTP HEADER:

Authorization: Basic ZGVtbzpwQDU1dzByZA==

Simply include your API key as your username and OUTGOING key as your password in your basic auth encoding string.

Content-Type Headers

When using BASIC AUTH, you should set your Content-Type HTTP header value to application/json and post a JSON body in your request payloads.

Checksum - (legacy)

To prevent tampering with payment data, the parameters may be signed with a checksum. The outgoing requests are signed with the OUTGOING key. The API applies the following checksum calculation algorithm to verify the authenticity of the posted data.

The merchant is identified and authenticated with API key and a checksum calculated with request parameters and the OUTGOING key. The API, OUTGOING and INCOMING keys should be treated carefully and not revealed to outsiders.

How to calculate checksum?

query_string="api_key=aab1fbbca555e0e70c27&currency=EUR&merchant_reference=123&order_id=123&payment_type=cc&shipping_costs=3.50&amount=17.50"
outgoing_key="4d422da6fb8e3bb2749a"

# MacOS
echo -n $query_string$outgoing_key | shasum | awk '{print $1}'

# Linux
echo -n $query_string$outgoing_key | sha1sum | awk '{print $1}'

# Please replace the outgoing_key with your own, which is located under the section My Company on your dashboard.
def calculate_checksum(params, outgoing_key)
  params_in = {}

  params.each do |k, v|
    params_in[k] = v || ''
  end

  Digest::SHA1.hexdigest(URI.encode_www_form(params_in) + outgoing_key)
end

params = [["api_key", "aab1fbbca555e0e70c27"],
          ["currency", "EUR"],
          ["merchant_reference", "123"],
          ["order_id", "123"],
          ["payment_type", "cc"],
          ["shipping_costs", "3.50"],
          ["amount", "17.50"]]

outgoing_key = "4d422da6fb8e3bb2749a"
puts calculate_checksum(params, outgoing_key)

# @returns 9b6b075854fc3473c09700e20e19af3fbc3ff543

# Please replace the outgoing_key with your own, which is located under the section My Company on your dashboard.
function sign_request($params, $outgoing_key){
  $query = http_build_query($params, NULL, "&", PHP_QUERY_RFC1738);
  $checksum = sha1($query . $outgoing_key);
  return $checksum;
}

$params = array(
  "api_key" => "aab1fbbca555e0e70c27",
  "currency" => "EUR",
  "merchant_reference" => "123",
  "order_id" => "123",
  "payment_type" => "cc",
  "shipping_costs" => "3.50",
  "amount" => "17.50");
$outgoing_key = "4d422da6fb8e3bb2749a";

printf(sign_request($params, $outgoing_key));

// Return value is 9b6b075854fc3473c09700e20e19af3fbc3ff543

// Please, replace the outgoing_key with your own, which is located under the section My Company on your dashboard.

Please, follow the steps below:

We provided checksum calculation code in various programming languages in the sidebar.

Please, keep the following in mind:

How to convert parameters into query string?

Spaces are encoded as plus (+) characters and special characters are encoded with a percentage sign followed by two hexadecimal digits. For more details about how to encode a query string see RFC 1738. If the company parameter's key has the value “John & Sons”, {"company": "John & Sons"}, the resulting string will be: company=John+%26+Sons

Where to find credentials?

Credentials such as API, Outgoing and Incoming keys can be found in your Dashboard once you have registered an account with us.

API Reference

Below you will see list of all public API endpoints made available in our Payment Gateway. For each endpoint, we provide example body and response.

Payment API

Payment API is used to create new payments in the Payment Gateway.

Example POST rest/payment payload - Fill in your own API key and return URLs

{
    "api_key": "70abd594084787a392e8",
    "payment_type": "cc",
    "order_id": "122",
    "amount": "15.9",
    "currency": "EUR",    
    "address": "WonderStr 8",
    "city": "Berlin",
    "postal_code": "666",
    "country": "DE",
    "first_name": "Chuck",
    "last_name": "Norris",
    "email": "email@email.email",
    "postback_url": "https://postback.url.com",
    "success_url": "https://success.url.com",
    "error_url": "https://error.url.com",
}

Example POST rest/payment response

{
  "transaction_id": "5e02903b-0fbf-4266-affd-dc58f2749cd1",
  "order_id": "123000",
  "error_code": 0,
  "status_code": 1,
  "status": "started",
  "client_action": "redirect",
  "action_data": { 
    "url": "https://some-target-url"
  }
}

Payment API Parameters

Payment request parameters are divided into following blocks. Depending on your payment method type, they will differ.

X means that parameter block is accepted for the given payment method and is mandatory.

(X) means that parameter block is accepted for the given payment method and is optional.

Payment Method Common Parameters Billing Address Shipping Address Risk Check Redirection URLs Recurring Special Parameters
Credit Card X X X (X)
SEPA Direct Debit X X (X) (X) Sepa Direct Debit Parameters
SEPA Direct Debit (B2B) X X (X) (X) Sepa Direct Debit Parameters
Purchase on Account X X (X) X
Purchase on Account (B2B) X X (X) X Company Details Parameters
Installments X X (X) X
giropay X X X
Sofort X X X
PayPal X X X (X)
Barzahlen X X
Paydirekt X X X
Advance Payment X X
iDeal X X X

Common Parameters

The following parameters are used with all payment methods:

Parameters Required Comments
payment_type YES See possible payment types
api_key YES Merchant-specific API key
order_id YES Any alphanumeric string to identify the Merchant’s order.
invoice_id NO Any alphanumeric string to provide the invoice number of a Merchant’s order (up to 20 characters) for factoring or debt collection
invoice_date NO Any date to provide the invoice date of a Merchant’s order for factoring or debt collection. format: “YYYY-MM-DD”
customer_id NO Any alphanumeric string to provide the customer number of a Merchant’s order (up to 40 characters) for factoring or debt collection
merchant _reference NO See details about merchant reference
amount YES Including possible shipping costs and VAT (float number)
shipping_costs NO Should be set if the order includes any shipping costs (float number)
VAT NO VAT amount (float number) if known
currency NO 3-letter currency code (ISO 4217). Defaults to ‘EUR’
postback_url YES The URL for updates about transaction status are posted
customer_ip NO If the order includes a risk check, this field can be set to prevent customers from making multiple order attempts with different personal information.
customer_ip_proxy NO Like customer_ip, but if the order comes from behind a proxy, this additional field can be used.
original_transaction_id NO See Original Transaction ID
duration NO Used in installment calculation.
locale NO The language of payment forms in Credit Card and Paypal. Possible locale values
checksum NO A checksum of posted parameters and their values. See Checksum Calculation for a complete explanation. This parameter is optional when you are using BASIC AUTH which we strongly suggest to use.
theme NO This is the name of the custom theme that can be set for the payment page. This is only for legacy payment page. See Payment Page Theme API for more details.
custom_pay_text NO If parameter is passed, it will override default Pay Button text in the Credit Card Payment Page

Billing Address Parameters

Billing information is required in all payment methods.

Parameters Required Comments
address YES Street address
address2 NO Second address line
city YES The town, district or city of the billing address
postal_code YES The postal code or zip code of the billing address
state NO The county, state or region of the billing address
country YES Country Code in ISO 3166-1
first_name YES Customer’s first name
last_name YES Customer’s last name
email YES Customer’s last email
phone NO Customer’s phone number

Shipping Address Parameters

Shipping address can be specified when it differs from the billing address.

Parameters Required Comments
shipping_address YES Street address
shipping_address2 NO Second address line
shipping_company NO Name of the company of the given shipping address
shipping_city YES The town, district or city of the shipping address
shipping_postal_code YES The postal code or zip code of the shipping address
shipping_state NO The county, state or region of the shipping address
shipping_country YES Country Code in ISO 3166-1 alpha2
shipping_first_name YES Customer’s first name
shipping_last_name YES Customer’s last name

Company Details Parameters

Company details are required in B2B Purchase on Account and B2B SEPA Direct Debit orders.

Parameters Required Comments
company YES Company name
company_vat_id NO Starts with ISO 3166-1 alpha2 followed by 2 to 11 characters. See more details about Vat
company_trade_register NO Company trade registry no

Risk Check Parameters

If the order includes a Risk Check, the following additional parameters are required:

Parameters Required Comments
risk_check_approval YES This field must be set to 1 for enabling risk checks.
date_of_birth YES Customer’s date of birth; format: YYYY-MM-DD
gender YES m for male, f for female

Redirection URL Parameters

For payment methods that involve browser redirection such as credit card payments, these URLs are required.

Parameters Required Comments
success_url YES Where to redirect the user after a successful transaction
error_url YES Where to redirect the user after a failed transaction

The following data is appended to the URL, which is used when redirecting back to the shop’s success or error URLs.

SEPA Direct Debit Parameters

The following additional parameters are required for a direct debit payment.

If the optional sepa_mandate parameter is supplied, the Mandate Reference API request can be skipped prior to making the actual payment request.

Parameters Required Comments
account_holder YES Bank account holder’s name
iban YES IBAN account number (max. 31 characters)
bic NO BIC code*(max. 11 characters)*
sepa_mandate NO Mandate Reference Number (max. 35 characters)

Recurring Payment Parameters

Some payment methods can use recurring payments. For credit card payments, authorizations can be recurring as well. Here is a summary of the recurring payment flow:

For more information about recurring payment see details about recurring and original transaction ID

Parameters Required Comments
recurring YES See recurring
original_transaction_id YES(Except the first time) See original_transaction_id

Iframe Parameters

The frame_origin parameter is reserved for complex cases of iframe redirection.

Consider the following scenario: The payment process is started on Website A. Website A embeds an iframe from Website B, which redirects to BP Payment Gateway that hosts the payment form.

Such a redirection will be blocked by browsers unless the BP payment form specifies Website A as an allowed origin in the Content-Security-Policy header. Therefore, regardless of which website initiated the payment request, the frame_origin parameter needs to be set to the protocol and domain of the website that displays the iframe.

For redirection between only two websites, the frame_origin parameter is not necessary.

Parameters Required Comments
frame_origin NO Domain of the page that embeds the payment form in an iframe

Payment API response

The response includes the following attributes

Parameters Comments
transaction_id ID of the created transaction
order_id Order ID of the transaction
status_code Status code of the transaction
status Status of the transaction
client_action Client action such as redirect or postform. When this is not returned, no action required on client side from requester.
action_data Hash that contains URL to redirect on the client side.
error_code Error code for the response

Authorization API

Example POST rest/authorize payload

{
    "api_key": "70abd594084787a392e8",
    "payment_type": "cc",
    "order_id": "122",
    "amount": "15.9",
    "currency": "EUR",    
    "address": "WonderStr 8",
    "city": "Berlin",
    "postal_code": "666",
    "country": "DE",
    "first_name": "Chuck",
    "last_name": "Norris",
    "email": "email@email.email",
    "postback_url": "https://postback.url.com",
    "success_url": "https://success.url.com",
    "error_url": "https://error.url.com",
}

Example POST rest/authorize response

{
  "transaction_id": "5e02903b-0fbf-4266-affd-dc58f2749cd1",
  "order_id": "123000",
  "error_code": 0,
  "status_code": 1,
  "status": "started",
  "client_action": "redirect",
  "action_data": { 
    "url": "https://some-target-url"
  }
}

Authorization API is used to create payment authorizations. Authorized payments need to be captured or reversed later on if merchant decides to deduct money from customer's payment authorization or just cancel it by using Reversal API.

Authorization API Parameters

Authorization API parameters are identical with Payment API parameters. Please refer to Payment API for full list of parameters for each payment method.

Authorization API Response

Response is identical to Payment API. Please, refer back for details.

Capture API

Example rest/capture request

{
  "transaction_id": "e06dec72-788e-471a-a33f-a9d0deeeb4df",
  "api_key": "70abd594084787a392e8",
  "amount": 12.4,
}

Example rest/capture response

{
  "transaction_id": "e06dec72-788e-471a-a33f-a9d0deeeb4df",
  "status_code": 3,
  "status": "completed",
  "order_id": "123000",
  "message": "Request has been processed in test mode",
  "card_last_four": "4242",
  "card_expiry_year": 2021,
  "card_expiry_month": 12,
  "card_brand": "VISA",
  "error_code": 0
}

Capture API is used to capture amount from previously authorized transactions. It is possible to do partial captures - meaning to capture less that the authorized amount. However, amount may not exceed the original transaction. The result of a successful capture will change the transaction status to complete.

Capture API Parameters

Parameters Required Comments
api_key YES Merchant API Key
transaction_id YES ID of the transaction to be captured
amount NO In case it differs from the original transaction
execution_date NO Optional date of the event (YYYY-MM-DD)
comment  NO  Optional comment
vat NO VAT of the captured amount, if known
checksum NO Checksum of parameters. Legacy, please skip this parameter.

Capture API Response

The response includes the following attributes

Parameters Comments
transaction_id ID of the captured transaction
status_code Status code of the transaction
order_id Order ID of the transaction
message Any message received from acquirer
card_last_four Last four number of the captured credit card
card_expiry_year Expiry year of the captured credit card
card_expiry_month Expiry month of the captured credit card
card_brand Brand of the credit card
error_code Error code for the response

Reversal API

Example POST rest/reverse request

{
  "transaction_id": "8296188e-dd59-4c58-96da-4981976a8e06",
  "api_key": "70abd594084787a392e8",
  "amount": 12.4,
}

Example POST rest/reverse response

{
  "transaction_id": "8296188e-dd59-4c58-96da-4981976a8e06",
  "status_code": 12,
  "status": "reversed",
  "order_id": "123000",
  "message": "Request successfully processed in test mode.",
  "error_code": 0
}

Reversal API is used to reverse(cancel) previously authorized transactions. Depending on the acquirer configured for your payment method, it's possible to do partial reversals(reversing less than the full amount).

Reversal API Parameters

Parameters Required Comments
api_key YES Merchant API Key
transaction_id YES ID of the transaction to be reversed
amount NO In case it differs from the original transaction
execution_date NO Optional date of the event (YYYY-MM-DD)
comment  NO  Optional comment
vat NO VAT of the captured amount, if known
checksum NO Checksum of parameters. We strongly suggest to skip this parameter when using BASIC authentication.

Reversal API Response

The response includes the following attributes

Parameters Comments
transaction_id ID of the captured transaction
status_code Status code of the transaction
status Status of the transaction
order_id Order ID of the transaction
message Any message received from acquirer
error_code Error code for the response

Registrations API

Example POST rest/register payload

{
    "api_key": "70abd594084787a392e8",
    "payment_type": "cc",
    "order_id": "122",
    "amount": "15.9",
    "currency": "EUR",    
    "address": "WonderStr 8",
    "city": "Berlin",
    "postal_code": "666",
    "country": "DE",
    "first_name": "Chuck",
    "last_name": "Norris",
    "email": "email@email.email",
    "postback_url": "https://postback.url.com",
    "success_url": "https://success.url.com",
    "error_url": "https://error.url.com",
}

Example POST rest/register response

{
  "transaction_id": "6ba6655a-d691-4b9a-b858-bb37de2d235f",
  "order_id": "123000",
  "error_code": 0,
  "status_code": 1,
  "status": "started",
  "client_action": "redirect",
  "action_data": {
    "url": "https://some-redirect.url"
  }
}

Registrations API is used to register credit card information for use in a future payment. Difference between Authorization API is that the prior does not have an amount to block for future deduction.

Registrations API returns tokenized transaction ID, which is used later on with any amount, to make an actual payment.

Below is the summary of the Registration API's use case.

Registration API Parameters

Registration API parameters are identical to Payment API. Please, refer back for details there.

Registration API Response

Registration API response is identical to Payment API. Please, refer back for details there.

Refund API

Example rest/refund request

{
  "transaction_id": "f3ba29ea-5644-4e4b-aacd-8d854ebb3d46",
  "api_key": "70abd594084787a392e8"
}

Example rest/refund response

{
  "transaction_id": "f3ba29ea-5644-4e4b-aacd-8d854ebb3d46",
  "refund_id": "2ce3297b-1bda-4637-9375-ecf224cdefc7",
  "status_code": 1,
  "status": "successful",
  "error_code": 0
}

Refund API is used to refund full or partial amounts of payments that were made by merchants' customers. There can be multiple refunds per transaction, however, the combined sum of refunds should not exceed the total amount of the transaction.

Refund API Parameters

Parameters Required Comments
api_key YES Merchant API Key.
transaction_id YES ID of the transaction to be refunded.
amount NO When not given, full amount will be refunded. Can be smaller but not larger that the original amount.
execution_date NO Optional date of the event (YYYY-MM-DD)
vat NO VAT of the captured amount, if known.
comment NO
announcement NO May only be used for specific acquirer(Payolution). Set this to "1" to make a refund announcement.
checksum NO Checksum of parameters. We strongly suggest to skip this parameter when using BASIC authentication.

Refund API Response

The response includes the following attributes

Parameters Comments
transaction_id ID of the refunded transaction
refund_id ID of the created refund object
status Status of the refund
status_code Status code of the refund
error_code Error code for the response

Refund statuses include - STARTED(0), SUCCESS(1), ERROR(2).

Payout API

Example POST rest/payout payload - for direct debit

{
  "payment_type": "dd",
  "order_id": "12345",
  "api_key": "45320990e1c8467468d6",
  "amount": 15.9,
  "currency": "EUR",
  "merchant_reference": "some reference",
  "first_name": "Max",
  "last_name": "Mustermann",
  "address": "Teststr 5",
  "city": "Berlin",
  "country": "DE",
  "postal_code": "15557",
  "iban": "DE89370400440532013000",
  "postback_url": "your.endpoint.com"
}

Example POST rest/payout response - for direct debit payout

{
  "transaction_id": "0b3c2327-9394-4ab4-be18-6e9d85e652fd",
  "status_code": 2,
  "status": "pending",
  "order_id": 123000,
  "iban": "DE89370400440532013000",
  "bic": "COBADEFFXXX",
  "error_code": 0
}

Payout API is used to create payouts - which is a money transfer between merchant's account to customer's account.

Unlike refunds, payouts do not need previously created payment.

Only specific payment methods support Payouts. Please, check in the payment methods page for more information.

For Credit Card Payouts, either an original transaction that represents payment by the customer should exist, or the customers should be redirected to the payment page where they can enter their credit card details - just like in Payment API flow.

Payout API Request Parameters

Parameters Required Comments
payment_type YES See possible payment types
api_key YES Merchant-specific API key
order_id No Merchant’s OrderID
amount YES Amount to be paid out to the customer (float number)
currency YES 3-letter currency code (ISO 4217).
original _transaction_id NO optional ID of a previous payment; useful for credit card payouts
iban NO IBAN account number (required for direct debit)
bic NO BIC code (required for direct debit)
account_holder NO Bank account holder’s name (required for direct debit)
merchant _reference NO See details about merchant reference
address NO Street address
address2 NO Second address line
city NO The town, district or city of the billing address
postal_code NO The postal code or zip code of the billing address
state NO The county, state or region of the billing address
country NO Country Code in ISO 3166-1 alpha2
first_name NO Customer’s first name
last_name NO Customer’s last name
email NO Customer’s last email
phone NO Customer’s phone number
success_url NO The URL to which the end user is returned on success (required for credit card)
error_url NO The URL to which the end user is returned on error (required for credit card)
postback_url YES The URL for updates about transaction status are posted
checksum YES Checksum of parameters. Legacy. We strongly suggest to skip this field when using BASIC AUTH.

Payout API response parameters

Parameters Comments
transaction_id Payment Gateway own transaction ID
status_code Transaction’s status code
status Transaction status in words
order_id Merchant’s order ID
iban Receiver's IBAN
bic Receiver's BIC
client_action In case of credit card payouts, you may receive client action such as to redirect to another url. Flow is same as Payment API
error_code Error code; if this is 0, everything is fine
error_message If the error code is other than 0, the error message will be included here.

Precheck API

Example POST rest/precheck response - with payment method known

  {  
    "transaction_id":"a98ce7f7-97ea-4417-bdcb-f6f4ecde4149",
    "status_code":9,
    "status":"registered",
    "order_id":"123000",
    "message":"PRE_CHECK performed successfully.",
    "error_code":0
  }

Example POST rest/precheck response - with payment method NOT known

  {  
    "transaction_id":"a98ce7f7-97ea-4417-bdcb-f6f4ecde4149",
    "status_code":9,
    "status":"registered",
    "order_id":"123000",
    "message":"PRE_CHECK performed successfully.",
    "allowed_payment_methods": ["cc", "dd", "sofort"],
    "error_code":0
  }

Precheck API is used to run risk checks prior to making the payment. Returned transaction_id from the initial POST request to /rest/precheck should be used as original_transaction_id in the actual payment request when using Payment API right after.

Precheck can be run either for a given payment method, or without it as well. Responses slightly differ as mentioned on the right hand side.

Using Installments API with Precheck API

If you have created installments using Installments API before using Precheck API

Precheck API Request Parameters

Precheck API accepts same parameters as Payment API. You can omit return urls such as success_url and error_url, as well as order_id, if not known during checkout.

Running Precheck without knowing payment method

If payment method is not known yet during checkout stage, you may run the Precheck API without payment method specified.

In such cases, pass precheck for the value of payment_type parameter in your API request.

Precheck API Response Parameters

Precheck API response parameters are same as Payment API.

See response example on the right sidebar.

You would either receive error on unsuccessful risk check, or successful response otherwise.

Mandate Reference API

Example POST rest/create_mandate_reference payload

  {
    "payment_type": "dd",
    "api_key": "45320990e1c8467468d6"
  }

Example POST rest/create_mandate_reference response

{
  "transaction_id": "c2a6bf6d-2dd7-4a9c-b4de-2d04347d802b",
  "token": "a7678918bfbbfa449cf9ff78446b60a4",
  "status_code": 9,
  "status": "registered",
  "error_code": 0,
  "order_id": "123000"
}

// token is your mandate_reference to show to the end user

Mandate Reference API is used to create mandate references. SEPA Direct Debit transactions depend on mandates. Please, see implications of using SEPA Direct Debit.

You can either provide mandate yourself in Payment API(sepa_mandate parameter) calls, or send POST request to /rest/create_mandate_reference endpoint.

Mandates can either be one time or recurring. For recurring SEPA Direct Debit payments, use returned transaction_id as original_transaction_id in your further recurring payments when using Payment API.

Mandate Reference API Request Parameters

Parameters Required Comments
payment_type YES dd for direct debit
api_key YES Merchant-specific API key
recurring NO 1 in case of recurring mandates
first_name NO First Name of the customer.
last_name NO Last Name of the customer.
email NO Email of the customer.
address NO Street address of the customer.
address2 NO Additional address line of the customer.
city NO City of the customer.
postal_code NO Postal Code of the customer.
state NO State of the customer.
country NO Country of the customer.
phone NO Phone Number of the customer.
account_holder NO Account Holder of the bank account.
iban NO IBAN of the bank account.
bic NO BIC of the bank account.

Mandate Reference API Response Parameters

Parameters Comments
transaction_id Payment Gateway own transaction ID
status_code Transaction’s status code
status Transaction status in words
order_id Merchant’s order ID
error_code Error code; if this is 0, everything is fine
error_message If the error code is other than 0, the error message will be included here.
token Mandate reference token

Installments API

Example POST rest/calculate payload

  {
    "payment_type": "rate",
    "amount": 100,
    "api_key": "45320990e1c8467468d6"
  }

Example POST rest/calculate response

{
  "transaction_id": "654bb33d-3773-44a6-8b84-386a07b492ce",
  "status_code": 1,
  "status": "started",
  "message": "Calculation performed successfully.",
  "error_code": 0,
  "installments": [
    {
      "installment": [
        {
          "amount": "33.57",
          "due": "2021-05-05"
        },
        {
          "amount": "33.57",
          "due": "2021-06-05"
        },
        {
          "amount": "33.57",
          "due": "2021-07-05"
        }
      ],
      "original_amount": "100.00",
      "total_amount": "100.71",
      "minimum_installment_fee": "0",
      "duration": "3",
      "interest_rate": "4.95",
      "effective_interest_rate": "5.03",
      "usage": "Calculated by calculation service",
      "currency": "EUR",
      "credit_information_url": "https://test-payment.paylater.unzer.com/payolution-payment/infoport/creditagreementdraft/Tx-nj953da6x97?duration=3"
    },
    {
      "installment": [
        {
          "amount": "16.89",
          "due": "2021-05-05"
        },
        {
          "amount": "16.89",
          "due": "2021-06-05"
        },
        {
          "amount": "16.89",
          "due": "2021-07-05"
        },
        {
          "amount": "16.89",
          "due": "2021-08-05"
        },
        {
          "amount": "16.89",
          "due": "2021-09-05"
        },
        {
          "amount": "16.89",
          "due": "2021-10-05"
        }
      ],
      "original_amount": "100.00",
      "total_amount": "101.34",
      "minimum_installment_fee": "0",
      "duration": "6",
      "interest_rate": "4.95",
      "effective_interest_rate": "5.06",
      "usage": "Calculated by calculation service",
      "currency": "EUR",
      "credit_information_url": "https://test-payment.paylater.unzer.com/payolution-payment/infoport/creditagreementdraft/Tx-nj953da6x97?duration=6"
    },
    {
      "installment": [
        {
          "amount": "11.33",
          "due": "2021-05-05"
        },
        {
          "amount": "11.33",
          "due": "2021-06-05"
        },
        {
          "amount": "11.33",
          "due": "2021-07-05"
        },
        {
          "amount": "11.33",
          "due": "2021-08-05"
        },
        {
          "amount": "11.33",
          "due": "2021-09-05"
        },
        {
          "amount": "11.33",
          "due": "2021-10-05"
        },
        {
          "amount": "11.33",
          "due": "2021-11-05"
        },
        {
          "amount": "11.33",
          "due": "2021-12-05"
        },
        {
          "amount": "11.33",
          "due": "2022-01-05"
        }
      ],
      "original_amount": "100.00",
      "total_amount": "101.97",
      "minimum_installment_fee": "0",
      "duration": "9",
      "interest_rate": "4.95",
      "effective_interest_rate": "5.06",
      "usage": "Calculated by calculation service",
      "currency": "EUR",
      "credit_information_url": "https://test-payment.paylater.unzer.com/payolution-payment/infoport/creditagreementdraft/Tx-nj953da6x97?duration=9"
    },
    {
      "installment": [
        {
          "amount": "8.55",
          "due": "2021-05-05"
        },
        {
          "amount": "8.55",
          "due": "2021-06-05"
        },
        {
          "amount": "8.55",
          "due": "2021-07-05"
        },
        {
          "amount": "8.55",
          "due": "2021-08-05"
        },
        {
          "amount": "8.55",
          "due": "2021-09-05"
        },
        {
          "amount": "8.55",
          "due": "2021-10-05"
        },
        {
          "amount": "8.55",
          "due": "2021-11-05"
        },
        {
          "amount": "8.55",
          "due": "2021-12-05"
        },
        {
          "amount": "8.55",
          "due": "2022-01-05"
        },
        {
          "amount": "8.55",
          "due": "2022-02-05"
        },
        {
          "amount": "8.55",
          "due": "2022-03-05"
        },
        {
          "amount": "8.55",
          "due": "2022-04-05"
        }
      ],
      "original_amount": "100.00",
      "total_amount": "102.60",
      "minimum_installment_fee": "0",
      "duration": "12",
      "interest_rate": "4.95",
      "effective_interest_rate": "5.07",
      "usage": "Calculated by calculation service",
      "currency": "EUR",
      "credit_information_url": "https://test-payment.paylater.unzer.com/payolution-payment/infoport/creditagreementdraft/Tx-nj953da6x97?duration=12"
    }
  ]
}

Installments API is used to create installments for requested amounts. Response includes installments options that you may choose from.

Installments API Request Parameters

Parameters Required Comments
payment_type YES Payment type. It should be set to rate
api_key YES Merchant API Key
amount YES Total amount of the transaction(float number).
vat NO VAT, if known

Installments API Response Parameters

Parameters Comments
transaction_id Payment Gateway own transaction ID
status_code Transaction’s status code
status Transaction status in words
error_code Error code; if this is 0, everything worked fine.
error_message If the error code is other than 0, the error message will be included here.
installments An array where each of its element is a json object, which contains details about an installment possibility for a monthly payment.

Payment Method Info API

Example GET rest/payment_info?api_key=your_api_key&payment_type=payment_method response

{
  disclaimer: "I agree to the risk check performed by Firma AG. More information on terms and conditions available <a href='http://www.firma.de/terms'>here</a>.",
  risk_check: false
}

Some payment methods, particularly the ones that use invoice and risk checks, need end user agreement.

Since the legal disclaimers can vary between payment providers, there is a method to pull the disclaimer texts.

Response will also include information on whether risk checks will be performed with this payment method for the requested merchant.

Payment Method Information Parameters

Parameters Required Comments
api_key YES Merchant API Key
payment_type YES See payment type
locale NO Optional language flag for disclaimer texts (“de” or “en”). Note that some payment providers only support the German language.

Payment Method API Response

The response includes the following attributes

Parameters Comments
disclaimer Disclaimer text
risk_check Boolean(true or false) indicating whether the risk check is needed or not

Transactions API

Transactions API is used to view and modify transactions.

List of transactions

Example GET rest/transactions response

[  
   {  
      "transaction_id":"4927d679-7695-4a31-a901-e89dcfed3d43",
      "created_at":"2016-10-26T16:04:33.901+02:00",
      "updated_at":"2016-10-26T16:05:00.897+02:00",
      "status_code":2,
      "status":"pending",
      "amount":612.85,
      "currency":"EUR",
      "order_id":"145000188",
      "recurring": 0,
      "sepa_mandate": null,
      "parent_id": null,
      "payment_method":"kar",
      "message": "PRE_AUTH performed successfully.",
      "sepa_msg_id": null,
      "captured_amount": null
   },
   {  
      "transaction_id": "07c8b0a4-186f-4b56-a929-17d13b29c695",
      "created_at": "2016-10-26T16:03:06.394+02:00",
      "updated_at": "2016-10-26T16:03:06.416+02:00",
      "status_code": 9,
      "status": "registered",
      "amount": 0.0,
      "currency": "EUR",
      "order_id":null,
      "recurring": 0,
      "sepa_mandate": null,
      "parent_id": null,
      "payment_method": "dd",
      "message": null,
      "sepa_msg_id": null,
      "captured_amount": null
   }
]

Returns list of transactions for the merchant. By default, it will respond with 50 transactions. You can use query parameters to adjust the time-frame to get list of transactions for the given period.

Query parameters for listing transactions

Parameters Required Comments
api_key YES Merchant-specific API key
from NO Optional earliest date in ISO-8601, e.g. 2016-10-05T17:50:28+02:00
to NO Optional latest date in ISO-8601, e.g. 2016-10-05T18:50:28+02:00
status NO Optional status code or a comma-separated list of status codes, e.g. status=3 or status=2,3
currency NO Optional 3-letter currency code (ISO 4217)
checksum NO Checksum of parameters. Legacy field, we strongly suggest to skip this field.

Response parameters for listing transactions

Response will include collection of the json objects. Each object will have following parameters:

Parameters Comments
transaction_id ID of the transactions
timestamps created_at and updated_at timestamps
status_code Status code
status Status name
amount amount used in this transaction(float number)
parent_id Transaction ID of the parent, usually available for recurring transactions
currency Code of the currency that have been used
order_id Merchant’s order ID
payment_method (Payment method)(#payment_type)
message Message about the transaction
sepa_message_id Sepa message ID
sepa_mandate Mandate Reference Number (max. 35 characters)
captured_amount Captured amount if exists.

Retrieve single transaction

Example GET rest/transactions/07c8b0a4-186f-4b56-a929-17d13b29c695 response

{  
  "transaction_id": "07c8b0a4-186f-4b56-a929-17d13b29c695",
  "created_at": "2016-10-26T16:03:06.394+02:00",
  "updated_at": "2016-10-26T16:03:06.416+02:00",
  "status_code": 9,
  "status": "registered",
  "amount": 0.0,
  "currency": "EUR",
  "order_id":null,
  "recurring": 0,
  "sepa_mandate": null,
  "parent_id": null,
  "payment_method": "dd",
  "message": null,
  "sepa_msg_id": null,
  "captured_amount": null
}

Responds with single transaction. Simply append transaction_id to the /rest/transactions/transaction_id endpoint.

Query parameters for retrieving a single transaction

The request should include the following parameters:

Parameters Required Comments
api_key YES Merchant-specific API key
id YES The ID of the requested transaction
checksum NO Checksum of parameters. Legacy. We strongly suggest to skip this field.

Response parameters for retrieving a single transaction

Response parameters are identical to the one returned from List of Transactions.

Get event logs

Example GET rest/transactions/123/log response

[
  {
  "created_at": "2021-04-15T11:51:41.793+02:00",
  "type": "precheck",
  "status": 1,
  "amount": 0,
  "execution_date": null,
  "message": "Risk checks waived: no checkout flows defined."
  },
  {
  "created_at": "2021-04-15T11:51:41.821+02:00",
  "type": "authorization",
  "status": 2,
  "amount": 15.9,
  "execution_date": "2021-04-12",
  "message": null
  },
  {
  "created_at": "2021-04-15T11:51:42.635+02:00",
  "type": "postback",
  "status": 2,
  "amount": 0,
  "execution_date": null,
  "message": "Transaction 445 postback completed successfully."
  },
  {
  "created_at": "2021-04-15T11:53:49.405+02:00",
  "type": "reauthorization",
  "status": 2,
  "amount": 20,
  "execution_date": "2021-04-15",
  "message": "Amount changed"
  }
]

Use this endpoint to receive event logs for the requested transaction. Please note that, not all attributes are applicable for all event types. For instance, postback events do not use amount, so the amount is stored as zero.

Execution date is for informative purposes only and can be entered when calling certain invoice operations.(authorize, capture, reverse and refund).

Event log endpoint query parameters

The request should include the following parameters:

Parameters Required Comments
api_key YES Merchant-specific API key
id YES The ID of the requested transaction
checksum NO Checksum of parameters. Legacy. We strongly recommend to skip this field.

Get a summary

Example rest/transactions/summary response

{
  "count":9,
  "total_amount":858.75
}

Use this endpoint when you would like to get a summary of the list of transactions.

Request to this endpoint will return the total sum of transaction amounts and the number of transactions found in the data set.

Query parameters for summary

Parameters Required Comments
api_key YES Merchant-specific API key
from NO Optional earliest date in ISO-8601, e.g. 2016-10-05T17:50:28+02:00
to NO Optional latest date in ISO-8601, e.g. 2016-10-05T18:50:28+02:00
status NO Optional status code or a comma-separated list of status codes, e.g. status=3 or status=2,3
currency NO Optional 3-letter currency code(ISO 4217)
checksum NO Checksum of parameters. Legacy. We strongly suggest to skip this field.

Response parameters for summary

Parameters Comments
count Number of transactions in the summary.
total_amount Sum of amounts of transactions in the summary.

Update a transaction

Example POST rest/update_data payload

  {
    "transaction_id": "0b3c2327-9394-4ab4-be18-6e9d85e650ed",
    "invoice_id": "newinvoice-id",
    "invoice_date": "01/12/2020"
  }

Example POST rest/update_data response

{  
   "transaction_id":"0b3c2327-9394-4ab4-be18-6e9d85e650ed",
   "order_id":"122",
   "status_code":2,
   "status":"pending",
   "error_code":0
}

You can update invoice_id and invoice_date values of any given transaction by sending a POST request to rest/update_data endpoint.

Request Parameters for updating a transaction

Parameters Required Comments
api_key YES Merchant API Key
transaction_id YES Transaction to be updated
invoice_id NO ID to provide the invoice number of a Merchant’s order
invoice_date NO Date to provide the invoice date of a Merchant’s order
checksum NO Checksum of parameters. Legacy field. We strongly suggest to skip this field when using BASIC AUTH

Response parameters for updating a transaction

Parameters Comments
transaction_id Payment Gateway own transaction ID
order_id The order ID specified by the merchant
status_code Transaction’s status code
status Transaction status in words
error_code Error code; if this is 0, everything is fine
error_message If the error code is other than 0, the error message will be included here.

Submitting transaction to Debt Collection

Some transactions will be sent to debt collection or factoring, under following conditions:

Exact conditions whether it will be sent to collection or factoring depends on merchant's configuration.

The result is a JSON object of transaction details, just like in the single transaction request. If a debt claim has been successfully submitted, the status will be "debt_collection" or "factoring".

Status Change

Example GET rest/transactions/07c8b0a4-186f-4b56-a929-17d13b29c695/change_status?status=completed response

{  
  "transaction_id": "07c8b0a4-186f-4b56-a929-17d13b29c695",
  "created_at": "2016-10-26T16:03:06.394+02:00",
  "updated_at": "2016-10-26T16:03:06.416+02:00",
  "status_code": 9,
  "status": "completed",
  "amount": 0.0,
  "currency": "EUR",
  "order_id":null,
  "recurring": 0,
  "sepa_mandate": null,
  "parent_id": null,
  "payment_method": "dd",
  "message": null,
  "sepa_msg_id": null,
  "captured_amount": null
}

Using this endpoint, you can change the status of the transaction manually. This endpoint is usually used with Invoice transactions that has no automatic way of marking its status completed.

New statuses are limited to the list below in the notice, and it's not possible to change transactions with certain current statuses, such as cancelled, error.

Status Change Request Parameters

Parameters Required Comments
api_key YES Merchant-specific API key
status YES The new status.
transaction_id YES ID of the transactions
debt_collection_id NO debt collection ID
checksum NO Checksum. Legacy. We strongly suggest to skip this field.

Status Change Response Parameters

Parameters Comments
transaction_id ID of the transactions
timestamps created_at and updated_at timestamps
status_code Status code
status Status name
amount amount used in this transaction(float number)
parent_id Transaction ID of the parent, usually available for recurring transactions
currency Code of the currency that have been used
order_id Merchant’s order ID
payment_method (Payment method)(#payment_type)
message Message about the transaction
sepa_message_id Sepa message ID
sepa_mandate Mandate Reference Number (max. 35 characters)
captured_amount Captured amount if exists.

Payment Page Theme API

Using Payment Page Theme API, you can manage your payment page themes. This endpoint is considered legacy and only affects legacy payment page.

The payment page can be customized with a color theme. The parameters of the page are listed in the following table and each parameter can be altered with an API call.

Please note that color values c1 to c10 can be given in hex or rgba color codes. If no value is given for an optional parameter then the default color from the payment page will be used.

Legacy Payment Page Theme Parameters

Payment Page theme settings

Parameters Required Comments
name YES Theme name for url path
font NO CSS fonts
c1 NO Input field text(hex or rgba)
c2 NO Background(hex or rgba)
c3 NO Border(hex or rgba)
c4 NO Input field background, submit button text(hex or rgba)
c5 NO Submit button, input field label (hex or rgba)
c6 NO Info button background (hex or rgba)
c7 NO Info button background on hover (hex or rgba)
c8 NO Info box background (hex or rgba)
c9 NO Info box text (hex or rgba)
c10 NO Submit button on hover (hex or rgba)
checksum NO Checksum of parameters. Legacy. We strongly suggest to skip this field when using BASIC AUTH.

List Merchant Themes

Example GET rest/merchant_themes response

[
  {  
    "id": 17,
    "merchant_id": 212,
    "name": "My Theme",
    "font": "Fira Sans",
    "c1": "#868686",
    "c2": "#fff",
    "c3": "#abb0b6",
    "c4": "#fefefe",
    "c5": "#59A618",
    "c6": "rgba(111, 208, 30, 1)",
    "c7": "rgba(255, 204, 0, 1)",
    "c8": "#ffc73e",
    "c9": "#0a0a0a",
    "c10": "#77de20",
    "created_at": "2018-02-20T13:29:22.454+01:00",
    "updated_at": "2018-02-20T13:29:22.454+01:00"
  },
  {  
    "id": 18,
    "merchant_id": 212,
    "name": "My Theme 2",
    "font": "Fira Sans",
    "c1": "#868686",
    "c2": "#fff",
    "c3": "#abb0b6",
    "c4": "#fefefe",
    "c5": "#59A618",
    "c6": "rgba(111, 208, 30, 1)",
    "c7": "rgba(255, 204, 0, 1)",
    "c8": "#ffc73e",
    "c9": "#0a0a0a",
    "c10": "#77de20",
    "created_at": "2018-02-20T13:29:22.454+01:00",
    "updated_at": "2018-02-20T13:29:22.454+01:00"
  }
]

Returns list of currently available themes for the given merchant.

Setting up a new theme

Example POST rest/merchant_themes payload

{
  "name": "my_new_theme",
  "font": "Fira Sans"
}

Example POST rest/merchant_themes response

{  
   "id":17,
   "merchant_id":212,
   "name":"my_new_theme",
   "font":"Fira Sans",
   "c1":"#868686",
   "c2":"#fff",
   "c3":"#abb0b6",
   "c4":"#fefefe",
   "c5":"#59A618",
   "c6":"rgba(111, 208, 30, 1)",
   "c7":"rgba(255, 204, 0, 1)",
   "c8":"#ffc73e",
   "c9":"#0a0a0a",
   "c10":"#77de20",
   "created_at":"2018-02-20T13:29:22.454+01:00",
   "updated_at":"2018-02-20T13:29:22.454+01:00"
}

Post a payload to rest/merchant_themes endpoint to create a new theme. You may choose to post all parameters which are shown above in the list of Payment Page Theme Parameters.

Update an existing theme

Example PATCH rest/merchant_themes/:theme_id payload

  {
    "name": "changed_name"
  }

Example PATCH rest/merchant_themes/:theme_id response

{  
   "id":17,
   "merchant_id":212,
   "name":"changed_name",
   "font":"Fira Sans",
   "c1":"#868686",
   "c2":"#fff",
   "c3":"#abb0b6",
   "c4":"#fefefe",
   "c5":"#59A618",
   "c6":"rgba(111, 208, 30, 1)",
   "c7":"rgba(255, 204, 0, 1)",
   "c8":"#ffc73e",
   "c9":"#0a0a0a",
   "c10":"#77de20",
   "created_at":"2018-02-20T13:29:22.454+01:00",
   "updated_at":"2018-02-20T13:29:22.454+01:00"
}

By sending PATCH request to rest/merchant_themes/:theme_id, you can update the existing theme. All parameters mentioned in Payment Page Theme configuration above can be updated.

Viewing an existing theme

By sending GET request to rest/merchant_themes/:theme_id you can get information for the requested theme.

Response is identical to the ones mentioned above.

Jetztzahlen Import API

Example rest/import request

{
  "url_name": "test_url",
  "batch_name": "any optional note you would like to add",
  "invoices": [
    {
        "debt_claim_number": "123",
        "amount": 1.99,
        "print_date": "12.10.2018",
        "first_name": "Peter",
        "last_name": "Mustermann",
        "address": "Egal Str. 1",
        "postal_code": "10434",
        "city": "Berlin",
        "email": "test@testov.com",
        "country":"Deutschland"
    },
    {
        "debt_claim_number": "124",
        "amount": 1.94,
        "print_date": "2.3.2018",
        "first_name": "Petra",
        "last_name": "Mustermann",
        "address": "Egal Str. 1",
        "postal_code": "10434",
        "city": "Berlin",
        "email": "test@testov.com",
        "country": "Deutschland"
    }
  ]
}

Example rest/import response

{
  "message": "Invoices have been successfully imported."
}

Jetztzahlen Import API is used to create invoice records for your Jetztzahlen channels.

Import API parameters

Parameters Required Comments
url_name YES url_name of the channel. You can find under channel configurations in the Jetztzahlen Dashboard.
batch_name NO A reference you would like to add to this batch import. Optional
invoices YES An array of invoice params as hash. See below for invoice params.

Invoice params

Parameters Required Comments
debt_claim_number YES Invoice number
amount YES Amount for the invoice. One EUR and 90 CENTS is represented as 1.90.
print_date YES Due date for the invoice. DD-MM-YYYY format.
first_name NO First name of the payee
last_name NO Last name of the payee
address NO Address of the payee
postal_code NO Postal code of the payee
city NO City of the payee
email NO Email of the payee
country NO Country of the payee. Full country name either in English or German.

Jetztzahlen Invoice API

Example rest/invoices/fhd-12102020 response

{
  "invoice": {
    "id": 29235,
    "status": "pending",
    "created_at": "2019-07-30T22:49:02.081+02:00",
    "updated_at": "2019-07-30T22:49:02.081+02:00",
    "channel_id": 5,
    "merchant_prefix": "test",
    "debt_claim_number": "fhd-12102020",
    "print_date": "2019-07-02",
    "first_name": "",
    "last_name": "",
    "address": "",
    "postal_code": "",
    "city": "",
    "import_id": 13,
    "amount_cents": 1200,
    "description": "",
    "country": "",
    "active": true
  },
  "paylink": "http://yourchannel.jetztzahlen.de/pay/fhd-12102020"
}

Jetztzahlen Invoice API is used to retrieve a specific invoice by its invoice/debt claim number. You can get information such as -- if it's paid or not, active or not, direct payment links and more.

Request parameters

Parameters Comments
invoice_number Append invoice number to /rest/invoices/invoice_number

Response Parameters

The response includes the following attributes

Parameters Comments
invoice Hash containing invoice information
paylink Link that you can send to your customers to open the payment page directly.

Invoice hash response parameters

Parameters in the invoice hash returned above

Parameters Comments
ID ID of the invoice in the system
debt_claim_number Invoice number
status "pending" if unpaid, "paid" if paid
timestamps created_at and updated_at timestamps
merchant_prefix Legacy field, can be ignored.
channel_id ID Channel that invoice belongs to
amount_cents Amount of invoice in cents
print_date Due date for the invoice. DD-MM-YYYY format.
first_name First name of the payee
last_name Last name of the payee
address Address of the payee
postal_code Postal code of the payee
city City of the payee
email Email of the payee
country Country of the payee. Full country name either in English or German.
import_id ID of the batch Import invoice belongs to
active true or false. If false, invoice will not be available for payment

Payment Methods

This section explains usage of different payment methods and their specific details and implications.

Credit Card

When integration Credit Card payments with us, merchant's shop/website will need to redirect the customer to the Payment Page that is hosted by us.

Customers proceed to enter their their Credit Card information and then our system will redirect back to your given success or error URLs depending on the outcome of the transaction.

When making the 1st recurring transaction, same redirection flow is expected to be completed. However, further recurring payments will only need a reference to an original(1st) transaction's ID without requiring the merchant's website to redirect any further.

Implementation flow

Example response for credit card with redirect client action

{
  "transaction_id": "d1bf9fdf-7268-406f-9e08-8d5a9540ab97",
  "order_id": "123000",
  "error_code": 0,
  "status_code": 1,
  "status": "started",
  "client_action": "redirect",
  "action_data": {
    "url": "https://testapi.betterpayment.de/payment/d1bf9fdf-7268-406f-9e08-8d5a9540ab97?custom_pay_text="
  }
}

Running Payment Page in your own website within an Iframe

It's possible to render our payment page within an Iframe, so the customer never have to leave the merchant's shop.

After completing the payment, the web page in the merchant’s success/error URL can include a JavaScript code snippet that breaks out of the Iframe if needed.

3DS2 Requirements

We strongly suggest to provide a complete billing information, specifically following fields when creating Credit Card transactions:

If you fail to provide these fields, transaction will still successfully be created in our system. However, it's strong possibility that the customer's payment will be declined due to insufficient information that is required by 3DS2 enabled cards and payment method configurations.

SEPA Direct Debit

When implementing SEPA Direct Debit transactions, you first need to see implications of using this payment method.

Once you have familiarized yourself with the implications, you either need to send us sepa_mandate value when using Payment API to create payments OR use Mandate Reference API prior to creating a payment.

SEPA Mandates has to be shown to the customer in the checkout, prior to making the payment, and customer should agree to the collection of the debit amount.

SEPA Direct Debit (B2B)

Same as SEPA Direct Debit, but for B2B clients.

Purchase On Account

Purchase on Account, also known as Invoice or Kauf auf Rechnung in German, offers the possibility to pay the invoice after receiving the goods.

To minimize the possibility of defaults, invoice payments should include a risk check procedure.

If the customer fails to pass the certain risk check flow conditions, an error is returned and transaction is deemed unsuccessful.

In these cases, it's best to offer an alternative payment method.

Purchase on Account (B2B)

Same as Purchase on Account, but for B2B clients.

Installments

With Installments payment method, customer may pay the sum in several monthly parts. First, you will need to use Installments API which returns the possible installment options.

You would then need to create a Payment using Payment API with the reference of the ID that was returned from Installment API use.

Giropay

Example POST /rest/payment response for Giropay

{
  "transaction_id": "3b5836ae-add6-4ab2-a878-6c9c3a3ffe8d",
  "order_id": "123000",
  "error_code": 0,
  "status_code": 1,
  "status": "started",
  "client_action": "postform",
  "action_data": {
    "url": "https://payment.girosolution.de/payment/start",
    "fields": {
      "urlRedirect": "https://sandboxapi.betterpayment.de/payment_response/9",
      "urlNotify": "https://sandboxapi.betterpayment.de/payment_postback/9",
      "sourceId": "6da0f976433e18641662198d98557955",
      "merchantId": "3606200",
      "projectId": "5678",
      "amount": "15.9",
      "transactionId": "3b5836ae-add6-4ab2-a878-6c9c3a3ffe8d",
      "currency": "EUR",
      "vwz": "Merchant Name",
      "hash": "0e9e4022f143299cc43a91a3fac96f0c"
    }
  }
}

Giropay is a service offered by GiroSolution that redirects the user to a website where they can complete the transaction by entering their bank account information and login credentials. The user confirms the transaction with their personal TAN code, after which the browser is redirected back to the merchant’s website.

Implementation flow of the Giropay is a little bit different than normal redirection flow seen in Sofort, Credit Card, Paydirekt and PayPal payment methods.

In Giropay, a POST request to /rest/payment will return a client_action which will include form data to submit to given url in the response. Once you submit that form to the given URL, customer will be redirected to the Giropay's payment platform automatically. Once customer completes the payment, they will return to your given success or error URL, depending on the outcome of the transaction.

Sofort (Klarna)

SOFORT Überweisung is an online payment service which is offered by SOFORT AG. Technically it is very similar to Credit Card, PayPal and Paydirekt flow. The user is redirected to a payment site hosted by SOFORT and returns back to the merchant’s site after completing the transaction.

PayPal

PayPal is an online payment service offered by PayPal Inc. It is also very similar to SOFORT. The user is redirected to a payment site hosted by PayPal and returns back to the Merchant's site after completing the transaction.

Paypal could be used for recurring payments where PayPal Reference Transactions are used. This is a feature PayPal only makes available on explicit request by the customer.

You will have to contact PayPal to activate this feature in your account before being able to make any recurring PayPal payments.

Barzahlen (viacash)

Example POST rest/payment response for Barzahlen

{
  "transaction_id": "93340f3f-ead3-46c2-8cf1-68fdb3ee0d55",
  "order_id": "123000",
  "error_code": 0,
  "status_code": 2,
  "status": "pending",
  "checkout_token": "djF8Y2hrdHxzbHAtODc2ZmZmODAtMmUzYS00MWYyLWE0YWUtMDEwZWJlYzFmY2RhfE8wSklqZHhNV3ZIL1J4SG15SzBvNDl3ZVVaQXp3dFNwZGxUa2tVY0FYSDA9"
}

Barzahlen is a special payment method that generates invoice slips and allows customers to pay at Barzahlen retail partner stores by cash.

The customer receives the invoice by email or SMS and can also view it when completing the order in the merchant’s webshop. When the cash payment is registered by a retail partner store, the merchant is notified of the completed payment via the postback URL.

Implementing Barzahlen payment method requires running a Barzahlen's javascript plugin in merchant's website. Flow is as follows:

You can get more info on viacash or use the scripts below:

For test environment: https://cdn.barzahlen.de/js/v2/checkout-sandbox.js

For production environment: https://cdn.barzahlen.de/js/v2/checkout.js

Include the script on your payment confirmation page as shown on the right hand side.

<script scr="https://cdn.barzahlen.de/js/v2/checkout.js" class="bz-checkout" type="test/javascript" data-token="CHECKOUT_TOKEN_GOES_HERE">

Paydirekt

Paydirekt is a payment method offered by German Banks and Sparkassen. It is also similar to Sofort, whereas the user is redirected to a payment site hosted by Paydirekt and returns back to the merchant's site after completing the transaction.

Advance Payment

Advance payment (Vorkasse) records transactions where the customer promises to pay the merchant.

This is rather a simple payment method option,which does not have any automatic updates nor requires any redirections. You will have to mark your transactions manually over Transactions API if you want their status to change and displayed as such in the Dashboard.

iDeal

A payment method that is used in the Netherland. Same redirection flow is applied as seen in Sofort, Credit Cards, Paypal, Giropay.

When using this Payment Method, you have to provide first_name and last_name in the billing address.

Risk Checks

Risk check involves validating the user’s address and identity (through name, date of birth and gender) as well as calculating the user’s credit score.

Risk check is optional and can be enabled with every payment method, but it is usually used with Invoice/Purchase on Account transactions to reduce possibility of defaults. Data used in the risk check is forwarded to the scoring provider. Users always have to be informed about the risk check and give their explicit approval.

For payment methods that have risk check enabled, the risk check is always performed first, prior to connecting to the acquirer with payment details. If the user does not pass the risk check, the API will return an error and the merchant should inform the user and suggest an alternative payment method.

How is it configured?

Merchants are able to configure risk check flows for their account during onboarding with us.

Risk Check Approvals

The customer must explicitly give his or her approval for risk checks. If the risk_check_approval value which is passed in payment calls is anything other than 1, an error is triggered.

Postbacks

On completing the transaction, the API will perform a POST request to the URL specified in postback_url before redirecting the user to the Merchant’s website. The purpose of this additional request is to pass transaction information to the Merchant without the end user seeing the contents, and to ensure the Merchant is informed about completing the transaction even if the user for some reason does not return to the Merchant’s website. The following data will be posted in all postback requests:

Parameters Comments
transaction_id ID of the transactions
status_code Status code
status Status name
order_id Merchant’s order ID
message Additional info about the transactions status
checksum Checksum of parameters. Same logic is applied but with incoming key instead of outgoing key. So, use your incoming key to verify the message integrity.

Postbacks will also be sent when transaction's status change after some time. For instance, a payment may be charge-backed by the customer after some time has passed since the payment.

In such cases, you will receive a new postback, which you can act upon.

Appendix

Parameters Details

Payment Types

Locales

The following languages options are available:

Merchant Reference

What to display as the reference on the customer’s bank statement.

Original Transaction ID

This parameter is used to perform a payment after

Where original_transaction_id would be the transaction_id returned from any of these requests' response.

This returned transaction_id can then be used as original_transaction_id when creating further payments. This is used mostly in recurring payments.

Recurring Payments

recurring parameter is set to 1 when a merchant wants to make a recurring payment.

Client redirections

Some payment methods require the client to redirect after the initial POST request to our Payment APIs. Client action is either redirect or postform.

Client Action

After posting a payment request, the action could be a postform or a redirect as the following:

Action Data

If client_action is specified, this array includes the following data:

In order to conform with International and German Law, information about the SEPA purchase needs to be shown to the paying customer in the case of an initial SEPA Direct Debit payment. Here is one example how such information text might look like:

Information Text

Mandate reference:

I hereby legitimate to conduct payments via direct debit to settle outstanding amounts. I further instruct my bank to service direct debit payments initiated by .

Surname, name: #surname>, #name Street, number: #Street, #No
Postcode, city: #post code, #city
Holder name: #holder name
IBAN: #iban
BIC: #bic

Notice: Within eight weeks time from the date of charge, you can demand a full refund of the charged amount. Please regard the terms and conditions for refunds of your bank, which apply.

"checkbox (required)" I hereby confirm that I have the authority to grant the mandate to the SEPA direct debit transaction(s) displayed above. I hereby grant the mandate.

Be aware that the text for a recurring mandate differs from this.

Additionally a customer must receive a pre notification if a recurring payment occurs, the text of the pre-notification might look something like:

We will debit your bank account with € 12.70 maturing March 13th 2015.

The customer must also be informed about the mandate number (not to be confused with mandate_reference). This number can be shown after the payment has been processed, or be sent via Email later.

Test Payment Data

You can use following test credentials, account and card numbers to perform transactions on test environments. Test data is configured to work with EUR currency.

Credit Card Payments

VISA

Any name and 3-digit ccv could be used with expiry date in the future.

Mastercard

Any name and 3-digit ccv could be used with expiry date in the future.

Giropay Payments

SOFORT Payments

Paydirekt Payments

User Name Password Restrictions
BetterPaymentGermany_SDE-Kaeufer SDE-Kaeufer2$ standard user
BetterPaymentGermany_unterAchtzehn unterAchtzehn2$ user under 18 years old
BetterPaymentGermany_SperreKB SperreKB2$ buyers of paydirekt are blocked

Paypal Payments

SEPA Direct Debit Payments

Barzahlen Payments

No test data required. Created transactions will stay pending, as in test environment it's not possible to imitate the completed status change.

iDEAL Payments

iDEAL provides test data directly in the payment page.

Invoice B2C Payments (Bonitätsprüfung)

Transaction Events

Following is list of transaction event types that may be returned from using Transactions API's Event Log endpoint.

Transaction Statuses

Code Status Description
1 started Transaction has been started. User has been redirected to the acquirer’s website. Transactions that remain in this state for longer than an hour should be considered aborted by the user except for SEPA Direct Debit transactions. Direct Debit transaction may take up to 24 hours to change their state from started to pending.
2 pending Credit card payments: The user submitted the payment, but the acquirer has marked the transaction as pending. This usually means that it takes longer than average to complete the transaction.
Invoice payments: The order has been accepted, but payment has to be confirmed manually by the merchant, captured over the API(depending on the acquirer), or captured by the automated system if inbound monitoring is enabled.
The pending status is treated as a successful payment for rest of the payment methods. The API returns a successful state or redirects to the merchant's success URL
3 completed Credit card payments: The acquirer has marked the transaction as completed.
Invoice payments: transaction has been marked completed by either manual or automatic processing.
Payment is successful. API returns a successful state or redirects to success URL.
4 error There has been an error with the transaction.
API returns an error state or redirects to the shop’s error URL.
5 canceled User has canceled the payment on the acquirer’s website.
API redirects to the error URL or returns a canceled status.
6 declined The acquirer has declined the payment. Payments that require a risk check are marked as declined if the risk check fails.
API returns a declined state or redirects to the shop’s error URL.
7 refunded There are partial or full refunds for this transaction.
This status is usually not returned by the API but visible in the merchant portal after refunds have been made.
8 authorized The payment has been authorized successfully but not yet executed.
This payment should be captured or reversed later.
9 registered A credit card has been registered for this transaction but payment has not been executed.
OR:
A successful precheck has been completed but the transaction is not yet authorized.
This transaction should be completed using the payment request.
10 debt_collection A debt collection process has been initiated for this transaction.
The transaction has gone into debt collection. Awaiting further status updates.
11 debt_paid The debt collection process has been completed for this transaction.
The debt has been collected and the transaction is considered successful.
12 reversed Authorization has been reversed (canceled).
The transaction is considered canceled.
13 chargeback A Chargeback has been issued for a completed or pending transaction.
14 factoring The transaction has entered factoring
The transaction is considered successful because the merchant is assumed to have received the money from the factoring party.
15 debt_declined Debt collection has been declined (for instance, because of insufficient data).
16 factoring_declined Factoring has been declined (for instance, because of insufficient risk checks).

Errors

API responses may return following codes and messages in case of any errors.

Code Message Meaning Action
101 Merchant not found. The Merchant does not exist or was not recognized. Check the API key.
102 Transaction not found. Transaction does not exist. Rare; may occur when redirecting back from the acquirer. Try again later or contact us.
103 The checksum does not match. The calculation algorithm or the outgoing key is invalid. Check the checksum calculation algorithm and the outgoing key. Pay particular attention not to confuse outgoing and incoming keys.
104 Unsupported payment type. Payment method does not exist or merchant does not have this payment method configured. Find your payment method from list in Appendix or contact us for setting up required payment method.
105 Deprecated.
106 The payment processor is not responding. Acquirer is not responding. Try again later.
107 There has been an error with the payment processor. Acquirer service is not responding or returning errors. Try again later or contact us.
108 Payment error Acquirer returned a payment-related error.Includes more information in the message if available. Look into error message and contact us if required.
109 Merchant does not have payment processor for this payment type. No acquirer has been defined for the merchant. Contact us.
110 Customer did not agree to the risk check process required by this payment method. Customer must explicitly agree to the risk check process. Check risk_check_approval. Remind the customer that risk check must be approved.
111 Risk check processor not found. System error We probably already noticed this error and working on it. Contact us if necessary.
112 Customer did not pass the risk check. Customer had insufficient risk check score, wasn’t identified by the risk check service or the address does not exist. Inform the customer and suggest alternative payment methods.
113 There has been an error with the risk check. Error in the risk check processor’s service. Try again later.
114 Too many risk check attempts from this address. Customer from the same IP has attempted to submit an order (and failed the risk check) multiple times, possibly with different personal/address data. .Suggest an alternative payment method.
115 Payment provider not found. System error. We probably already noticed this error and working on it. Contact us if necessary.
116 Risk check adapter not found. System error. We probably already noticed this error and working on it. Contact us if necessary.
117 Payment adapter not found. System error. We probably already noticed this error and working on it. Contact us if necessary.
118 Recurring payment could not find the original transaction. You are trying to run a recurring transaction, but the original transaction was not found. Provide or check original_transaction_id's validity.
119 This payment processor does not support recurring payments. You are trying to make a recurring payment with an acquirer that doesn’t support recurring payments. Make a new non-recurring payment.
120 Recurring payment could not find the original payment token. The tokens needed to make a repeat transaction with the acquirer could not be found. Most likely the acquirer did not support recurring payments at the time of the original transaction. Make a new non-recurring transaction.
121 This payment processor does not support refunds. Refunds cannot be made for this acquirer. Contact us if the transaction MUST be refunded.
122 The refunded amount cannot exceed the original amount. Combined amount of past refunds for this transaction is larger than the original amount. Check the amount to be refunded.
123 This currency is not supported. The selected currency is not supported by this acquirer. Make sure provided currency code is valid and try another currency otherwise.
124 Invalid country code. The country has not been specified in the correct format. Make sure the country code is in the ISO 3166-1 format.
125 Invalid or missing return URLs. No valid return URLs have been specified in the payment request. Check the parameters success_url, error_url and postback_url.
126 Invalid bank account information. The bank data of a direct debit transaction does not pass the validation. Check IBAN and BIC
127 This payment processor does not support authorization. The payment processor does not support authorize/capture/reverse operations. Use payment call or contact us.
128 Transaction has not been authorized for capture or reverse operation. The status of transaction is other than “authorized”, that is, it has already been captured or reversed or was not authorized to begin with. Create a new payment.
129 Deprecated ---
130 Error converting legacy bank information to IBAN/BIC. (No longer used, because legacy parameters are no longer accepted.) Use IBAN or BIC instead.
131 This payment processor does not support Mandate generation. SEPA Mandate generation cannot be used with this payment processor Use payment call.
132 Reserved Reserved
134 Amount cannot be zero or negative. Payments with zero or negative amounts are rejected by all acquirers. Only send payments with an amount greater than zero.
135 Payouts not supported. Payment processor does not support payouts. Make sure the payment processor you are using supports payouts.
136 Transaction status change not possible. The status change is not permitted or logical, for example trying to change a cancelled transaction to completed. Try another status or contact us.
137 Debt collector not found. The debt collector assigned for the merchant does not exist or is not working. Contact us.
138 Debt collections for this merchant are not supported. This merchant does not have debt collections enabled. Contact us.
139 The debt collector returned an error
140 Amount submitted to debt collection does not match transaction amount The verify_amount option, if used, must match the transaction amount. Verify that the transaction amount is correct before retrying.
141 Factoring allowance exceeded. Merchant has exceeded the limit of factored transaction amounts within a set time limit. Contact us to raise the limit or try again in a new calendar month/year.
142 Age conditions for debt claim are not met. Transaction is too new or too old to be sent to debt collection or factoring. Try again later or contact us to change age limits.
144 Unauthorized. The passed credentials are invalid. Check your api_key and outgoing_key
145 Channel cannot be found. Provided url_name does not match to any active channels. Check url_name.
146 Import error: related error message. Import error will describe any validations that the request could not pass.