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:

• Make a key/value list of all used parameters (except the checksum itself), in the same order they are posted to the API request
• Convert parameters into a query string using the application/x-www-form-urlencoded format (RFC 1738). See below for more information on how to do the conversion.
• Append the outgoing key to the query string
• Calculate the SHA1 digest of the resulting string
• Set the value of the checksum parameter to the SHA1 digest

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

Please, keep the following in mind:

• That the order of parameters passed in the request MUST match the order that you have calculated the checksum
• That you have verified your API and Outgoing key
• That you are sending request in correct environment. E.g test vs production.

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	X
giropay	X	X			X
Sofort	X	X			X
PayPal	X	X	(X)		X	(X)	PayPal Subscriptions Special Parameters
Barzahlen	X	X
Paydirekt	X	X			X
Request To Pay	X	X			X
Advance Payment	X	X
iDeal	X	X			X
Bancontact	X	X			X
MyBank	X	X			X
BLIK	X	X			X
eps	X	X			X
PayU	X	X			X
Apple Pay	X	X					Apple Pay Special Parameters
Boleto	X	X					Company Details Parameters
Boleto B2B	X	X					Company Details Parameters
PIX	X	X
AiiA	X	X			X
SmartPay	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 (*optional if using Basic Auth)
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
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
additional_transaction_data	NO	Additional payment information provided by you. This will be shown in the dashboard as well as when you query for transaction data. It will also be sent back to your postback_url as part of the postback data.

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	NO*	Customer’s last email. We suggest to provide an email when transaction's payment method type is CC(credit card) to avoid declines in 3DS2.
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, d for diverse

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.

• order_id
• transaction_id
• checksum(optional)

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:

• Create a regular payment with a special parameter: recurring = 1
• Store the transaction_id parameter from the response of the first payment request
• Create any number of repeat payments with the following parameters: recurring = 1 and original_transaction_id = transaction_id from the first transaction

Parameters and flows differ for PayPal Subscriptions. Please follow PayPal Subscriptions section for more information.

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

Apple Pay Special Parameters

Request to Payment API with an Apple Pay payment method, requires encrypted apple_pay_token json payload to be passed in.

Parameters	Required	Comments
apple_pay_token	YES	Encrypted Apple Pay token in JSON format

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 (*optional if using Basic Auth)
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 (*optional if using Basic Auth)
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.

• Send a POST request to /rest/register.
• Redirect the end user to the returned URL.
• End user inputs credit card data and gets redirected back to Merchant’s shop.
• Transaction status should now be registered. Keep the transaction_id for use in original_transaction_id field in further requests.
• Make a payment request to rest/payment using Payment API. Fill original_transaction_id= with the ID from the register call above in the request body. Set recurring=1 if you intend to make recurring payments.

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 (*optional if using Basic Auth)
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)
pix_key	NO	Optional. Can be passed to transactions made with Credit Card in Brazil, to process refunds through PIX payment method, instead of natively.
pix_key_type	NO	Optional. Can be passed to transactions made with Credit Card in Brazil, to process refunds through PIX payment method, instead of natively. Values can be one of the following: "EMAIL", "CPF", "CNPJ", "EVP", "PHONE", "CHAVE_ALEATORIA"
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 (*optional if using Basic Auth)
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)
payout_email	NO*	Required for Pay Pal Payouts. E-mail address of the client who receives the payout
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.

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 (*optional if using Basic Auth)
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

Cancellation API

Example POST rest/cancel payload

  {
    // Must be ID of the transaction that was created to start the subscription.
    "transaction_id": "c2a6bf6d-2dd7-4a9c-b4de-2d04347d802b", 
    "reason": "no reason",
    "api_key": "45320990e1c8467468d6"
  }

Example POST rest/cancel response

{
  "transaction_id": "c2a6bf6d-2dd7-4a9c-b4de-2d04347d802b",
  "token": "a7678918bfbbfa449cf9ff78446b60a4",
  "status_code": 5,
  "status": "canceled",
  "paypal_subscription_id": "I-B3452HHDSD",
  "paypal_plan_id": "I-DSJA4533BDH",
  "error_code": 0,
  "order_id": "123000"
}

Cancellation API is used to cancel subscription transactions made in the Payment Gateway. Transaction ID of the transaction that was initially created for registration of the subscription must be passed to stop further transactions.

Cancellation API Request Parameters

Parameters	Required	Comments
api_key	YES*	Merchant-specific API key (*optional if using Basic Auth)
transaction_id	YES	Transaction ID of the original transaction created for initiation of the subscription
reason	NO	Reason for the subscription. Defaults to "NO REASON"

Cancellation 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
paypal_subscription_id	ID of the PayPal Subscription
paypal_plan_id	ID of the PayPal Plan
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

Revisal API

Example POST rest/revise request

  {
    // Must be ID of the transaction that was created to start the subscription.
    "transaction_id": "c2a6bf6d-2dd7-4a9c-b4de-2d04347d802b", 
    "api_key": "45320990e1c8467468d6",
    "paypal_plan_id": "P-6UK2193323222643NMFJN66Q",
    "paypal_subscription_quantity": "6",
    "effective_time": "2021-11-30T20:47:25Z"
  }

Example POST rest/revise response

{
    "transaction_id": "dbd3ab13-38f3-49da-9e12-47ef445b0b72",
    "order_id": "123000",
    "error_code": 0,
    "status_code": 9,
    "status": "registered",
    "client_action": "redirect",
    "action_data": {
        "url": "https://www.sandbox.paypal.com/webapps/billing/subscriptions?ba_token=BA-0M029980WL960863C"
    }
}

Revisal API is used to update subscription information on an existing approved subscription transaction using PayPal.

Revisal API Request Parameters

Parameters	Required	Comments
api_key	YES*	Merchant-specific API key (*optional if using Basic Auth)
transaction_id	YES	Transaction ID of the original transaction created for initiation of the subscription
paypal_plan_id	YES	ID of the PayPal Plan
paypal_subscription_quantity	NO	Subscription quantity.
effective_time	NO	Time for changes to take effect. Defaults to current time. Has to be in this format. E.g 2021-09-29T11:47:25Z
shipping_costs	NO	Should be set if the order includes any shipping costs (float number)
shipping_address	NO	Street address
shipping_address2	NO	Second address line
shipping_company	NO	Name of the company of the given shipping address
shipping_city	NO	The town, district or city of the shipping address
shipping_postal_code	NO	The postal code or zip code of the shipping address
shipping_state	NO	The county, state or region of the shipping address
shipping_country	NO	Country Code in ISO 3166-1 alpha2
shipping_first_name	NO	Customer’s first name
shipping_last_name	NO	Customer’s last name

Revisal API Response Parameters

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. 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

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 (*optional if using Basic Auth)
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 (*optional if using Basic Auth)
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.
additional_transaction_data	Additional data provided by you during payment creation

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 (*optional if using Basic Auth)
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 (*optional if using Basic Auth)
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 (*optional if using Basic Auth)
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 (*optional if using Basic Auth)
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:

• They have been in pending state for more than 2 weeks.
• Debt Collector has been set up with the merchant.

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 (*optional if using Basic Auth)
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

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,
        "currency": "EUR",
        "print_date": "12.10.2018",
        "first_name": "Peter",
        "last_name": "Mustermann",
        "address": "Egal Str. 1",
        "address2": "Complementary str",
        "tax_id": null,
        "postal_code": "10434",
        "city": "Berlin",
        "email": "test@testov.com",
        "state": "Berlin",
        "country":"Deutschland",
        "phone": "+49333222111",
        "description": "Sport sneakers",
        "redirect_after_payments": false,
        "success_url": null,
        "error_url": null
    },
    {
        "debt_claim_number": "124",
        "amount": 1.94,
        "currency": "EUR",
        "print_date": "2.3.2018",
        "first_name": "Petra",
        "last_name": "Mustermann",
        "address": "Egal Str. 1",
        "address2": "Complementary str",
        "tax_id": null,
        "postal_code": "10434",
        "city": "Berlin",
        "state": "Berlin",
        "email": "test@testov.com",
        "country": "Deutschland",
        "phone": "+49333222111",
        "description": "Sport sneakers",
        "redirect_after_payments": false,
        "success_url": null,
        "error_url": null
    }
  ]
}

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.
currency	NO	Falls back to channel's default currency if not given. 3 letter currency code. ISO-4217. E.g EUR, USD, CHF...
first_name	NO	First name of the payee
last_name	NO	Last name of the payee
address	NO	Address of the payee
address2	NO	Complementary address of the payee
tax_id	NO	Tax ID 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.
phone	NO	Phone number of the payee
redirect_after_payments	NO	True or false. Indicating if customers should be redirected to success or error URls after payments
success_url	NO	Success URL that customers should be redirected to after payments
error_url	NO	Error URL that customers should be redirected to after failed payments

Jetztzahlen Invoice API

Example GET 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": "",
    "state": "",
    "currency": "EUR",
    "import_id": 13,
    "amount_cents": 1200,
    "description": "",
    "address": "",
    "address2": "",
    "country": "",
    "phone": "",
    "redirect_after_payments": false,
    "success_url": null,
    "error_url": null,
    "active": true
  },
  "paylink": "http://yourchannel.jetztzahlen.de/pay/fhd-12102020"
}

Jetztzahlen Invoice API is used to retrieve or delete 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.
currency	3 letter currency code.
first_name	First name of the payee
last_name	Last name of the payee
address	Address of the payee
address2	Complementary address of the payee
postal_code	Postal code of the payee
city	City of the payee
state	State 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
redirect_after_payments	true or false. If true, customers will be redirected to success and error URls
success_url	Success URL customers should be redirected to
error_url	Error URL customers should be redirected to

Example PUT / PATCH rest/invoices/fhd-12102020 response

{
    "channel_id": 1,
    "id": 3,
    "first_name": "Max",
    "last_name": "Mustermann",
    "amount_cents": 1599,
    "status": "paid",
    "created_at": "2023-04-06T14:47:19.694+02:00",
    "updated_at": "2023-05-10T13:42:08.759+02:00",
    "merchant_prefix": null,
    "debt_claim_number": "888",
    "print_date": "2019-07-02",
    "address": "Rosenthalerstr. 100",
    "postal_code": "12345",
    "city": "Berlin",
    "import_id": 3,
    "description": "Here insert a description",
    "country": "Deutschland",
    "active": true,
    "email": "example@mail.de",
    "currency": "EUR",
    "state": "Berlin",
    "address2": ""
}

Request parameters

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

Response Parameters

The response includes the following attribute

Parameters	Comments
invoice	Hash containing invoice information

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.
currency	3 letter currency code.
first_name	First name of the payee
last_name	Last name of the payee
email	Email of the payee
address	Address of the payee
address2	Complementary address of the payee
phone	Phone number of the payee
postal_code	Postal code of the payee
state	State of the payee
city	City of the payee
state	State 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
description	Description of the invoice
redirect_after_payments	true or false. If true, customers will be redirected to success and error URls
success_url	Success URL customers should be redirected to
error_url	Error URL customers should be redirected to

This request does not return any response but only response code 204, no content.

Request parameters

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

Response Parameters

The response is empty.

Payment Methods

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

Available Payment APIs

Below you can find the list of available actions per each payment method.

Payment Method	Payment	Refund	Payout	Recurring Payments	Authorize, Capture, Reverse	Precheck	Other
Credit Card	X	X		X	X		Register
Sepa Direct Debit	X	X	X	X			Create Mandate Reference
Sepa Direct Debit B2B	X	X	X	X			Create Mandate Reference
Purchase on Account	X	X			X	X
Purchase on Account (B2B)	X	X			X	X
Installments		X			X	X
giropay	X	X
Sofort Überweisung	X
PayPal	X	X	X	X	X		Cancel, Revise
Barzahlen	X	X
Paydirekt	X	X
Request To Pay	X	X
Advance Payment	X
iDeal	X	X
Bancontact	X	X
MyBank	X	X
BLIK	X	X
eps	X	X
PayU	X	X
Apple Pay	X	X
Boleto	X	X			Reverse
Boleto B2B	X				Reverse
PIX	X	X
AiiA	X
SmartPay	X

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="
  }
}

• First you make a Payment request.

• Response with client_action is returned as shown in the example on the right hand side.

• You redirect the client to the payment page url given in action_data.

• We redirect back to the merchant's given success, and error URLs.

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:

• first_name
• last_name
• address
• city
• postal_code
• country
• email

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.

Apple Pay

Apple Pay provides an easy and secure way to make payments in your iOS, iPadOS, and watchOS apps, and on websites in Safari.

Integrating Apple Pay with our Payment API, is possible by passing in the apple_pay_token to us when creating the transaction.

We do not provide payment pages for this payment method, thus, frontend integration should be handled by merchants.

You can check Apple Developer Portal to get information on how to generate Apple Pay tokens, or contact us for more information.

Implementation Flow

Below is the steps to create a successful transaction with Apple Pay.

1. Have the button in place in your frontend platform such as web browser, or application screen.
2. Prompt the Apple Pay page for the user and let them to authenticate the transaction.
3. Receive the encrypted Apple Pay token and pass it in as apple_pay_token parameter in your requests to Payment API
4. Receive a success or an error response from our API.

Example request body for applepay transaction

{
    "api_key": "70abd594084787a392e8",
    "payment_type": "applepay",
    "order_id": "122",
    "amount": "15.9",
    // Use JSON.stringify(payment.token["paymentData"])
    // when passing this value to our payment gateway.
    "apple_pay_token": "your stringified payment token", 
    "currency": "EUR",    
    "address": "WonderStr 8",
    "city": "Berlin",
    "postal_code": "666",
    "country": "DE",
    "first_name": "Chuck",
    "last_name": "Norris",
    "email": "email@email.com",
    "postback_url": "https://postback.url.com",
    "success_url": "https://success.url.com",
    "error_url": "https://error.url.com",
}

Example response for applepay transaction request

{
  "transaction_id": "d1bf9fdf-7268-406f-9e08-8d5a9540ab97",
  "order_id": "122",
  "error_code": 0,
  "status_code": 3,
  "status": "completed",
}

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

Installments payment method is currently available for residents of Germany through Santander Bank. Due amount is credited to merchant's account upon successful authorization and completion of the payment.

Subsequent payments for each monthly installment are triggered automatically by the bank.

Constraints

1. This payment method should only displayed for German customers and if the amount is over 99 EUR, unless your account with Santander is contracted with support for lower level amounts.
2. Authorized orders should be captured within 90 days of their authorization, otherwise, they will be void.
3. Only full captures are permitted.
4. Multiple and partial refunds are permitted.

Transaction Flow

1. When a transaction is created, it will be in started state, waiting for customer action after redirection to Santander's redirect URL.

2. Once customer completes the application, it will either be declined and customer will be returned to the shop's error URL or it will be pre-approved and state will be pending which the customer will then be redirected to the shop's success URL.

3. Customer may also cancel the application and redirected to the shop's error URL.

4. Once transaction is at pending state, shop should wait for postback notifications from payment gateway. Further notifications will move the transaction state from pending to either authorized or declined or canceled depending on the outcome of the loan application.

5. Once the transaction is at authorized state, merchant is able to either send a request to POST /rest/capture to capture the amount and ship the order, OR send a POST rest/reverse request to cancel/reverse the transaction. Once the transaction is captured, it will reach the completed state. Reversed transactions will reach the reversed state.

6. Captured transactions in completed state, can be refunded by sending a request to POST rest/refund endpoint.

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.

Please note that SOFORT refunds can only be halfway automated. They can be started over the API but must be finalized in SOFORT's dashboard by downloading a transaction file and uploading it to the merchant's bank.

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 Subscriptions

In order to implement recurring payments with PayPal, you will have to implement flows for PayPal Subscriptions.

This, differ from traditional recurring payments.

PayPal takes control over triggering payments unlike traditional recurring payments - where merchant is responsible for triggering each payment after initial billing agreement.

PayPal Subscriptions Pre-requisites

You will have to familiarize yourself with concepts surrounding PayPal Subscriptions.

Follow this documentation guide to learn more about Catalogue Products API, Plan API, and Subscriptions API.

Creation of Catalogue Products and Plans

When you initially create a PayPal Subscription over our API, you should already have an existing PayPal Plan created. You should then pass us the paypal_plan_id when creating a recurrent payment over our Payments API.

How PayPal Subscriptions works?

In simple terms, you will have to follow steps below to create a PayPal subscription.

1. Create a Catalogue Product using PayPal API, outside of our systems. Follow official documentation of PayPal REST API
2. Create a Plan using PayPal API, outside of our systems. Follow official documentation of PayPal REST API.
3. Pass in paypal_plan_id and rest of the required parameters to our Payments API endpoint to create a subscription.
4. Redirect the client to the redirect_url and let them approve the subscription.
5. Once subscription is created, our systems will track new transactions, create them and send a postback notification to the original transaction's postback_url.

Postbacks that are sent to original transaction's postback URL will contain additional parameter. See here for mor info.

What APIs are available for PayPal Subscriptions?

To work with PayPal subscriptions, you will only have to work with Payments API. In case you would like to cancel or revise(a.k.a update) your subscription information, you can use Cancellation API and Revisal API

PayPal Subscriptions Required Parameters

Same parameters are required as in a normal /rest/payment request with few additions and differences mentioned below.

Parameters	Required	Comments
amount	YES	Amount has to be 0. As, this amount has no effect on future transactions, but the plan's selection does.
paypal_plan_id	YES	ID of the PayPal Plan
paypal_subscription_start_time	NO	Start time for the subscription. When left blank, it will start immediately. It has to be in this format. E.g 2021-09-29T11:47:25Z
paypal_subscription_quantity	NO	Quantity of an item within the plan. Only possible if Plan supports quantities.

Shipping Address Parameters are required when the Plan is a physical product and requires shipping.

If you are using our test account, you can use following test plan IDs to test your integration.

PayPal Subscriptions Example Request

Example POST rest/payment payload for subscriptions

{
  "payment_type": "paypal",
  "recurring": "1",
  "api_key": "your-api-key",
  "amount": "0",
  "postback_url": "https://your-postback-url",
  "success_url": "https://your-success-url",
  "error_url": "https://your-error-url",
  "order_id": "123000",
  "currency": "EUR",
  "address": "Hellersbergstr. 14",
  "shipping_address": "2211 N First Street",
  "city": "Neuss",
  "shipping_city": "San Jose",
  "postal_code": "41460",
  "shipping_postal_code": "95131",
  "state": "NW",
  "shipping_state": "CA",
  "country": "DE",
  "shipping_country": "US",
  "first_name": "Max",
  "shipping_first_name": "Max",
  "last_name": "Mustermann",
  "shipping_last_name": "Mustermann",
  "email": "max.m@test.com",
  "paypal_plan_id": "P-6UK2193323222643NMFJN66Q",
  "shipping_costs": "10",
  "paypal_subscription_quantity": 1,
  "paypal_subscription_start_time": "2021-09-30T20:47:25Z"
}

PayPal Subscriptions Example Response

Example POST rest/payment response for subscriptions

{
    "transaction_id": "dbd3ab13-38f3-49da-9e12-47ef445b0b72",
    "order_id": "123000",
    "error_code": 0,
    "status_code": 2,
    "status": "pending",
    "client_action": "redirect",
    "action_data": {
        "url": "href": "https://www.sandbox.paypal.com/webapps/billing/subscriptions?ba_token=BA-0M029980WL960863C"
    }
}

You will have to redirect the client o given URL. Once they approve the subscription, they will be redirected back to your given success_url, and our systems will start tracking transactions on this subscription.

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 make a POST request to /rest/payment as mentioned in Payments API.
• You receive a checkout_token and pass it to Barzahlen Javascript plugin which loads the Barzahlen payment slip
• Customer prints/saves/gets notified with the slip and proceeds to pay it in any of the Barzahlen supported physical shops or payment points.

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.

Request to Pay

Request to Pay is a redirecting payment method offered by Deutsche Bank.

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.

Bancontact

Similar to iDEAL, but used in Belgium.

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

MyBank

Similar to iDEAL, but used in Italy.

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

BLIK

Similar to iDEAL, but used in Poland (only PLN is accepted as currency).

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

eps

Similar to iDEAL, but used in Austria.

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

PayU

Similar to iDEAL, but used in Czech Republic (CZK currency only) and Poland (PLN currency only).

Boleto

Boleto is a popular payment method from Brazil. Current implementation is through Banco Bs2. Merchants may choose to setup and use one of their own Banco BS2 bank accounts for processing of transactions, or may opt in to receive payments to their bank accounts through provided BS2 account.

If the choice is the latter one, payouts will be scheduled to your specified bank account on pre-agreed conditions.

Please, contact us for more information.

Boleto Transaction Example Request

When sending a request to Payment API, payment_type should be either boleto or boleto_b2b, depending if the end customer is a physical person or a business.

Example POST rest/payment response for Boleto

{
    "api_key": "yourapikey",
    "payment_type": "boleto", // boleto OR boleto_b2b
    "invoice_date": "2022-03-15", // Expiry date for the Boleto
    "company_vat_id": "345827344", // VAT ID of the customer or the company
    "order_id": "BOLETO001", // Reference for the transaction. Max 10 chars
    "amount": 10,
    "currency": "BRL",
    "first_name": "Maria",
    "last_name": "Josefina Da Silva",
    "email": "test@test.com",
    "address": "Nossa Senhora do Rosário",
    "address2": "Setor de Mansoes do Lago Norte",
    "city": "Brasilia",
    "postal_code": "71540072",
    "state": "DF",
    "country": "BR",
    "postback_url": "https://your.postback.url"
}

Example response for Boleto

{
    "transaction_id": "a5db3dc0-ca62-48d2-8fbf-c22b8757547f",
    "order_id": "LIVE004",
    "error_code": 0,
    "status_code": 2,
    "status": "pending",
    "barcode": "21899892400000005000010005173639804144214418",
    "slip_id": "21890010070517363980741442144188989240000000500"
}

You may choose to display the SLIP_ID to your end customer for the payment, or use an available Javascript library such as Boleto JS to display them in a nicely formatted SVGs.

Once the Boleto is paid by the end customer, transaction will receive a status update within 1-2 business days, and a webhook notification will be sent to your given postback_url.

PIX

Pix is a popular payment method in Brazil. Its instant and secure nature led to its wide adoption.

Example POST rest/payment response for Pix

{
    "api_key": "yourapikey",
    "payment_type": "pix",
    "order_id": "PIX001",
    "amount": 10,
    "currency": "BRL",
    "first_name": "Maria",
    "last_name": "Josefina Da Silva",
    "email": "test@test.com",
    "address": "Nossa Senhora do Rosário",
    "address2": "Setor de Mansoes do Lago Norte",
    "city": "Brasilia",
    "postal_code": "71540072",
    "state": "DF",
    "country": "BR",
    "postback_url": "https://your.postback.url"
}

Billing address information is optional, except the country.

Example response for Pix

{
  "transaction_id": "106e4436-408b-466c-8495-9d83dee1d37e",
  "order_id": "123000",
  "error_code": 0,
  "status_code": 2,
  "status": "pending",
  "pix_qrcode": "00020126910014BR.GOV.BCB.PIX2569api-pix-h.bancobs2.com.br/spi/v2/23b703ad-09f2-4de0-b14f-ae776d4d8015520400005303986540515.905802BR5925Visconde Pagamentos E Sol6014Belo Horizonte61083038040362070503***63041E49"
}

You will need to display the "pix_qrcode" value to your customers. This text value should then be used by your customers to make the payment in their banking/payment applications.

Once the payment is made, we will send a postback notification to your specified postback_url, letting you know that payment has been cleared.

AiiA

AiiA (Mastercard) is an open banking platform that processes millions of payments and billions of transactions for banks, fintechs, payment service providers and more to enable greater consumer access, control and choice across Europe. It is also similar to Sofort, whereas the user is redirected to a payment site hosted by AiiA and returns back to the merchant's site after completing the transaction.

Example POST rest/payment for AiiA

{
    "api_key": "yourapikey",
    "payment_type": "aiia",
    "amount": 10,
    "currency": "EUR",
    "postback_url": "https://your.postback.url",
    "success_url": "https://your-success-url",
    "error_url": "https://your-error-url",
}

Example response for AiiA

{
  "transaction_id": "cabff187-f216-4f4d-90a0-58ef73fa52a9",
  "order_id": "123000",
  "error_code": 0,
  "status_code": 1,
  "status": "started",
  "client_action": "redirect",
  "action_data": {
    "url": "https://some-target-url"
  }
}

SmartPay

SmartPay is the easiest way to accept crypto payments.

Example POST rest/payment for SmartPay

{
  "payment_type": "smartpay",
  "api_key": "your-api-key",
  "amount": "20",
  "currency": "EUR",
  "email": "max.m@test.com"
}

Example response for SmartPay

{
  "transaction_id": "925c1a68-24b8-47a5-8d21-f8b8fd10d725",
  "order_id": "123000",
  "error_code": 0,
  "status_code": 1,
  "status": "started",
  "client_action": "redirect",
  "action_data": {
    "url": "https://some-target-url"
    }
}

When using this Payment Method, you have to provide an amount equal to or greater than 20 FIAT.

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:

NB! Only HTTPS addresses with TLS 1.2/1.3 will be accepted as postback urls.

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.

PayPal Subscriptions Postback Parameters

When a new payment happens on a transaction that was created for PayPal Subscriptions, these additional parameters will be part of the postback.

You will be able to create transactions in your own systems by having:

Parameters	Comments
original_transaction_id	ID of the transaction that was made initially to create the subscription
amount	Amount of the newly created payment on a subscription
currency	Currency of the newly created payment on a subscription
message	Additional info about the transactions status
paypal_subscription_id	PayPal Subscription ID
paypal_plan_id	PayPal Plan ID

Additional Postback Parameters

Parameters	Comments
additional_transaction_data	Additional transaction data that you have provided during payment creation

Appendix

Parameters Details

Payment Types

• cc (for credit card)
• dd (for direct debit)
• dd_b2b (for B2B direct debit)
• kar (for invoice service)
• kar_b2b (for B2B invoices)
• rate (for installments)
• giro (for giropay)
• sofort (for SOFORT Überweisung)
• paypal (for PayPal)
• bar (for Barzahlen)
• paydirekt (for Paydirekt)
• rtp (for Request To Pay)
• advance (for Advance Payment/Vorkasse)
• ideal (for Ideal)
• bancontact (for Bancontact)
• mybank (for MyBank)
• blik (for BLIK)
• eps (for eps)
• payu (for PayU)
• applepay (for Apple Pay)
• boleto (for Boleto)
• boleto_b2b (for Boleto B2B)
• pix (For PIX)
• smartpay (For Smartpay)
• aiia (For AiiA)

Locales

The following languages options are available:

• en (for English)
• de (for German)
• fr (for French)
• it (for Italian)
• sv (for Swedish)
• ru (for Russian)
• fi (for Finnish)
• pt (for Portuguese)
• es (for Spanish)
• pl (for Polish)
• nl (for Dutch)

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

• Precheck API request.
• Mandate Reference API request.
• Installments API
• Recurring payments after making initial payment using Payment API.

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, except in PayPal Subscriptions

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:

• postform: build a POST form from the data included in the action_data array and immediately submit it to the url included in action_data hash.

• redirect: redirect to the url specified in action_data hash.

Action Data

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

• url: Target url of the action
• fields: In case of a POST form, this array specifies the key/value pairs of the data to be posted.

Sepa Payment Legal Implications

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

• Card Number Non-3D Secure: 4200000000000000
• Card Number 3D Secure: 4711100000000000

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

Mastercard

• Card Number Non-3D Secure: 5454545454545454
• Card Number 3D Secure: 5212345678901234

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

Giropay Payments

• Bank: giropay Testbank
• IBAN: DE48499999601234567890
• VR-NetKey / Alias: (any value)
• PIN: 1234
• TAN‑Verfahren auswählen (only for amounts >= 20,00, see below): “Smart-TAN plus optisch / USB” or “Smart-TAN photo”
• TAN: 123456

SOFORT Payments

• Bank Code: 88888888

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

• Username: paula.penny@example.com
• Password: paypaltest1

PayPal Payments REST

• Username: test-buyer@betterpayment.de
• Password: bptest$1

PayPal Subscriptions Plan IDs

We strongly suggest you to use your own test accounts when integrating PayPal subscriptions, to have greater flexibility in creating your own plans. However, if you are still using our test accounts, here is different paypal_plan_ids for you to utilize in PayPal subscriptions.

• Plan 1: supports quantity and shipping, P-6UK2193323222643NMFJN66Q

• Plan 2: fixed price, no shipping, no quantity, P-3T530789UT9902333MFXIR3Q

• Plan 3: tiered plan, supports quantity, no shipping, P-2KX28069JK751103FMFXI4QI

• Plan 4: volume plan, supports quantity, no shipping, P-5GP07204RX5314834MFXI6YQ

SEPA Direct Debit Payments

• IBAN: DE89370400440532013000
• BIC: COBADEFFXXX

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)

• Vorname: Uno
• Nachname: Eins
• Geburtsdatum: 07.07.1960
• Addresse: Hellersbergstr.14
• PLZ, Ort: 41460,Neuss

Request To Pay Payments

Look up the bank on the first payment page by typing in "Demo". Use any numbers for account and pin codes.

Installment

When testing transactions, in order to imitate a successful, declined and pending statuses without going through lengthy verification flow of Santander, you can use the following test data as First Name and Last Name:

1. Declined Transaction

• First Name: Stub
• Last Name: Declined

1. Pending Transaction

• First Name: Stub
• Last Name: In_process

1. Authorized Transaction

• First Name: Stub
• Last Name: Accepted

1. Completed Transaction

• First Name: Stub
• Last Name: Paid

Transaction Events

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

• registration: registration has been performed on transaction
• authorization: authorization has been performed on transaction
• capture: capture has been performed on transaction
• reversal: reversal has been performed on transaction
• payment: payment has been performed on transaction
• sepa_mandate: create mandate reference has been performed on transaction
• refund: transaction has been fully or partially refunded
• postback: postback has been sent to postback_url of the transaction
• chargeback: transaction has been charged-back fully or partially
• riskcheck: risk check has been performed on transaction
• debt_collection: debt collection has been performed on transaction
• manual_change: transaction data or state has been modified manually
• user_cancellation: user has cancelled transaction
• initialization: transaction has been initialized with no payment completed yet
• return_from_acquirer: transaction has been peformed and returned from 3rd party
• precheck: precheck has been performed on transaction
• rate_calculation: installments has been calculated on the transaction
• refund_announcement: refund announcement has been made for the transaction
• reauthorization: reauthorization has been performed on transaction
• fee_calculation: fees has been calculated for the transaction
• status_check: status check has been performed with 3rd party for synchronization purposes
• refund_status_check: status check has been performed for refund with 3rd party for synchronization purposes
• payout: payout has been performed
• remote_change: transaction data has been altered remotely over API
• factoring: unpaid transaction was sent to factoring
• global_precheck: pre-check without payment method
• blacklist: an address has been added in the blacklist
• sepa_import: transaction status updated through reading EBICS bank statements
• data_forwarding: data forwarding has been performed on the transaction
• manual_cancellation: transaction has been cancelled manually by the merchant
• authentication: one of the first steps in some 3DS2 payments
• challenge_3d: a front-end step in 3DS2 payments
• removal_of_personal_data: personal information has been removed from transaction data

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.