Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

 Additional specification

UI Text Box
typeinfo

Currently there are some technical limitations regarding the “fulfillment_delay” and “refund_announcement”. If you plan on using them you have to implement the the “preauthorization” instead of “authorization”also always use API version 3.10 when using Unzer Pay Later™.

Referencing preliminary requests by “workorderid”

UI Text Box
typeinfo

Unzer offers a couple of preliminary requests (“calculation” and “pre_check”) that need to be referenced during the preauthorization/auothorization of a transaction.

The “pre_check” request can be used to perform a preliminary risk check. This request is optional.

The “calculation” request is required for installment transactions.

If you decide to use the pre_check in your implementation, make sure that you pass the workorderid returned by the “pre_check” on to following requests.

Example:

  • If you try to perform an installment payment with a preceding “pre_check” you need to reference the “pre_check”’s workorderid in both the “calculation” and “preauthorization”/”authorization” requests. In this particular case, you don’t need to reference the workorderid of the “calculation” request.

  • If you try to perform an installment payment without a preceding “pre_check” you need to reference the workorderid of the preceding “calculation” request.

  • If you try to perform an invoice payment with a preceding “pre_check” you need to reference the workorderid of the “pre_check”

Fraud Prevention

Unzer offers the possibility to send a session_id, referencing a complete customer session. This is to make sure, that all requests sent by the merchant, belong to the same customer session. This helps Unzer to make sure, that there are no fraudulent requests sent by a third party.

For each checkout process, a session ID has to be created and transmitted to Unzer in two ways:

1. When loading the fraud prevention JS, and 2. during API requests.


Section


Column

The add_paydata[analysis_session_id] is a temporary identifier that is unique to the visitor’s session and per event/order. It can be up to 128 bytes long and must only consist of the following characters:

  • upper and lowercase English letters([az], [A-Z])
  • digits (0-9)
  • underscore (_)
  • hyphen(-)


Column


Code Block
languagexml
titleExample
SessionId= merchantshop_cd-695a7565-979b-4af9




UI Text Box
typetip

Recommendations for creation of add_paydata[analysis_session_id]:

  • Use a merchant identifier (URL without domain additions), append an existing session identifier from a cookie, append the date and time in milliseconds to the end of the identifier and then applying a hexadecimal hash to the concatenated value to produce a completely unique Session ID.
  • Use a merchant identifier (URL without domain additions), append an existing session identifier from the web application and applying a hexadecimal hash to the value to obfuscate the identifier.

UI Steps


UI Step

Define a session ID. Unzer recommends to concatenate the merchant name, an existing session identifier and a timestamp in milliseconds, then apply a hexadecimal hash function. The session ID must be retained through the checkout process.


UI Step

Load the fraud prevention JavaScript, be sure to replace the [SessionID] placeholder. 363t8kgq is a static value:

Code Block
languagexml
<head>
     <script type="text/javascript" src="https://h.online-metrix.net/fp/tags.js?org_id=363t8kgq&session_id=[SessionID]"></script>
</head>
  
<body>
     <noscript>
          <iframe style="width: 100px; height: 100px; border: 0; position: absolute; top: -5000px;" src="https://h.online-metrix.net/fp/tags?org_id=363t8kgq&session_id=[SessionID]"></iframe>
     </noscript>
</body>


UI Text Box
typewarning

You are free to use any asynchronous loading mechanism. We strongly recommend to load the JS only when the customer hits the acceptance checkbox of the privacy statement to avoid GDPR issues.



UI Step

The session ID must be added to all pre_check and authorization/preauthorization requests in the paramter add_paydata[analysis_session_id]



B2B Transactions

UI Text Box
typeinfo

Unzer supports B2B transactions for (monthly) Invoice and Debit transactions. If you want your transaction to be flagged as B2B, you need to set the parameter “add_paydata[b2b]” to “yes” for all requests regarding this transaction.


UI Text Box
typenote

B2B transactions are only available for Unzer Rechnungskauf.

Unzer HTTP Authentication

UI Text Box
typeinfo

As part of the calculation request response a document URL is returned as well (StandardCreditInformationUrl). In order to access the referenced document HTTP authentication is required. The user credentials are the channelname and password provided by Unzer.

Preauthorization/Authorization

Request

Parameter

Required

Comment

api_version+

Has to be at least "3.10"

clearingtype

+

Has to be "fnc": Financing

financingtype

+

PYV: Unzer Rechnungskauf

PYM: Unzer - Monthly

PYS: Unzer Ratenkauf

PYD: Unzer Lastschrift

amount

+

Total amount (in smallest currency unit! e.g. cent)

currency

+

Currency (ISO 4217)

Excerpt Include
currency - definition
currency - definition
nopaneltrue

workorderid

o

Required for Preauth/Auth of Unzer Ratenkauf / references the preceding calculation request

Excerpt Include
workorderid - definition
workorderid - definition
nopaneltrue

narrative_text

-

Excerpt Include
narrative_text - definition
narrative_text - definition
nopaneltrue

reference

+

Merchant reference number for the payment process

Excerpt Include
reference - definition
reference - definition
nopaneltrue

email

+

Customers e-mail address

Excerpt Include
email - definition
email - definition
nopaneltrue

it[n]

-


it[n]

Comments

goods

Goods

shipment

Shipping Charges

Note: handling and voucher are not supported and will be mapped to goods

id[n]

-

International Article Number (EAN bzw. GTIN)

Excerpt Include
id[n] - definition
id[n] - definition
nopaneltrue

pr[n]

-

Excerpt Include
pr[n] - definition
pr[n] - definition
nopaneltrue

no[n]

-

Excerpt Include
no[n] - definition
no[n] - definition
nopaneltrue

de[n]

-

Excerpt Include
de[n] - definition
de[n] - definition
nopaneltrue

add_paydata[installment_duration]

o

Required for Unzer Ratenkauf, value has to be the result of a preceding generic calculation request

company

o

Company name, required for B2B transactions (if add_paydata[b2b] = “yes”)

birthday+

Excerpt Include
birthday - definition
birthday - definition
nopaneltrue

firstname

+

Excerpt Include
firstname - definition
firstname - definition
nopaneltrue

lastname

+

Excerpt Include
lastname - definition
lastname - definition
nopaneltrue

street

+

Street number and name

zip

+

Excerpt Include
zip - definition
zip - definition
nopaneltrue

city

+

City

country

+

Excerpt Include
country - definition
country - definition
nopaneltrue

ip

+

Customer's IP-V4-address (123.123.123.123) or IP-V6-address

bankcountry

o

Excerpt Include
bankcountry - definition
bankcountry - definition
nopaneltrue

bankaccount

o

Excerpt Include
bankaccount - definition
bankaccount - definition
nopaneltrue

bankcode

o

Excerpt Include
bankcode - definition
bankcode - definition
nopaneltrue

iban - definition

o

Excerpt Include
iban - definition
iban - definition
nopaneltrue

bic

o

Excerpt Include
bic - definition
bic - definition
nopaneltrue

add_paydata[company_trade_registry_number]

-

Trade registry number for B2B transactions

add_paydata[b2b]

-

Optional, defaults to “no”

Set “yes” for B2B transactions

B2B transactions only available for PYV transactions.

For additional information refer to chapter 1.4

add_paydata[company_uid]

-

VAT identification number, recommended for better acceptance rates with b2b transactions

add_paydata[company_register_key]

-

ID of other company register than trade registry or UID

add_paydata[mobile]

-

Optional mobile phone number

add_paydata[analysis_transportation_<suffix>]

-

<suffix> is one of:

company - DHL, UPS

tracking - delivery tracking package id

return_tracking - for tracking id of returns

You can use these parameters on authorization and capture requests

add_paydata[analysis_customer_<suffix>]

-

<suffix> is one of:

group - customer group

confirmed_orders - recently confirmed orders

confirmed_amount - recently confirmed amount

internal_score - internal risk score of the merchant

add_paydata[analysis_item_category_<n>]

-

Item category

Replace <n> with the shopping item id you want to categorize

add_paydata[analysis_webshop_url]

-

Webshop URL

add_paydata[payolution_session_id]-see Chapter "Fraud Prevention" for more details

 Response

Parameter

Required

Comment

workorderid

-

Used to reference a preceding calculation or pre-check request

status

+

APPROVED / REDIRECT / ERROR / PENDING

txid

+

Transaction ID

add_paydata[clearing_reference]

+

accounting number, used to print on the invoice

Parameter (ERROR)

errorcode

+

Error number

errormessage

-

Error message

customermessage

-

Error message for the end customer

(Language selection is based on the end customer’s language, „language“)

Capture

UI Text Box
typeinfo

The capture request is used to finalize a preauthorized transaction.


UI Text Box
typenote

If you use preauth/Capture with installment transactions, the capture request has to be sent right after the preauthorization

Request


Parameter

Required

Comment

txid

+

Payment process ID (PAYONE)

clearingtype

+

Has to be "fnc": Financing

financingtype

+

PYV: Unzer Rechnungskauf

PYM: Unzer Monthly

PYS: Unzer Ratenkauf

PYD: Unzer Lastschrift

add_paydata[b2b]

-

Optional, defaults to “no”

Set “yes” for B2B transactions

B2B transactions only available for PYV transactions.

For additional information refer to chapter 1.4

capturemode

+

Excerpt Include
capturemode - definition
capturemode - definition
nopaneltrue

amount

+

Amount to be entered (in smallest currency unit! e.g. cent)

The amount must be less than or equal to the amount of the corresponding booking.

sequencenumber

o

Excerpt Include
sequencenumber - definition
sequencenumber - definition
nopaneltrue

currency

+

Excerpt Include
currency - definition
currency - definition
nopaneltrue

narrative_text

-

Human readable description of the reason for the transaction

add_paydata[analysis_customer_<suffix>]

-

<suffix> is one of:

group - customer group

confirmed_orders - recently confirmed orders

confirmed_amount - recently confirmed amount

internal_score - internal risk score of the merchant

add_paydata[analysis_invoice_id]

-

Additional field for an invoice ID that the merchant can use for his own purposes

add_paydata[analysis_order_id]

-

Additional field for an order ID that the merchant can use for his own purposes

 Response


Parameter

Required

Comment

status

+

APPROVED / ERROR

txid

+

Payment process ID (PAYONE)

add_paydata[clearing_reference]

+

accounting number, used to print on the invoice (only for API version >3.10)

Debit/Refund

UI Text Box
typeinfo

Only Unzer Pay Later™specific parameters are described here. Refer to the Payone API description

Request


Parameter

Required

Comment

add_paydata[analysis_invoice_id]

-

Additional field for an invoice ID that the merchant can use for his own purposes

add_paydata[analysis_order_id]

-

Additional field for an order ID that the merchant can use for his own purposes

add_paydata[b2b]

o

Optional, defaults to “no”

Set “yes” for B2B transactions

B2B transactions only available for PYV transactions.

For additional information refer to chapter 1.4


genericpayment – add_paydata[action] = calculation

UI Text Box
typeinfo

The calculation request is used, whenever you need to retrieve financing plans for the payment type “Unzer Pay Later™-Installment”. It accepts the amount of the transaction as an input parameter and returns all possible payment plans.

The calculation request has to be referenced in an installment preauthorization/authorization. add_paydata[installment_duration] is used to specify the desired duration for the payment plan in months.

Request

Parameter

Required

Comment

add_paydata[action]

+

For “calculation” Requests this has to be:

-          calculation

clearingtype

+

Has to be "fnc": Financing

financingtype

+

PYV: Unzer Rechnungskauf

PYM: Unzer Monthly

PYS: Unzer Ratenkauf

PYD: Unzer Lastschrift

amount

o

Required for action=pre_check and action=calculation

currency

+

Excerpt Include
currency - definition
currency - definition
nopaneltrue

add_paydata[analysis_merchant_comment]

-

Comment field for the merchant

add_paydata[company_uid]

-

Only for action=pre_check

VAT identification number, recommended for better acceptance rates with b2b transactions

 Response


Parameter

Required

Comment

status

+

OK / ERROR

workorderid

+

The workorderid has to be referenced during preauth/auth

add_paydata[PaymentDetails _<n>_Currency ]

-

Currency

 

add_paydata[PaymentDetails_<n>_StandardCreditInformationUrl ]

-

A URL to the EU Standard Credit Information hosted by Unzer

add_paydata[PaymentDetails_<n>_Usage ]

-

A human readable description of the reason for the payment

Replace n with natural number

add_paydata[PaymentDetails_<n>_Duration]

-

Defines how many installments are used to perform the payment

Replace n with natural number

add_paydata[PaymentDetails_<n>_EffectiveInterestRate]

-

The effective interest rate p.a. in percent

add_paydata[PaymentDetails_<n>_InterestRate]

-

The interest rate p.a. in percent

add_paydata[PaymentDetails_<n>_MinimumInstallmentFee ]

-

The minimum fee for the installment payment, which will be charged even if the interest would be lower than that (e.g. because of partial refunds)

add_paydata[PaymentDetails_<n>_OriginalAmount]

-

The original transaction amount as transmitted by the merchant

add_paydata[PaymentDetails_<n>_TotalAmount]

-

The total transaction amount as transmitted by the merchant

add_paydata[PaymentDetails_<n>_Installment_<m>_amount]

-

Amount of installment number m

add_paydata[PaymentDetails_<n>_Installment_<m>_due]

-

Due date of installment number m

add_paydata[PaymentDetails_<n>_Installment_<m>_dueInDays]

-

Number of days until installment number m is due

genericpayment – add_paydata[action] = pre_check

UI Text Box
typeinfo

This can be used to perform a preliminary risk check.

Request

Parameter

Required

Comment

clearingtype

+

Has to be "fnc": Financing

financingtype

+

PYV: Unzer Rechnungskauf

PYM: Unzer Monthly

PYS: Unzer Ratenkauf

PYD: Unzer Lastschrift

ip

+

Customer's IP-V4-address (123.123.123.123) or IP-V6-address

email

+

Customers e-mail address

add_paydata[action]

+

For “pre-check” Requests this has to be:

-          pre_check

add_paydata[payment_type]

+


Section


Layout box
cssClasspayoneFormat
floatingleft

Format


Layout box
cssClasspayoneFormatValue
floatingleft
LIST 



Section


Layout box
cssClasspayoneFormat
floatingleft

Permitted values


Layout box
cssClasspayoneFormatValue
floatingleft
Payolution-Invoicing
Payolution-Installment
Payolution-Monthly
Payolution-Debit



add_paydata[b2b]

-

Optional, defaults to “no”

Set “yes” for B2B transactions

B2B transactions only available for PYV transactions.

For additional information refer to chapter 1.4

add_paydata[company_trade_registry_number]

-

Trade registry number for B2B transactions

add_paydata[company_register_key]

-

ID of other company register than trade registry or UID

add_paydata[mobile]

-

Only for action=pre_check

Optional mobile phone number

amount

+

Amount to be entered (in smallest currency unit! e.g. cent)

currency

+

Excerpt Include
currency - definition
currency - definition
nopaneltrue

company

o

Company name, required for B2B transactions (if add_paydata[b2b] = “yes”)

birthday

+

Date of birth (YYYYMMDD)

firstname

+

First name

lastname

+

Surname

street

+

Street number and name

zip

+

Postcode

city

+

City

country

+

Excerpt Include
country - definition
country - definition
nopaneltrue

add_paydata[payolution_session_id]-see Chapter "Fraud Prevention" for more details

Response 

Parameter

Required

Comment

status

+

OK / ERROR

workorderid

+

Excerpt Include
workorderid - definition
workorderid - definition
nopaneltrue

 

genericpayment – add_paydata[action] = refund_announcement

UI Text Box
typeinfo

If a customer announces a return to the customer support it is possible to send a “refund_announcement” request in order to stop the dunning process.

Request

Parameter

Required

Comment

add_paydata[action]

+

For “refund_announcement” Requests this has to be:

-          refund_announcement

clearingtype

+

Has to be "fnc": Financing

financingtype

+

PYV: Unzer Rechnungskauf

PYM: Unzer Monthly

PYS: Unzer Ratenkauf

PYD: Unzer Lastschrift

add_paydata[txid]

+

Not the regular TXID that is returned by all preauth/auth requests. This txid is returned as “add_paydata[txid]” for preauthorizations using API version 3.10

workorderid

+

The “workorderid” of the corresponding preauth/auth request. It is only returned for preauthorizations using API version 3.10

amount

+

Amount to be entered (in smallest currency unit! e.g. cent)

currency

+

Excerpt Include
currency - definition
currency - definition
nopaneltrue

Response

Parameter

Required

Comment

status

+

OK / ERROR

workorderid

+

Excerpt Include
workorderid - definition
workorderid - definition
nopaneltrue

genericpayment – add_paydata[action] = fulfillment_delay

UI Text Box
typeinfo

If the merchant can’t abide by his commited fulfillment date, it is possible to send a “fulfillment_delay” request in order to delay the dunning process until a specified date.

Request

Parameter

Required

Comment

add_paydata[action]

+

For “fulfillment_delay” requests this has to be:

-          fulfillment_delay

add_paydata[analysis_expected_fulfillment_date]

+

New expected fulfillment date.

Format: YYYY-MM-DD

add_paydata[txid]

+

Not the regular TXID that is returned by all preauth/auth requests. This txid is returned as “add_paydata[txid]” for preauthorizations using API version 3.10

workorderid

+

The “workorderid” of the corresponding preauth/auth request. It is only returned for preauthorizations using API version 3.10

amount

+

Amount to be entered (in smallest currency unit! e.g. cent)

currency

+

Excerpt Include
currency - definition
currency - definition
nopaneltrue

Response

Parameter

Required

Comment

status

+

OK / ERROR

workorderid

+

Excerpt Include
workorderid - definition
workorderid - definition
nopaneltrue

Sequence Diagrams

Installment Authorization and Refund

draw.io Diagram
bordertrue
viewerToolbartrue
fitWindowfalse
diagramDisplayName
lboxtrue
revision47
diagramNamePaysafe_Installment_Authorization_Refund
simpleViewerfalse
width
linksauto
tbstylehidden
diagramWidth1401

Installment Preauthorization and Refund

draw.io Diagram
bordertrue
viewerToolbartrue
fitWindowfalse
diagramDisplayName
lboxtrue
revision37
diagramNamePaysafe_installment_preauthorization_refund
simpleViewerfalse
width
linksauto
tbstylehidden
diagramWidth1401

Invoice Sale Authorization and Refund

draw.io Diagram
bordertrue
viewerToolbartrue
fitWindowfalse
diagramDisplayName
lboxtrue
revision25
diagramNamePaysafe_invoice_sale_authorization_refund
simpleViewerfalse
width
linksauto
tbstylehidden
diagramWidth1401

Invoice Preauthorization and Refund

 

Reversal

draw.io Diagram
bordertrue
viewerToolbartrue
fitWindowfalse
diagramDisplayName
lboxtrue
revision25
diagramNamePaysafe_invoice_preauthorization_refund
simpleViewerfalse
width
linksauto
tbstylehidden
diagramWidth1401
draw.io Diagram
bordertrue
viewerToolbartrue
fitWindowfalse
diagramDisplayName
lboxtrue
revision36
diagramNamepaysafe_reversal
simpleViewerfalse
width
linksauto
tbstylehidden
diagramWidth1401


Table of Contents
outlinetrue
indent2em