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
optional
|
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 "@" 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]
optional
|
Note: handling and voucher are not supported and will be mapped to goods
|
||||||
|
id[n]
optional
|
Format CHAR(1..32)
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]
optional
|
Format NUMERIC(10) max. 19 999 999 99
Array elements [n] starting with [1]; serially numbered; max [400]
Unit gross price of the item in smallest unit! e.g. cent |
||||||
|
no[n]
optional
|
Format NUMERIC(6)
Array elements [n] starting with [1]; serially numbered; max [400]
Quantity of this item |
||||||
|
de[n]
optional
|
Format CHAR(1..255)
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]
optional
|
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]
optional
|
VAT identification number, recommended for better acceptance rates with b2b transactions |
|
add_paydata[company_register_key]
optional
|
ID of other company register than trade registry or UID |
|
add_paydata[mobile]
optional
|
Optional mobile phone number |
|
add_paydata[analysis_transportation_<suffix>]
optional
|
<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>]
optional
|
<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>]
optional
|
Item category Replace <n> with the shopping item id you want to categorize |
|
add_paydata[analysis_webshop_url]
optional
|
Webshop URL |
|
add_paydata[payolution_session_id]
optional
|
see Chapter "Fraud Prevention" for more details |
ReSponse Parameters
|
status
required
|
Permitted Values
APPROVED
ERROR
|
ReSponse Parameter (APPRoved)
|
txid
|
Format NUMERIC(9..12)
The txid specifies the payment process within the PAYONE platform |
|
workorderid
|
Format NUMERIC(6..12)
Used to reference a preceding calculation or pre-check request |
|
add_paydata[clearing_reference
|
Format CHAR(2..1024)
Accounting number, used to print on the invoice |
ReSponse Parameter (Error)
|
errorcode
|
Format NUMERIC(1..6)
In case of error the PAYONE Platform returns an error code for your internal usage. |
|
errormessage
|
Format CHAR(1..1024)
In case of error the PAYONE Platform returns an error message for your internal usage. |
|
customermessage
|
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
aid=52078
amount=49595
api_version=3.10
birthday=19711110
city=Frankfurt am Main
clearingtype=fnc
country=DE
currency=EUR
email=test@example.com
encoding=UTF-8
financingtype=PYV
firstname=Manuel
hash=d9e909f9004dae0c838b142e48505fb388b2d26f979e96a805dc602fec0babc6c585cc1036c78e94ffcf8b90dd95adb0
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
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
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
optional
|
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>]
optional
|
<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]
optional
|
Additional field for an invoice ID that the merchant can use for his own purposes |
|
add_paydata[analysis_order_id]
optional
|
Additional field for an order ID that the merchant can use for his own purposes |
Response Parameters
|
status
|
Permitted Values
APPROVED
ERROR
|
Response Parameter (approved)
|
txid
|
Format NUMERIC(9..12)
The txid specifies the payment process within the PAYONE platform |
|
add_paydata[clearing_reference]
|
Accounting number, used to print on the invoice (only for API version >3.10) |
Response parameters (error)
|
errorcode
|
Format NUMERIC(1..6)
In case of error the PAYONE Platform returns an error code for your internal usage. |
|
errormessage
|
Format CHAR(1..1024)
In case of error the PAYONE Platform returns an error message for your internal usage. |
POST Request Debit
Only Unzer specific parameters are described here. Refer to the Payone API description
ADd_Paydata Parameters
|
add_paydata[analysis_invoice_id
optional
|
Additional field for an invoice ID that the merchant can use for his own purposes |
|
add_paydata[analysis_order_id]
optional
|
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-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]
optional
|
Comment field for the merchant |
|
add_paydata[company_uid]
optional
|
Only for action=pre_check
VAT identification number, recommended for better acceptance rates with b2b transactions |
Response Parameter
|
status
|
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
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=test@example.com
encoding=UTF-8
financingtype=PYS
firstname=Manuel
hash=7f015290822476e1e062f9ef9f77a537cdde4fe533cfba2cf0afa6d7e6610fb71fd39c0357398451adfc911304a8ce0e
ip=89.245.17.41
key=19539eb4b369b29f314b51368076475a
language=de
lastname=Weißmann
mid=14648
mode=test
portalid=2037267
request=genericpayment
salutation=Herr
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]
optional
|
Optional, defaults to “no”
Set “yes” for B2B transactions B2B transactions only available for PYV transactions. |
| add_paydata[company_trade_registry_number]
optional
|
Trade registry number for B2B transactions |
|
add_paydata[company_register_key]
optional
|
ID of other company register than trade registry or UID |
|
add_paydata[mobile]
optional
|
Only for action=pre_check Optional mobile phone number |
|
add_paydata[payolution_session_id]
optional
|
see Chapter "Fraud Prevention" for more details
|
Response Parameters
|
status
|
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)
|
errorcode
|
Format NUMERIC(1..6)
In case of error the PAYONE Platform returns an error code for your internal usage. |
|
errormessage
|
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
|
status
|
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)
|
errorcode
|
Format NUMERIC(1..6)
In case of error the PAYONE Platform returns an error code for your internal usage. |
|
errormessage
|
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
|
status
|
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)
|
errorcode
|
Format NUMERIC(1..6)
In case of error the PAYONE Platform returns an error code for your internal usage. |
|
errormessage
|
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(-)
|
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:
|
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/