Introduction

Unzer's services include transaction processing and acting as an acquirer.

The Unzer Group includes numerous companies, including Heidelberger Payment and Universum Group, mPAY24, StarTec, Avanti, Alpha Cash, ec-Plus, POSeidon digital, Pay Later (acquired by Paysafe), Paydiscount. Kulam and Lavego. Unzer also acquired Berlin-based fintech Tillhub in April 2022.

Integrations

POST  Request - Pre-/ Authorization

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

path Parameters
api_version
required
Has to be at least "3.10"
clearingtype
required
Fixed Value fnc
financingtype
required
Fixed Values PYV, PYM, PYS, PYD

PYV: Unzer Rechnungskauf

PYM: Unzer - Monthly

PYS: Unzer Ratenkauf

PYD: Unzer Lastschrift

reference
required
Format CHAR(1..20)
Permitted Symbols [0-9][a-z][A-Z], .,-,_,/

Merchant reference number for the payment process (case insensitive)

amount
required
Format NUMERIC(1..10)
Permitted values max. +/- 19 999 999 99

Specifies the total gross amount of a payment transaction.

Value is given in smallest currency unit, e.g. Cent of Euro.

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

currency
required

Format List

Permitted values ISO 4217 (currencies) 3-letter-codes

Samples

EUR

USD

GBP

narrative_text
not required
Format CHAR(1..81)

Dynamic text element on account statements.

(3 lines with 27 characters each) and credit card statements.

workorderid
optional
Format CHAR(1..50)

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

 

The workorderid is a technical id returned from the PAYONE platform to identify a workorder. A workorder is a part of a payment process (identified by a txid). The workorderid is used for the genericpayment request.

PERSONAL DATA Parameters
firstname
required
Format CHAR(1..50)

First name of customer; optional if company is used, i.e.: you may use

"company" or "lastname" or "firstname" plus "lastname"

lastname
required
Format CHAR(2..50)

Last name of customer; optional if company is used, i.e.: you may use

"company" or "lastname" or "firstname" plus "lastname"

company
optional
Format CHAR(2..50)

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

street
required
Format CHAR(1..50)

Street number and name (required: at least one character)

zip
required
Format CHAR(2..50)
Permitted Symbols [0-9][A-Z][a-z][_.-/ ]

Postcode

city
required
Format CHAR(2..50)

City of customer

country
required
Format List
Permitted values ISO 3166 2-letter-codes
Samples
DE
GB
US

Specifies country of address for the customer.

Some countries require additional information in parameter "state"
email
required
Format CHAR(5..254
Permitted Symbols RFC 5322

Special Remark email validation:

Max. length for email is 254 characters. Validation is set up in the following way:

Username = Max. 63 characters

Domain Name = Max. 63 characters
Domain Suffixes = Max. 4 suffixes with max. 124 characters 
Example: username[63]@domain_name[63].suffix[60].suffix[60].suffix[4]

"@" and "." is counted as a character as well; in case of a total of three suffixes, this would allow a total of 254 characters.

email-address of customer

birthday
required
Format DATE(8), YYYYMMDD
Samples
20190101
19991231

Date of birth of customer

ip
required
Format CHAR(1..39)

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

Bank TRANSFER PARAMETERS
bankcountry
optional
Format LIST
Account type/ country for use with BBAN (i.e. bankcode, bankaccount): DE

DE: Mandatory with bankcode, bankaccount, optional with IBAN

For other countries than DE please use IBAN or IBAN/BIC

bankaccount
optional
Numeric (1..10)

Account number (BBAN)

DE: bankcountry, bankcode and bankaccount may be used. Then IBAN will be generated by PAYONE platform and used for SEPA transactions.
Not DE: Please use IBAN or IBAN / BIC.

bankcode
optional
Numeric (1..8)

Sort code (BBAN) (only in DE)

DE: bankcountry, bankcode and bankaccount may be used. Then IBAN will be generated by PAYONE platform and used for SEPA transactions.
Not DE: Please use IBAN or IBAN / BIC.

iban
optional
Format CHAR(8 or 11) Only capital letters and digits, no spaces
Permitted Symbols [0-9][A-Z]

Bank Identifier Code to be used for payment or to be checked

bic
optional
Format CHAR(8 or 11) Only capital letters and digits, no spaces
Permitted Symbols [0-9][A-Z]

BIC is optional for all Bank transfers within SEPA. For Accounts from Banks outside of SEPA, BIC is still required.

ARTicle Parameters
it[n]
not required
it[n] Comments
goods Goods
shipment Shipping Charges


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

id[n]
not required
Format CHAR(1..32)
Array Array elements [n] starting with [1]; serially numbered; max [400]
Symbols [0-9][a-z][A-Z], .,-,_,/

International Article Number (EAN bzw. GTIN)

Product number, SKU, etc. of this item

pr[n]
not required
Format NUMERIC(10) max. 19 999 999 99
Array Array elements [n] starting with [1]; serially numbered; max [400]
Unit gross price of the item in smallest unit! e.g. cent
no[n]
not required
Format NUMERIC(6)
Array Array elements [n] starting with [1]; serially numbered; max [400]

Quantity of this item

de[n]
not required
Format CHAR(1..255)
Array Array elements [n] starting with [1]; serially numbered; max [400]
Description of this item. Will be printed on documents to customer.
add_paydata PARAMETERS
add_paydata[installment_duration]
optional
Required for Unzer Ratenkauf, value has to be the result of a preceding generic calculation request
add_paydata[company_trade_registry_number]
not required
Trade registry number for B2B transactions
add_paydata[b2b]
optional
Optional, defaults to “no”

Set “yes” for B2B transactions

B2B transactions only available for PYV transactions.

add_paydata[company_uid]
not required

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

add_paydata[company_register_key]
not required
ID of other company register than trade registry or UID
add_paydata[mobile]
not required
Optional mobile phone number
add_paydata[analysis_transportation_<suffix>]
not required
<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>]
not required

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>]
not required

Item category

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

add_paydata[analysis_webshop_url]
not required
Webshop URL
add_paydata[payolution_session_id]
not required
see Chapter "Fraud Prevention" for more details

ReSponse Parameters
status
required
Permitted Values
APPROVED
ERROR
ReSponse Parameter (APPRoved)
Format NUMERIC(9..12)

The txid specifies the payment process within the PAYONE platform

Format NUMERIC(6..12)
Used to reference a preceding calculation or pre-check request
Format CHAR(2..1024)

Accounting number, used to print on the invoice

ReSponse Parameter (Error)
Format NUMERIC(1..6)

In case of error the PAYONE Platform returns an error code for your internal usage.

Format CHAR(1..1024)

In case of error the PAYONE Platform returns an error message for your internal usage.

Format CHAR(1..1024)

The customermessage is returned to your system in order to be displayed to the customer.

(Language selection is based on the end customer's language, parameter "language")



Host: api.pay1.de
Content-Type: application/x-www-form-urlencoded
Payload
        
https://api.pay1.de/post-gateway/
aid=52078
amount=49595
api_version=3.10
birthday=19711110
city=Frankfurt am Main
clearingtype=fnc
country=DE
currency=EUR
email=frank.hartung@payone.com
encoding=UTF-8
financingtype=PYV
firstname=Manuel
hash=d9e909f9004dae0c838b142e48505fb388b2d26f979e96a805dc602fec0babc6c585cc1036c78e94ffcf8b90dd95adb0
integrator_name=shopware6
integrator_version=6.5.8.3
ip=89.245.17.41
key=19539eb4b369b29f314b51368076475a
language=de
lastname=Weißmann
mid=14648
mode=test
portalid=2037267
reference=1240501003
request=preauthorization
salutation=Herr
shipping_city=Frankfurt am Main
shipping_country=DE
shipping_firstname=Manuel
shipping_lastname=Weißmann
shipping_street=Hugo-Junckers-Straße 3
shipping_zip=60386
solution_name=kellerkinder
solution_version=dev-task/PAYOSWXP-47
street=Hugo-Junckers-Straße 3
zip=60386
RESPONSE
                            
status=APPROVED
add_paydata[PaymentDetails_1_Duration]=1
add_paydata[PaymentDetails_1_Installment_1_Amount]=495.95
add_paydata[PaymentDetails_1_Installment_1_DueInDays]=14
add_paydata[txid]=TX1B1DC6WU4019L0
add_paydata[PaymentDetails_1_MinimumInstallmentFee]=0
add_paydata[PaymentDetails_1_Currency]=EUR
add_paydata[PaymentDetails_1_Installment_1_Due]=2024-02-22
add_paydata[PaymentDetails_1_TotalAmount]=495.95
add_paydata[PaymentDetails_1_OriginalAmount]=495.95
add_paydata[workorderid]=WX1B1DC6WUUKFC6H
add_paydata[clearing_reference]=XGBG-FBSM-GKTN
add_paydata[PaymentDetails_1_Usage]=Calculated by calculation service
txid=995802748
userid=663754411                        
POST Request Capture

The capture request is used to finalize a preauthorized transaction.

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

common Parameters
txid
required
Format NUMERIC(9..12)

The txid specifies the payment process within the PAYONE platform

clearingtype
required
Fixed Value fnc
financingtype
required
Fixed Value PYV, PYM, PYS, PYD

PYV: Unzer Rechnungskauf

PYM: Unzer - Monthly

PYS: Unzer Ratenkauf

PYD: Unzer Lastschrift

capturemode
required
Format LIST
Value Comment
completed Set with last capture; i.e.: Delivery completed.
No further capture is allowed.
notcompleted Set with partial deliveries (last delivery with "completed")
Another capture is expected to complete the transaction.

     

Specifies whether this capture is the last one or whether there will be another one in future.

sequencenumber
optional
Format NUMERIC(1..3)
Permitted values 0..127

Sequence number for this transaction within the payment process (1..n), e.g. PreAuthorization: 0, 1. Capture: 1, 2. Capture: 2

Required for multi partial capture (starting with the 2nd capture)

amount
required
Format NUMERIC(1..10)
Permitted values max. +/- 19 999 999 99

Specifies the total gross amount of a payment transaction.

Value is given in smallest currency unit, e.g. Cent of Euro

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

currency
required
Fixed Value EUR
narrative_text
not required
Format CHAR(1..81)

Dynamic text element on account statements
(3 lines with 27 characters each) and credit card statements.

add_paydata PARAMETERS
add_paydata[b2b]
optional
Optional, defaults to “no”

Set “yes” for B2B transactions

B2B transactions only available for PYV transactions.

add_paydata[analysis_customer_<suffix>]
not required

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]
not required

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

add_paydata[analysis_order_id]
not required
Additional field for an order ID that the merchant can use for his own purposes
Response Parameters
Permitted Values
APPROVED
ERROR
Response Parameter (approved)
Format NUMERIC(9..12)

The txid specifies the payment process within the PAYONE platform

Accounting number, used to print on the invoice (only for API version >3.10).
Response parameters (error)
Format NUMERIC(1..6)

In case of error the PAYONE Platform returns an error code for your internal usage.

Format CHAR(1..1024)

In case of error the PAYONE Platform returns an error message for your internal usage.


POST Request Debit

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

ADd_Paydata Parameters
add_paydata[analysis_invoice_id
not required
Additional field for an invoice ID that the merchant can use for his own purposes
add_paydata[analysis_order_id]
not required
Additional field for an order ID that the merchant can use for his own purposes
add_paydata[b2b]
optional
Optional, defaults to “no”

Set “yes” for B2B transactions

B2B transactions only available for PYV transactions.


genericpayment – Requests

POST Request genericpayment – add_paydata[action] = calculation

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.

common Parameters
clearingtype
required
Fixed Value fnc
financingtype
required
Fixed Values PYV, PYM, PYS, PYD

PYV: Unzer Rechnungskauf

PYM: Unzer - Monthly

PYS: Unzer Ratenkauf

PYD: Unzer Lastschrift

amount
optional
Required for action=pre_check and action=calculation
currency
required

Format List

Permitted values ISO 4217 (currencies) 3-letter-codes

Samples

EUR

USD

GBP

add_paydata PARAMETERS
add_paydata[action]
required
Fixed Value calculation
add_paydata[analysis_merchant_comment]
not required
Comment field for the merchant
add_paydata[company_uid]
not required
Only for action=pre_check

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

Response Parameter

Permitted Values

OK
ERROR
 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
Host: api.pay1.de
Content-Type: application/x-www-form-urlencoded
Payload
        
https://api.pay1.de/post-gateway/
add_paydata[action]=calculation
aid=52078
amount=49595
api_version=3.10
birthday=19710110
city=Frankfurt am Main
clearingtype=fnc
country=DE
currency=EUR
email=frank.hartung@payone.com
encoding=UTF-8
financingtype=PYS
firstname=Manuel
hash=7f015290822476e1e062f9ef9f77a537cdde4fe533cfba2cf0afa6d7e6610fb71fd39c0357398451adfc911304a8ce0e
integrator_name=shopware6
integrator_version=6.5.8.3
ip=89.245.17.41
key=19539eb4b369b29f314b51368076475a
language=de
lastname=Weißmann
mid=14648
mode=test
portalid=2037267
request=genericpayment
salutation=Herr
solution_name=kellerkinder
solution_version=dev-task/PAYOSWXP-47
street=Hugo-Junckers-Straße 3
workorderid=WX1B0DC6153HQN3A
zip=60386
RESPONSE
                            
status=OK
add_paydata[PaymentDetails_1_Duration]=3
add_paydata[PaymentDetails_6_EffectiveInterestRate]=16.01
add_paydata[PaymentDetails_5_Installment_2_Due]=2024-04-05
add_paydata[PaymentDetails_5_Installment_3_Amount]=44.69
add_paydata[PaymentDetails_5_Installment_4_Amount]=44.69
add_paydata[PaymentDetails_5_Installment_7_Amount]=44.69
add_paydata[PaymentDetails_6_Installment_4_Due]=2024-06-05
add_paydata[PaymentDetails_6_Installment_17_Due]=2025-07-05
add_paydata[PaymentDetails_5_Installment_9_Amount]=44.69
add_paydata[PaymentDetails_5_Installment_1_Amount]=44.69
add_paydata[PaymentDetails_5_Installment_2_Amount]=44.69
add_paydata[PaymentDetails_5_Installment_5_Amount]=44.69
add_paydata[PaymentDetails_5_Installment_6_Amount]=44.69
add_paydata[PaymentDetails_1_MinimumInstallmentFee]=0
add_paydata[PaymentDetails_5_Installment_8_Amount]=44.69
add_paydata[PaymentDetails_6_Installment_7_Amount]=24.00
add_paydata[PaymentDetails_6_Installment_8_Amount]=24.00
add_paydata[PaymentDetails_6_Installment_9_Amount]=24.00
add_paydata[PaymentDetails_6_Installment_2_Due]=2024-04-05
add_paydata[PaymentDetails_4_Installment_9_Due]=2024-11-05
add_paydata[PaymentDetails_5_EffectiveInterestRate]=16.02
add_paydata[PaymentDetails_4_Installment_6_Amount]=58.51
add_paydata[PaymentDetails_6_Installment_1_Amount]=24.00
add_paydata[PaymentDetails_6_Installment_6_Due]=2024-08-05
[...]
add_paydata[PaymentDetails_6_Installment_21_Amount]=24.00
add_paydata[PaymentDetails_4_Installment_6_Due]=2024-08-05
add_paydata[PaymentDetails_4_Currency]=EUR
add_paydata[PaymentDetails_6_Installment_10_Amount]=24.00
add_paydata[PaymentDetails_6_Installment_14_Amount]=24.00
add_paydata[PaymentDetails_5_Installment_12_Due]=2025-02-05
add_paydata[PaymentDetails_4_StandardCreditInformationUrl]=https://test-payment.paylater.unzer.com/payolution-payment/rest/query/customerinfo/pdf?trxId=Tx-dxsxfzfkn7z&duration=9
add_paydata[PaymentDetails_3_Installment_5_Due]=2024-07-05
add_paydata[PaymentDetails_6_Usage]=Calculated by calculation service
add_paydata[PaymentDetails_2_Installment_2_Amount]=127.66
workorderid=WX1B0DC6153HQN3A
POST Request genericpayment – add_paydata[action] = pre_check

This can be used to perform a preliminary risk check.

common Parameters
clearingtype
required
Fixed Value fnc
financingtype
required
Fixed Value PYV, PYM, PYS, PYD

PYV: Unzer Rechnungskauf

PYM: Unzer - Monthly

PYS: Unzer Ratenkauf

PYD: Unzer Lastschrift

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

Customers e-mail address

amount
required
Required for action=pre_check and action=calculation
currency
required

Format List

Permitted values ISO 4217 (currencies) 3-letter-codes

Samples

EUR

USD

GBP

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

birthday
required

Date of birth (YYYYMMDD)

firstname
optional
First name
lastname
required

Surname

street
optional
Street name and number
zip
required
Postcode
city
optional
City
country
required
Format List
Permitted values ISO 3166 2-letter-codes
Samples
DE
GB
US

Specifies country of address for the customer.

Some countries require additional information in parameter "state"
add_paydata PARAMETERS
add_paydata[action]
required
Fixed Value pre_check
add_paydata[payment_type]
required
Format LIST
Permitted values Payolution-Invoicing, Payolution-Installment, Payolution-Monthly, Payolution-Debit
add_paydata[b2b]
not required
Optional, defaults to “no”

Set “yes” for B2B transactions

B2B transactions only available for PYV transactions.

add_paydata[company_trade_registry_number]
not required
Trade registry number for B2B transactions
add_paydata[company_register_key]
not required
ID of other company register than trade registry or UID
add_paydata[mobile]
not required
Only for action=pre_check
Optional mobile phone number
add_paydata[payolution_session_id]
not required
see Chapter "Fraud Prevention" for more details
Response Parameters
Permitted Values
OK
ERROR
Response Parameter (OK)
 workorderid
Format CHAR(1..50)

The workorderid is a technical id returned from the PAYONE platform to identify a workorder. A workorder is a part of a payment process (identified by a txid). The workorderid is used for the genericpayment request.

Response Parameter (ERRor)
Format NUMERIC(1..6)

In case of error the PAYONE Platform returns an error code for your internal usage.

Format CHAR(1..1024)

In case of error the PAYONE Platform returns an error message for your internal usage.

Host: api.pay1.de
Content-Type: application/x-www-form-urlencoded
Payload
        
https://api.pay1.de/post-gateway/
add_paydata[action]=pre_check
add_paydata[payment_type]=Payolution-Installment
aid=52078
amount=10000
api_version=3.10
birthday=19900505
city=Test
clearingtype=fnc
country=DE
currency=EUR
email=test@example.com
encoding=UTF-8
financingtype=PYS
firstname=Test
hash=fe6469c3fae568d427ea33a5ab5822ca966634d37f4e527e100b139a511cd0922f47ac554615587c27b0ad286efaabf1
ip=127.0.0.1
key=19539eb4b369b29f314b51368076475a
lastname=Test
mid=14648
mode=test
portalid=2037267
reference=TESTPO-7119981132236
request=genericpayment
street=teststreet 2
zip=12345
RESPONSE
                            
status=OK
workorderid=WX1A6DC65EFPX83F
POST Request genericpayment – add_paydata[action] = refund_announcement

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.

common parameters
clearingtype
required
Fixed Value fnc
financingtype
required
Fixed Value PYV, PYM, PYS, PYD

PYV: Unzer Rechnungskauf

PYM: Unzer - Monthly

PYS: Unzer Ratenkauf

PYD: Unzer Lastschrift

amount
required
Required for action=pre_check and action=calculation
currency
required
Format List

 

Permitted values ISO 4217 (currencies) 3-letter-codes

Samples EUR, USD, GBP

workorderid
required

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

add_paydata PARAMETERS
add_paydata[action]
required
Fixed Value refund_announcement
add_paydata[txid]
required

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

Response Parameters
Permitted Values
OK
ERROR
Response Parameter (ok)
 workorderid
Format CHAR(1..50)

The workorderid is a technical id returned from the PAYONE platform to identify a workorder. A workorder is a part of a payment process (identified by a txid). The workorderid is used for the genericpayment request.

Response Parameter (Error)
Format NUMERIC(1..6)

In case of error the PAYONE Platform returns an error code for your internal usage.

Format CHAR(1..1024)

In case of error the PAYONE Platform returns an error message for your internal usage.


POST Request genericpayment – add_paydata[action] = fulfillment_delay

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.

common parameters
amount
required
Required for action=pre_check and action=calculation
currency
required
Format List

 

Permitted values ISO 4217 (currencies) 3-letter-codes

Samples EUR, USD, GBP

workorderid
required

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

add_paydata PARAMETERS
add_paydata[action]
required
Fixed Value fulfillment_delay
add_paydata[txid]
required

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

add_paydata[analysis_expected_fulfillment_date]
required
Format YYYY-MM-DD

New expected fulfillment date.

Response Parameters
Permitted Values
OK
ERROR
Response Parameter (OK)
 workorderid
Format CHAR(1..50)

The workorderid is a technical id returned from the PAYONE platform to identify a workorder. A workorder is a part of a payment process (identified by a txid). The workorderid is used for the genericpayment request.

Response Parameter (Error)
Format NUMERIC(1..6)

In case of error the PAYONE Platform returns an error code for your internal usage.

Format CHAR(1..1024)

In case of error the PAYONE Platform returns an error message for your internal usage.


Referencing preliminary requests by “workorderid”

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:

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

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(-)

Example
SessionId= merchantshop_cd-695a7565-979b-4af9

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.

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.

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

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

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.

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

B2B Transactions

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.

B2B transactions are only available for Unzer Rechnungskauf.

Unzer HTTP Authentication

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.

Sequence Diagrams

Installment Authorization and Refund

Installment Preauthorization and Refund

Invoice Sale Authorization and Refund

Invoice Preauthorization and Refund

Reversal

Testdata

Please refer to the Unzer documentation for specific test data: https://docs.unzer.com/reference/test-data/