Glossary

A

accesscode

Customer's password

Format
CHAR(1..32)

accessid

Access ID, defined by PAYONE

Format
NUMERIC(3..12)

accessname

Customer's user name

Format
CHAR(1..32)

access_canceltime

Date of cancellation as Unixtimestamp in the future (after this date no further renewals will be carried out)

Format

Unixtimestamp

access_expiretime

Can be

  1. either used with creating a new access (createaccess)
    -> Set expiry date/time of the initial term as Unixtimestamp (e.g. date of first renewal)
 - deprecated, should not be used. Please use “period_unit_trail”, “period_length_trail” instead.
- do not use with “period_unit_trail”, “period_length_trail”
  1. or used with updating an existing access (updateaccess)
    -> Update expiry date/time of the current term as Unixtimestamp (e.g. overwrite date of next renewal)

Format
Unixtimestamp

access_starttime

Access starting date as Unixtimestamp

Format

Unixtimestamp

action

Action to perform to given contract

Format LIST 

Value Comment

update

Update access (default)

cancel

Cancel subscription

reverse_cancel

Revoke cancellation of sub­scription

lock

Block access

unlock

Unblock access

 

add_paydata[..._entity_type]

Klarna (KLS, KLV, KIV, KIS) - Extra Merchant Data → Value range: Link

Format
LIST

Payment specific:

Payment type Comment

KLS, KLV, KIV, KIS

Mandatory for B2B transactions

Values:

Value

LIMITED_COMPANY 

PUBLIC_LIMITED_COMPANY

ENTREPRENEURIAL_COMPANY

LIMITED_PARTNERSHIP_LIMITED_COMPANY

LIMITED_PARTNERSHIP

GENERAL_PARTNERSHIP

REGISTERED_SOLE_TRADER

SOLE_TRADER

CIVIL_LAW_PARTNERSHIP

PUBLIC_INSTITUTION

OTHER

add_paydata[reservation_txid]

The reservation_txid is a technical id returned from the PAYONE platform to identify a reservation. A reservation is a part of a payment process (identified by a txid). The reservation is used for "genericrequest".

Format

CHAR(12..50) 

Permitted Symbols
[0-9,A-Z] 

add_paydata[...url_standard_n]

Example = Response from Content Delivery network Klarna (https, svg)
Sample: Badge

add_paydata[...url_descriptive_n]

Example = Response from Content Delivery network Klarna (https, svg)
Sample: Badge

add_paydata[...identifier_n]

The values known to us at the time of implementation are as follows:

Payment Category

pay_later

direct_debit

pay_over_time

add_paydata[...tegory_name_n]

Payment Type

Slice it

Pay Later

Direct debit

addressaddition

Specifies an additional address line for the invoice address of the customer.

Format
CHAR(1..50)

Samples
7th floor

c/o Maier

Payment specific:

Payment type Comments

KLV, KLS

Mandatory

addresschecktype

Specifies type of address check to be performed

Format
LIST

Value Group Comment

BA

PAYONE Services

Addresscheck Basic, i.e. address is checked whether the address itself is valid and existing

PE

PAYONE Services

Addresscheck Person, i.e. address is checked whether the address itself is valid and existing and whether the given person is recorded at this address

BB

Boniversum Services

Addresscheck Basic, i.e. address is checked whether the address itself is valid and existing

PB

Boniversum Services

Addresscheck Person, i.e. address is checked whether the address itself is valid and existing and whether the given person is recorded at this address

aid

Sub-Account ID, defined by PAYONE 

Format
NUMERIC(5..6)

ALP

Meaning: Alipay

amount

Specifies the total gross amount of a payment transaction.

Value is given in smallest currency unit, e.g. Cent of Euro; Pence of Pound sterling; Öre of Swedish krona.

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

Format
NUMERIC(1..10)

Permitted values

max. +/- 19 999 999 99

Payment specific:

Payment type Comments

PDT

Maximum amount is limited to 5000000 (i.e. 50,000.00 Euro)

amount capture

Specifies the total gross amount of a payment transaction.

Value is given in smallest currency unit, e.g. Cent of Euro; Pence of Pound sterling; Öre of Swedish krona.

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

Format
NUMERIC(1..10)

Permitted values

max. +/- 19 999 999 99

Special use cases:

  1. with previous preauthorization and clearingtype=”cc”: An “amount = 0” can be used to cancel a reserved amount of money (with a preauthorization) at the acquirer.
  2. with previous preauthorization and clearingtype=”wlt”, wallettype=”PPE”: An “amount = 0” can be used to cancel a reserved amount of money (with a preauthorization) at PayPal.
  3. with previous preauthorization/ authorization and clearingtype=”elv”: An “amount = 0” can be used to cancel a direct debit transaction. This is not possible if the parameter “due_time” has been used, if the portal has enabled a delayed settlement (setup by PAYONE) or the direct debit has already been processed (after midnight).
  4. with previous preauthorization and  clearingtype=”fnc”, “financingtype=“KLV” or “KLS”: An “amount = 0” can be used to cancel a reserved amount of money (with a preauthorization) at external Payment Service Provider.
  5. Not supported for other payments.
amount debit

Gross amount of debit (in smallest currency unit! e.g. cent, max. 19 999 999 99)

Credit: amount < 0

Payment request: amount > 0

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

Format

NUMERIC(1..10)

Permitted values

max. +/- 19 999 999 99

amount refund

Amount of refund (in smallest currency unit! e.g. cent, max. 19 999 999 99). The amount must be less than or equal to the amount of the corresponding booking.
Always provide a negative amount

Format
NUMERIC(1..10)

Permitted values

max. +/- 19 999 999 99

amount_trail

Total gross amount for initial term

Must equal the sum (quantity x price) of all items for the initial term.

Required when item is submitted.

Amount can be "0" (e.g. for test period).

Format
NUMERIC(1..8)

Permitted values

max. +/- 19 999 999 99

amount_recurring

Total gross amount of all items of one period during the subsequent term

Must equal the sum (quantity x price) of all items during the subsequent term.

Required when item is submitted.

Amount must not be "0".

Format

NUMERIC(1..8)

Permitted values

max. +/- 19 999 999 99

AMZ / AMP

Meaning: Amazon Pay

api_version

New parameter api_version should be added to current implementations as it will be mandatory in future.

Format
LIST 

api_version Comment Description

3.8

Current API-version
(Default if not present)

3.9

New API-version
from 2015-01-05

New response “pending” added for “preauthorization” / “authorization”

3.10

New API-version
from 2016-06-01

Response for “customermessage” can be more specific in case of error by containing detailed error messages from external payment gateways (e.g. Ratepay, …)

3.11

New API-version
from 2018-02-01

Request “capture” with response “pending”

  1. Announcement for upcoming request “refund” / response “pending”
  2. Announcement for upcoming request “createaccess” / response “pending”
APL

Meaning: Apple Pay

autosubmit

Specifies whether payment details should be queried with customer interaction or with payment details provided in Frontend request URL.

Format
LIST

Value Comment

no

no: No auto-submit (default)

yes

Payment is executed immediately without customer interaction. If the payment was successful the customer is forwarded directly to the „successurl“.

All payment data must be transmitted in this version.

AVS

AVS (Address Verification System) is currently only supported for American Express

B

BCT

Meaning: Bancontact

backurl

URL for "Back" or "Cancel"

Format
CHAR(2..255)

Scheme

<scheme>://<host>/<path>
<scheme>://<host>/<path>?<query>


scheme-pattern: [a-zA-Z]{1}[a-zA-Z0-9]{1,9}

URL is required for any type of redirect payments, e.g.
- Bancontact, EPS, Giropay, iDEAL, Multibanco, PostFinance, Przelewy24, SOFORT, Trustly, ...
- PayPal, ...
- credit card with 3-D secure
Allowed schemes for URL:
- For Channel "Frontend" / "Client-API" only schemes "http" or "https" allowed.
- For Channel "Server-API" individual schemes like "app://app.domain.com" is allowed
URL can be
- either defined in PMI -> configuration -> portal
-> then this URL is used as default
(this requires channel "Frontend" to be avalibale)
- or it can be specified via API parameter
-> then this URL overrides the PMI-configuration.
Example
Valid for all channels (Server, Client, Frontend):
https://www.domain.com/success.html
https://www.domain.com/success.html?exit=success&txid=__txid__
https://www.domain.com/back.html?exit=back
https://www.domain.com/error.html?exit=error&errorcode=__errorcode__

Valid additionally for Server-API:
app://app.domain.com/success.html?exit=success&txid=__txid__
myscheme://myapp.domain.com/success.html?exit=success&txid=__txid__
myscheme://myapp.domain.com/error.html?exit=error&errorcode=__errorcode__

Payment specific:

Payment type Comments

Redirect payment

For redirect payments (e.g. PayPal, Giropay, SOFORT, ...) an URL has to be provided.

It can be

  1. either defined in PMI -> configuration -> portal
    -> then this URL is used as default
  2. or it can be specified via API parameter
    -> then this URL overrides the PMI-configuration.
bankaccount

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.

Format
NUMERIC(1..10)

bankaccountholder

Account holder

Format

CHAR(1..50)

The account holder is required for bank transfer (SEPA direct debit and SEPA credit transfer).
If the account holder is not specified the PAYONE platform will use firstname / lastname / company for account holder
bankcode

Sort code (BBAN) (only in DE)

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

Format
NUMERIC(8)

bankcountry

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

Format
LIST

bankcountry obt

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

Format

LIST

Values onlinebanktransfertype Payment type

BE

BCT

Bancontact

AT

EPS

EPS

NL

IDL

iDEAL

PT

MBC

Multibanco

IT

MYB

MyBank

PL

P24

Przelewy24 (P24)

CH

PFC

PostFinanceCard

CH

PFF

Post E-Finance

DE;AT;CH;NL;PL;BE

PNT

SOFORT

DE;DK;EE;ES;FI;IT;

MT;NL;NO;PL;SE

TRL

Trustly

FI

VKP

Verkkopankki

bankgrouptype

Issuer of Online-Bank-Transfer used for iDEAL and EPS

Format

LIST

Value Comment

List of supported EPS banks

Bank Groups (EPS) (bankgrouptype)

List of supported iDEAL banks

Bank Groups (iDEAL) (bankgrouptype)

Payment specific:

Payment type Comment

EPS

Mandatory

IDL

Mandatory

bic

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

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. 

birthday

Date of birth of customer

Format

DATE(8), YYYYMMDD

Samples

20190101

19991231

Payment specific:

Request Payment type/ score type Comments

preauthorization
authorization

KLV, KLS, KIV, KIS

Parameter is mandatory for this payment type

preauthorization
authorization

POV

Parameter is mandatory for this payment type with businessrelation=b2c

preauthorization
authorization

PYV, PYM, PYS, PYD

Parameter is mandatory for this payment

consumerscore

SCHUFA Services “b2c”

Parameter is mandatory for this request

booking_date

Booking date (YYYYMMDD)

Format

DATE(8), YYYYMMDD

businessrelation

Value specifies business relation between merchant and customer

Format
LIST

Value Comment

b2c

Indicates business to private customer

b2b

indicates business to business customer (company)

Request specific: 

Payment type Comment

POV

Mandatory

Full list of values:

Value Business from Business to Comment

b2c

business (company)

consumer (private)

b2b

business (company)

business (company)

b2a

business (company)

administration (government)

not in use by now

a2a

administration (government)

administration (government)

not in use by now

a2b

administration (government)

business (company)

not in use by now

a2c

administration (government)

consumer (private)

not in use by now

c2a

consumer (private)

administration

not supported

c2b

consumer (private)

business (company)

not supported

c2c

consumer (private)

consumer (private)

not supported

businessrelation (scoring)

Value specifies business relation between merchant and customer

Format

LIST

Value Comment

b2c

Indicates business to private customer

b2b

indicates business to business customer (company)

Payment specific:

Consumerscoretype Comment

SFS, SFM

"businessrelation" is mandatory for SCHUFA-checks

other

"businessrelation" is recommended be set to "b2c" for other checks

BZN

Meaning: Barzahlen

C

capturemode

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

Format

LIST 

Value Comment

completed

  1. Set with last capture; i.e.: Delivery completed.
  2. No further capture is allowed.

notcompleted

  1. Set with partial deliveries (last delivery with "completed")
  2. Another capture is expected to complete the transaction.

Payment specific:

Payment type Comment

PDT

Parameter "capturemode" is mandatory.

KLS, KLV

Parameter "capturemode" is mandatory.

cardcvc2

Credit card security number

Format
NUMERIC(3..4)

For SAQ A compliance: PAYONE Frontend hosted iFrame must be used. This parameter must not be used.
cardexpiredate

Credit card expiry date YYMM

Format

NUMERIC(4), YYMM

cardexpiremonth

Credit card expiry month MM

Format

NUMERIC(2), MM

cardexpireyear

Credit card expiry year YYYY

Format
NUMERIC(4), YYYY

cardholder

Cardholder of credit card.

Format

CHAR(1..50)

if the cardholder is not specified the PAYONE platform will use firstname / lastname for cardholder
However, the correct cardholder name plays a great role in the internal risk assessment of the issuer, so providing it can be beneficial in terms of 3-D Secure

cardissuenumber

Card issue number (only Maestro UK cards)

Format

NUMERIC(1..2)

cardpan

Primary account number of credit card

Format
NUMERIC(13..19)

if your system handles "cardpan" directly you can not be PCI DSS SAQ A compliant.
for simple PCI DSS SAQ A compliance please use PAYONE hosted iFrames together with pseudocardpan.
cardtype

Card type of credit card

Format

LIST

Full list of values:

M
Value Commentfrom BIN-Range for automatic card type detection

V

Visa

4

M

MasterCard

51-55,2221-2720

A

American Express

34, 37

D

Diners / Discover

300-305,3095,36,38,39

601, 64, 65

J

JCB

3528-3589

O

Maestro International

50, 56-58,602, 61, 620, 627, 63, 67

P

China Union Pay

62212600-62299800,624-626, 6282-6288

U

UATP / Airplus

1220, 1920 -> coming soon; not available yet

G

girocard

68 (girocard is currently only viable for e-commerce-payments via Apple Pay.)

Parameter "cardtype" can be omitted for request "creditcardcheck". The card type will then be detected automatically and returned in response.
Parameter "cardtype" must be present for credit card payment requests . Value for "cardtype" can be retrieved from previous creditcardcheck-response.

cavv

3-D Secure authentication value

Format

CHAR(1..40) 

checktype

Specifies type of check to be performed, e.g. creditcardcheck or bankaccountcheck

Format
LIST

Request Value Comment

bankaccountcheck

0

  1. regular check (default)
  2. IBAN is checked for correct syntax (mode live only)
  3. IBAN is splitted into BBAN (mode live only)

bankaccountcheck

1

check against POS blacklist (only DE)

bankaccountcheck

2

check against NCA list (non-consumer account)

creditcardcheck

without "checktype" given the regular check is performed (LUHN-check)

For Deutsche Bahn only:

Request checktype Comment

creditcardcheck

TC

  1. For Deutsche Bahn only:
    extended check for travelcards with specific response data
city

City of customer

Format

CHAR(2..50)

Payment specific:

Payment type Comments

KLV, KLS

Mandatory

PYV, PYM,
PYS, PYD

Mandatory

ELV

Mandatory for direct debit (ELV) used with IBAN-countries CH, SM, MC, PM, JE, GG

According to the new regulation on the transfer of funds (Geldtransferverordnung) address data (name, street, zip, city) is mandatory for cross border bank transfers (EEA / EWR), e.g.: CH, SM, MC, PM, JE, GG. This is mandatory from 2017-11-19. This takes effect when “capture” is done.

clearingsubtype

Only valid with “clearingtype=rec”. Used for PAYONE Secure Invoice.

Format

LIST  

Value Comment

POV

PAYONE secure purchase on invoice

clearingtype

Format
LIST

Value Comment Description/ Comments

elv

Debit payment

According to the new regulation on the transfer of funds (Geldtransferverordnung) address data (name, street, zip, city) is mandatory for cross border bank transfers (EEA / EWR), e.g.: CH, SM, MC, PM, JE, GG. This is mandatory from 2017-11-19.

Please use request “updateuser” to update customers address data.

This means that the whole address for bank transfers needs to be provided.

cc

Credit card

rec

Invoice

cod

Cash on delivery

not allowed for vauthorization, createaccess, updateaccess

vor

Prepayment

not allowed for vauthorization, createaccess, updateaccess

sb

Online Bank Transfer

not allowed for vauthorization, createaccess, updateaccess

wlt

e-wallet

not allowed for vauthorization, createaccess, updateaccess

fnc

Financing

not allowed for vauthorization, createaccess, updateaccess

csh

Cash or Hybrid Payments

not allowed for vauthorization, createaccess, updateaccess

clearingtype debit

Use for changes of payment type - only to select new payment type.

Format

LIST

Payment specific:

Value Comments

rec

Invoice

company

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

  1. "company"
  2. or "lastname"
  3. or "firstname" plus "lastname"

Format

CHAR(2..50)

Payment specific:

Payment/ request type Comments

PNT

Company name is limited to 27 characters

consumerscore B2B

  1. "company" required for b2b-request (e.g. “PAYONE GmbH”)
  2. "company" empty for person managed companies
country

Specifies country of address for the customer 

Format
LIST

Permitted values
ISO 3166 2-letter-codes

Samples
DE, GB, US

Some countries require additional information in parameter "state"

Request restrictions:

Request Comment

addresscheck

Check “BB”, “PB”: only “DE” supported

consumerscore

only “DE” supported

creditor_identifier

Creditor identifier as recorded at PAYONE

Format

CHAR(1..35)

currency

Specifies currency for this transaction

Format

LIST 

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

Samples
EUR
USD
GBP

customerid

Merchant's customer ID, defined by you / merchant to refer to the customer record

Format
CHAR(1..20)

Permitted values
[0-9, a-z, A-Z, .,-,_,/]

"customerid" can be used to identify a customer record.
If "customerid" is used then stored customer data are loaded automatically.
customermessage

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

Format

CHAR(1..1024)

With “api_version>=3.10” you may get more detailed error messages from the external payment processor (e.g. Ratepay)

customer_is_present

Indicates whether customer is “present” and can enter their data in the shop (=yes). Or customer is not present and can not enter any data (=no).

Format

LIST 

Permitted values
yes

no

consumerscoretype

Specifies type of consumer score to be performed.

Format
LIST

Value Comment
Arvato Infoscore Services  – must be combined with addresschecktype “NO”, “BA”, “PE”

IH

Infoscore (hard criteria)

IA

Infoscore (all criteria)

IB

Infoscore (all criteria + bonus score)

IF

Infoscore (all criteria + bonus score) + Informa-Consumer-Score

Boniversum Services – must be combined with addresschecktype “PB”

CE

Boniversum VERITA Score including special addresses (status-codes AS1..AS8)

D

de_recurring[n]

Description of this item (subsequent term)

Format

CHAR(1..255)

Array

Array elements [n] starting with [1]; serially numbered; max [100]

Example
de[1]=Product 1
de[2]=Product 2
de[3]=Product 3
...
de[100]=Product 100

Payment specific:

Payment type Comment

PPE

Max. 127 characters are processed

de_trail[n]

Description of this item (initial term)

Format
CHAR(1..255)

Array

Array elements [n] starting with [1]; serially numbered; max [100]

Example
de[1]=Product 1
de[2]=Product 2
de[3]=Product 3
...
de[100]=Product 100

Payment specific:

Payment type Comment

PPE

Max. 127 characters are processed

de[n]

Description of this item. Will be printed on documents to customer.

Format
CHAR(1..255)

Array

Array elements [n] starting with [1]; serially numbered; max [400]

Example
de[1]=Product 1
de[2]=Product 2
de[3]=Product 3
...
de[400]=Product 400

Payment specific:

Payment type Comment

PPE

Max. 127 characters are processed

delete_bankaccountdata

Deleting data for payment method "direct debit".

Format

LIST

Value Comment

yes

Delete data 

no

Do not delete data (default) 

delete_carddata

Deleting data for payment method "credit card".

Format
LIST

Payment specific:

Value Comment

yes

Delete data 

no

Do not delete data (default) 

display_address

Specifies whether the customer address should be queried - instead of providing them in the Frontend request URL.

Format
LIST 

Payment specific:

Value Comment

yes

Address will be queried (default)

no

Address will not be queried if all necessary data were already transferred and are correct 

display_change_order

Specifies whether payment details or payment information should be displayed first.

Format

LIST

Value Comment

no

Unchanged order (default)

yes

Changed order: Payment details are listed after the payment information.

display_name

Specifies whether the customer name / company should be queried - instead of providing them in the Frontend request URL.

Format
LIST

Value Comment

yes

Name will be queried (default)

no

name/company will not be queried if all necessary data were already transferred and are correct

document_date

Document date (YYYYMMDD)

Format
DATE(8), YYYYMMDD

due_time

Due date (Unixtimestamp)

Format

Unixtimestamp

Payment specific: 

Payment type Comment

rec

Due time of the invoice; needed to start dunning run

elv

Debit will be initiated on this date.
Please pay attention that 5 or 2 days are added to the due_time – depending on FIRST or RECURRENT debit.

E

eci

3-D Secure e-commerce indicator

Format

CHAR(1..2)

ecommercemode

Specifies how the payment transaction should be processed - if not default.

Format
LIST

Value Comments

internet

eCommerce Transaction (SSL secured)

3dsecure

3-D Secure transaction (can be enabled alternatively in the risk settings)

moto

Mail or telephone order transaction

A credit card transaction has different types of processing, e.g. "internet/ecommerce" (e.g. online shop) or "moto" (e.g. call center). A default can be setup in a payment portal (identified by portalid) with different defaults per portal.
This default can be overruled by this parameter.

However: a callcenter payment transaction can never be 3-D secure as the customer will not be able to personally enter the 3-D password and he will never tell it to a callcenter agent.
ed[n]

Delivery period end date (YYYYMMDD)

Format
DATE(8), YYYYMMDD

Array

Array elements [n] starting with [1]; serially numbered; max [400]

ELV

Meaning: PAYONE Direct Debit (Elektronisches Lastschrift-Verfahren)

It has been replaced by SEPA Direct Debit (SDD) -> but abbreviation is still used.

email

email-address of customer

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:

  1. Username = Max. 63 characters
  2. Domain Name = Max. 63 characters
  3. 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.

Payment specific:

Payment Type Comment

KLV, KLS

Email-address is mandatory

PYV, PYM, PYS, PYD

Email-address is mandatory

P24

Email-address is mandatory

POV

Email-address is mandatory

encoding

The type of character encoding used in the request.

Format
LIST

Value Comments

ISO-8859-1

Default if not specified

UTF-8

Please keep in mind that TransactionStatus / SessionStatus are always sent in "ISO 8859-1".
EPS

Meaning: EPS

errorcode

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

Format

NUMERIC(1..6)

Please refer to the error codes section.
errorurl

URL for "faulty payment"

Format

CHAR(2..255)

Scheme

<scheme>://<host>/<path>
<scheme>://<host>/<path>?<query>


scheme-pattern: [a-zA-Z]{1}[a-zA-Z0-9]{1,9}

URL is required for any type of redirect payments, e.g.
- Bancontact, EPS, Giropay, iDEAL, Multibanco, PostFinance, Przelewy24, SOFORT, Trustly, ...
- PayPal, ...
- credit card with 3-D secure
Allowed schemes for URL:
- For Channel "Frontend" / "Client-API" only schemes "http" or "https" allowed.
- For Channel "Server-API" individual schemes like "app://app.domain.com" is allowed
URL can be
- either defined in PMI -> configuration -> portal -> then this URL is used as default
(this requires channel "Frontend" to be avalibale)
- or it can be specified via API parameter
-> then this URL overrides the PMI-configuration.
---end
Example
Valid for all channels (Server, Client, Frontend):
https://www.domain.com/success.html
https://www.domain.com/success.html?exit=success&txid=__txid__
https://www.domain.com/back.html?exit=back
https://www.domain.com/error.html?exit=error&errorcode=__errorcode__

Valid additionally for Server-API:
app://app.domain.com/success.html?exit=success&txid=__txid__
myscheme://myapp.domain.com/success.html?exit=success&txid=__txid__
myscheme://myapp.domain.com/error.html?exit=error&errorcode=__errorcode__

Payment specific:

Payment Type Comment

Redirect payment

For redirect payments (e.g. PayPal, Giropay, SOFORT, ...) an URL has to be provided.
It can be

  1. either defined in PMI -> configuration -> portal
    -> then this URL is used as default

  2. or it can be specified via API parameter
    -> then this URL overrides the PMI-configuration.
errormessage

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

Format
CHAR(1..1024)

Please refer to the error codes section.
The errormessage is returned to your system and should only be used for internal purpose (e.g. logging).

It should not be returned to the customer.
exiturl

Exit-URL to be forwarded after authentication on the ACS

Format

CHAR(2..255)

F

financingtype

Used with "clearingtype=fnc" to identify Financing type

Format

LIST

Value Comment Server-API Client-API Frontend

RPV

Ratepay Open Invoice

x x x

RPS

Ratepay Installments

x

x

RPP

Ratepay Prepayment

x

x

x

RPD

Ratepay Direct Debit

x

x

x

PYV

Unzer Invoice

x

x

PYS

Unzer Installment

x

x

PYD

Unzer Direct Debit

x

x

KIS

Klarna Payments "Slice it" (Installments)

x

KIV

Klarna Payments "Pay now" (Invoice)

x

KDD

Klarna Payments "Pay now" (Direct Debit)

x

KBT

Klarna Payments "Pay now" (Bank Transfer)

x

firstname

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

  1. "company"
  2. or "lastname"
  3. or "firstname" plus "lastname"

Format
CHAR(1..50)

Payment specific:

Payment/ request type Comment

PNT

Combination of firstname + lastname is limited to 27 characters

BCT

firstname / lastname are always mandatory

KLV, KLS

firstname / lastname are always mandatory

PYV, PYM, PYS, PYD

firstname / lastname are always mandatory

PDT

firstname is optional

addresscheck

firstname / lastname are always mandatory

consumerscore

firstname / lastname are always mandatory

frontend_description

Confirmation text for the end customer after creating access. The transfer of HTML elements is permitted. At 10,000 characters this parameter is truncated.

Format

CHAR(1..10000)

G

gender

Gender of customer (female / male / diverse)

Format

LIST

Permitted values

f

m

d

Payment type Comment

KLV, KLS

Mandatory in DE, NL, AT

getusertoken

Can be used to get a reference (usertoken) to a debtor which can be passed to another merchant account within the PAYONE platform.

This usertoken is valid for 15 minutes. This reference to a PAYONE debtor can be used for authorization / preauthorization. The debtor-data will then be copied to the other merchant account.

Must not be used together with Parameter "type".

Format
LIST

Value Comment

yes

get usertoken

H

hash

The hash code is used to prevent that a customer changes any relevant value (like payment type, your MID or the amount).

Format

CHAR(1..96) lowercase

Permitted Symbols
[0-9,a-z]

I

iban

IBAN to be used for payment or to be checked

Format

CHAR(10..34)

Permitted Symbols

[0-9][A-Z]

  1. IBAN / BIC will be validated. 
  2. Only capital letters and digits, no spaces
  3. It's not checked whether IBAN and BBAN (Bankcode/Bankaccount) refer to the same account or whether the account does exist.
  4. For some countries IBAN, BIC will be splitted into bankcode, bankaccount automatically
  5. If both (bankcode/bankaccount and IBAN) are submitted, IBAN is splitted into bankcode/bankaccount and IBAN is used for processing - bankcode/bankaccount parameters are ignored.
id_recurring[n]

Product number, order number, etc. of this item (subsequent term)

Format

CHAR(1..32)

Array

Array elements [n] starting with [1]; serially numbered; max [100]

Permitted Symbols

[0-9][A-Z][a-z][()[]{} +-_#/:]

id_trail[n]

Product number, order number, etc. of this item (initial term)

Format
CHAR(1..32)

Array

Array elements [n] starting with [1]; serially numbered; max [100]

Permitted Symbols

[0-9][A-Z][a-z][()[]{} +-_#/:]

id[n]

Product number, SKU, etc. of this item

Format

CHAR(1..32)

Array

Array elements [n] starting with [1]; serially numbered; max [100]

Permitted Symbols

[0-9][A-Z][a-z][()[]{} +-_#/:]

invoiceappendix

Dynamic text on the invoice

Format

CHAR(1..255)

  1. You may use "|" (pipe-symbol) to transmit up to three individual text lines which will be placed on customer documents (invoice, credit note, reminder).
  2. This text will then be displayed at the end of the document - each part in a new line.
invoiceid

Merchant's invoice number

Format
CHAR(1..20)

  1. The PAYONE platform can also incremented the invoiceid automatically. By this your invoices and credit notes will always have a unique id.
  2. The prefix can be specified by our merchant service, e.g. "INVOICE-" - so invoiceids will be generated like "INVOICE-1", "INVOICE-2", "INVOICE-3", ... 
  3. The start number can be given as well.
  4. The invoiceid will then be in a sequence for invoices and credit notes (sharing the same sequence).

invoice_deliverydate

Delivery date (YYYYMMDD)

Format

DATE(8), YYYYMMDD

invoice_deliveryenddate

Delivery end date (YYYYMMDD)

Format

DATE(8), YYYYMMDD

invoice_deliverymode

Parameter defines how documents like invoice, credit notes and reminders should be sent to the customer.

Format
LIST

Value Comments

M

Postal Mail

P

PDF (via email)

N

no delivery

ip

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

Format

CHAR(1..39)

Payment specific for clearingtype financing:

financing type Comments

KLS, KLV

Mandatory

PYV, PYM, PYS, PYD

Mandatory

it[n]

Parameter it[n] specifies the item type of a shopping cart item.

Format

LIST 

Array

Array elements [n] starting with [1]; serially numbered; max [400]

it[n] Comments

goods

Goods

shipment

Shipping charges

handling

Handling fee

Not to be used with PDT

voucher

Voucher / discount 

Not to be used with PDT

Payment specific: 

Payment type Comments

KLS, KLV

Mandatory

POV

Mandatory

J

K

KBT
KDD
key

Payment portal key as MD5 value. The key is used to check the authentification of the sender (either your system for sending requests or PAYONE platform for sending notifications).

Format

CHAR(1..32) lowercase

Permitted Symbols

[0-9,a-z]

  1. MD5 value has to be presented in lower case
  2. Not the key as a value is used, but the MD5 hash of the key value.
  3. You can assign the key to be used in the PMI (PAYONE Merchant Interface) in the portal configuration.
Do not pass this key to third parties in any case.
KIS
KIV

Meaning: Klarna Invoice

L

language

Language indicator (ISO 639) to specify the language that should be presented to the customer (e.g. for error messages, frontend display).

If the language is not transferred, the browser language will be used. For a non-supported language English will be used.

Format

LIST

Permitted

ISO 639-1 (Language) 2-letter-codes

Languages supported for specific customer messages: 

Value Language

de

German

en

English

es

Spanish

fr

French

it

Italian

nl

Dutch

pt

Portuguese

Payment specific reference:

Payment type
financingtype
Comments

KLV, KLS

  1. Parameter is mandatory for this payment type
  2. This payment types supports following languages
     
    Code Meaning

    sv

    swedish

    nb

    norwegian

    fi

    finnish

    da

    danish

    de

    german

    nl

    dutch

lastname

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

  1. "company"
  2. or "lastname"
  3. or "firstname" plus "lastname"

Format

CHAR(2..50)

Payment specific:

Payment/request type Comments

PNT

Combination of firstname + lastname is limited to 27 characters

BCT

firstname / lastname is mandatory

KLV, KLS

firstname / lastname is mandatory

PYV, PYM, PYS, PYD

firstname / lastname is mandatory

PDT

lastname is mandatory

PSC

firstname / lastname is mandatory

addresscheck

firstname / lastname is mandatory

consumerscore

firstname / lastname is mandatory

M

mandate_identification

A SEPA mandate can be created if a payment is initiated (amount > 0). Can be used to enforce a merchant specific mandate identification. The mandate_identification has to be unique.

Format

CHAR(1..35)

Permitted Symbols

[A-Z,a-z,0-9,+,-,.,(,)] 

If the mandate_identification is not set PAYONE will create an unique mandate identification (pattern: PO-nnnnnnnnnn).

PPS (PAYONE Payment Service): This parameter must not be used! For PPS the PAYONE platform defines the mandate_identification
mandate_status

Status of SEPA mandate

Format

LIST

Value Comment

pending

indicates a new created mandate
Pending mandate has to be used within 2 hours by authorization / preauthorization to complete a payment.

active

indicates an existing / active mandate

mandate_text

Content of mandate text

HTML-formatted, URL-encoded

Format
TEXT

MBC

Meaning: Multibanco

mid

Merchant ID, defined by PAYONE

Format

NUMERIC(5..6)

mode

Mode for transactions, either ‘live’ or ‘test’

Format

LIST

Value Comment

live

Transaction should be performed in live mode.

test

Transaction should be simulated 

MPA

Meaning: Masterpass

N

narrative_text

Dynamic text element on account statements

Format

CHAR(1..81)

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

Payment specific:

Payment type Comments

AMZ

Only 16 alphanumeric characters are allowed and will be truncated if it exceeds the limit.

BCT

Only 16 alphanumeric characters are allowed and will be truncated if it exceeds the limit.

KLV, KLS

Text string stored in the invoice commentary area.

PDT

Only 37 alphanumeric characters are allowed and will be truncated if it exceeds the limit. 

Default-Value for narrative_text can be changed in PMI -> portal configuration.
no_recurring[n]

Quantity of this item (subsequent term)

Format

NUMERIC(5)

Array

Array elements [n] starting with [1]; serially numbered; max [100]

no_trail

Quantity of this item (initial term)

Format

NUMERIC(5)

Array

Array elements [n] starting with [1]; serially numbered; max [100]

no[n]

Quantity of this item

Format

NUMERIC(6)

Array

Array elements [n] starting with [1]; serially numbered; max [400]

notify_version

You can setup the notify_version in the PMI -> configuration -> payment portals -> Notify-Version

Format

LIST 

notifiy_version Comments

7.3

Does not send parameter "notify_version" - and no parameter "transaction_status" (compatibility/ old version)

7.4

Does send parameter "notify_version" and parameter "transaction_status" with value "txaction=appointed"

7.5

Does send parameter "notify_version" and parameter "transaction_status" : completed/pending with value "txaction=failed"

7.6

Does send parameter "notify_version" and parameter "transaction_status" : completed/pending with value "txaction=capture" and "reasoncode" if pending.

O

onlinebanktransfertype

Format

LIST 

Payment specific:

Value Comments Server- API Client- API Frontend

BCT

Bancontact

x

x

EPS

eps – online transfer (AT)

x

x

x

IDL

iDEAL (NL)

x

x

x

MBC

Multibanco

x

x

MYB

MyBank

x

x

P24

Przelewy24 (PL)

x

x

x

PFF

PostFinance E-Finance (CH)

x

x

x

PFC

PostFinance Card (CH)

x

x

x

PNT

SOFORT Überweisung

x

x

x

TRL

Trustly(DE)

x

x

VKP

Verkkopankki

x

x

P

param

Individual parameter (per payment process)

Format

CHAR(1..255)

param contract

Individual parameter (per payment process)

This parameter is passed on to all follow-up bookings of the same contract

Format

CHAR(1..255)

payout_open_balance

Credits will be booked on the most recent payment process.

Format

LIST 

Value Comment

yes

Amount will be credited immediately (default)

no

Credited amount will be offset with the subsequent transaction

PDD
PDT

Meaning: Giropay

period_length_recurring

Duration of the subsequent term. Can only be used in combination with period_unit_recurring.

Required when period_length_recurring is submitted.

Format

NUMERIC(1..4)

period_length_trail

Duration of the initial term. Can only be used in combination with period_unit_trail.

Required when period_unit_trail is submitted.

Do not use with “access_expiretime”

Format

NUMERIC(1..4)

period_unit_recurring

Time unit for subsequent term

Do not exceed 5 years / 60 months.

Format

LIST 

Value Comment

Y

Value “length” is in years

M

Value “length” is in months

D

Value “length” is in days

N

No subsequent term given

period_unit_trail

Time unit for initial term

Do not use with “access_expiretime”.

Do not exceed 5 years / 60 months.

Format

LIST 

Value Comment

Y

Value “length” is in years

M

Value “length” is in months

D

Value “length” is in days

personalid

Person specific numbers or characters, e.g. number of passport / ID card

Format

CHAR(1..32)

Permitted Symbols

[0-9][A-Z][a-z][+-./()]

Payment specific: 

Payment type Comments

KLV, KLS

Mandatory in SE, FI, DK, NO

personstatus

Person address check result; details

Format

LIST 

List of codes: 

AddressCheck PAYONE Services

Code Signification

NONE

no verification of personal data carried out

PAB

first name & surname unknown

PHB

surname known

PKI

ambiguity in name and address

PNP

address cannot be checked, e.g. fake name used

PNZ

cannot be delivered (any longer)

PPB

the person can be confirmed for this address.

PPF

postal address details incorrect

PPV

person deceased

PUG

postal address details correct but building unknown

PUZ

person has moved, address not corrected

UKN

unknown return values are mapped to UKN

AddressCheck Boniversum Services

mapped to Code Boniversum internal status Signification Signification (DE)

PPF

00

postal address details incorrect

Nicht identifiziert.

PPB

02

the person can be confirmed for this address.

Nicht identifiziert.

PHB

03

surname known

Haushalt identifiziert.

PAB

05

first name & surname unknown

Gebäude identifiziert.

PPV

06

person deceased

Person verstorben.

PFC

Meaning: Postfinance Card

PFF
PIN
PIV
portalid

Portal ID, defined by PAYONE

Format

NUMERIC(7)

POV

Meaning: Clearingsubtype for PAYONE Secure Invoice

PPE

Meaning: PayPal

productid

ID for the offer

Format

NUMERIC(1..7)

pr_recurring[n]

Unit gross price of the item (subsequent term) in smallest unit.

Format

NUMERIC(8) max. 999 999 99

Array

Array elements [n] starting with [1]; serially numbered; max [100]

pr_trail[n]

Unit gross price of the item (initial term) in smallest unit.

Format

NUMERIC(8) max. 999 999 99

Array

Array elements [n] starting with [1]; serially numbered; max [100]

pr[n]

Unit gross price of the item in smallest unit! e.g. cent

Format

NUMERIC(10) max. 19 999 999 99

Array elements [n] starting with [1]; serially numbered; max [400]

pseudocardpan

Pseudo primary account number for a credit card.

Format

NUMERIC(16..19)

This pseudo card pan is a token to a real cardpan, but it's not PCI DSS relevant. So therefore it can be handled and stored by the merchant system without any PCI DSS impact - however you have to complete a PCI DSS compliance in any case. 

This token is unique per merchant and cardpan/expiredate and can be used in any payment-request with credit cards to refer to an existing credit card in the PAYONE platform.

PYD
PYM

Meaning: Unzer - Monthly

PYS

Meaning: Unzer Ratenkauf

PYV
P24

Meaning: Przelewy24

R

rec
recurrence

Indicates recurring payments. Currently supported for PayPal and Credit Card payments.

Format

LIST

Value Comments

installment

a recurring payment, which has an a priori defined frequency, limit/threshold and end date

none

a non recurring payment, i.e. a single authorization which might be captures at once or later in one or multiple charges

oneclick

a form of payment on which the cardholder is authenticated only on the initial transaction. Follow-up transactions are authorized without active interaction of the cardholder

recurring

a recurring payment, which has an a priori defined frequency and limit/threshold

redirecturl

Redirect URL → zMerchant system has to redirect customer to this URL to complete payment

Format

CHAR(2..2000)

Payment specific:

Payment type Comment

Redirect payment

Merchant system has to redirect customer to this URL to complete payment

reference

Merchant reference number for the payment process (case insensitive)

Format

CHAR(1..20)

Permitted Symbols

[0-9][a-z][A-Z], .,-,_,/

Special limits / restrictions:
Payment type Format

GPY

CHAR(4..16)

PDT

_ is not allowed

Merchant Reference has to be unique per merchant (mid) and mode, i.e.: the same Reference can be used for Live / Test

Merchant Reference can not be the same for two different portals, i.e.: Portal X, Mode=Live and Portal Y, Mode=Live

reg 2015-847

According to the new regulation on the transfer of funds (Geldtransferverordnung) address data (name, street, zip, city) is mandatory for cross border bank transfers (EEA / EWR), e.g.: CH, SM, MC, PM, JE, GG. This is mandatory from 2017-11-19.

Please use request “updateuser” to update customers address data.

This means that the whole address for bank transfers needs to be provided.
reminderlevel

Set reminder status

Format

LIST 

Value Comment

1

1st dunning level

2

2nd dunning level

3

3rd dunning level

4

4th dunning level

5

Transfer to an encashment agency

A

Dunning procedure ended

S

Dunning procedure starts (again)

M

Dunning proposal list

I

Encashment proposal list

remindertime

Date of the next dunning level as Unixtimestamp (the next reminder will be sent on this date)

Format

Unixtimestamp

request

The type of request you would like to perform

Format

LIST 

s

salutation

The customer's salutation

Format

CHAR(1..10)

SAQ A

Please refer to PCI DSS Security Standards listed in SAQ A V3 on https://de.pcisecuritystandards.org

score

Indication for all consumerscoretypes

Format

LIST

Value Comments

G

"green", high degree of creditworthiness

Y

"yellow", average degree of creditworthiness

R

"red", low degree of creditworthiness

U

unknown / not available

Please keep in mind that each merchant may have a different need of safety.

The scorevalue is more detailed - but not for all services present.

sd[n]

Delivery date (YYYYMMDD)

Format

DATE(8), YYYYMMDD

Array

Array elements [n] starting with [1]; serially numbered; max [400]

secstatus

Response code of address check to return whether address has been corrected

Format

LIST

Value Status Comment

10

VALID

address correct

20

VALID

address could be corrected / has changed

30

INVALID

address could not be corrected

secscore

For consumerscoretype: IA, IB, IH, IF; Negative criteria if registered.

Format

LIST

sendreminder

Send reminder to customer yes / no

Format

LIST

Value Comments

yes

Sends the reminder for the current/ updated dunning level, or transfers the case to encashment when dunning level 5 is reached.

no

Simply sets the indicated dunning level.

sequencenumber

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)

Format

NUMERIC(1..3)

Permitted values
0..127

settleaccount

Carry out settlement of outstanding balances. The request is booked and the resulting balance is settled by means of a collection, e.g. a refund.

Format

LIST

Value Comment

yes

Settlement of outstanding balances is carried out.

no

Do not carry out settlement of outstanding balances, book request only.

auto

The system decides - depending on type of payment and balance - if a settlement of balances can be carried out or not. (default)

Payment specific: 

Payment type Comment

KLS, KLV

Value "no" is not valid for Klarna and will be rejected.

settleaccount response

Provides information about whether a settlement of balances has been carried out.

Format

LIST

Value Comment

yes

Settlement of outstanding balances has been carried out.

no

Settlement of outstanding balances has not been carried out.

settletime

Date for the next invoicing Unixtimestamp in the future.

Format

Unixtimestamp

settle_period_length

Length of the accounting period

Format

NUMERIC(1..3)

settle_period_unit

Time unit of the accounting period

Format

LIST

Value Comment

Y

Value “length” is in years

M

Value “length” is in months

D

Value “length” is in days

shipping_addressaddition

Specifies an additional address line for the delivery address of the customer, e.g. "7th floor", "c/o Maier".

Format

CHAR(1..50)

shipping_city

City of delivery address

Format

NUMERIC(1..3)

shipping_company

Company Name of the delivery address

Format

CHAR(2..50)

shipping_country

Specifies country of delivery address for the customer

Format

LIST

Permitted values

ISO 3166 2-letter-codes

Samples

DE
GB
US

Some countries require additional information in parameter shipping_state
shipping_firstname

First name of delivery address

Format

CHAR(1..50)

shipping_lastname

Surname of delivery address

Format

CHAR(1..50)

shipping_state

Specifies country of delivery address for the customer

Specifies state of country of delivery address for the customer

"shipping_state" is required for these countries: US, CA, CN, JP, MX, BR, AR, ID, TH, IN (if shipping_country is given) and must not be used in all other countries.

Format

LIST

Permitted values

ISO 3166-2 States (regions)  2-letter-codes

Samples US

AK
AL
AR

Samples CA

AB
BC

shipping_street

Street number and name of delivery address

Format

CHAR(2..50) 

shipping_zip

Postcode of delivery address

Format

CHAR(2..10)

Permitted values

[0-9][A-Z][a-z][_.-/ ]

shippingprovider

Shipping Provider

Format

LIST

Shipping Provider Comment

DHL

DHL, Germany

state

Specifies state / region of country for the customer.

"state" is required for these countries: US, CA, CN, JP, MX, BR, AR, ID, TH, IN and must not be used for all other countries.

Format

LIST

Permitted values

ISO 3166-2 States (regions)  2-letter-codes

Samples US

AK
AL
AR

Samples CA

AB
BC

storecarddata

Specifies whether a pseudocardnumber shall be generated for later use (e.g. payment request)

Format

LIST 

Value Comment

no

Card data is not stored

yes

Card data is stored, a pseudo card number is returned

street

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

Format

CHAR(1..50)

Payment specific: 

Payment Type Comment

KLV, KLS

Mandatory

PYV, PYM, PYS, PYD

Mandatory

ELV

Mandatory for direct debit (ELV) used with IBAN-countries CH, SM, MC, PM, JE, GG

According to the new regulation on the transfer of funds (Geldtransferverordnung) address data (name, street, zip, city) is mandatory for cross border bank transfers (EEA / EWR), e.g.: CH, SM, MC, PM, JE, GG. This is mandatory from 2017-11-19. This takes effect when “capture” is done.

streetname

Street name

Format

CHAR(1..50)

streetnumber

Street number

Format

CHAR(1..50)

subtype

Overview of "cardtype" in use with "clearingtype=cc"

Card type of credit card

Format

LIST 

Value Comment BIN-Range for automatic type detection

V

Visa

4

M

MasterCard

51-55,2221-2720

A

American Express

34, 37

D

Diners / Discover

300-305,3095,36,38,39

601, 64, 65

J

JCB

3528-3589

O

Maestro International

50, 56-58,602, 61, 620, 627, 63, 67

P

China Union Pay

62212600-62299800,624-626, 6282-6288

U

UATP / Airplus

1220, 1920 -> coming soon; not available yet

G

girocard

68 

Overview of "clearingsubtype" in use with "clearingtype=rec"

Only valid with “clearingtype=rec”. Used for PAYONE Secure Invoice.

Format

LIST 

Value Comment

POV

PAYONE secure purchase on invoice

Overview of "financingtype" in use with "clearingtype=fnc"
 

Used with "clearingtype=fnc" to identify Financing type

Format

LIST 

Value Comment Server-API Client-API Frontend

RPV

Ratepay Open Invoice

x

x

x

RPS

Ratepay Installments

x

x

RPP

Ratepay Prepayment

x

x

x

RPD

Ratepay Direct Debit

x

x

x

PYV

Unzer Invoice

x

x

PYS

Unzer Installment

x

x

PYM

Unzer Monthly

x

x

PYD

Unzer Direct Debit

x

x

PPI

PayPal Installment

x

x

KLV

Klarna Checkout Invoice

x

x

KLS

Klarna Checkout Installment

x

x

KIS

Klarna Payments "Slice it" (Installments)

x

KIV

Klarna Payments "Pay now" (Invoice)

x

KDD

Klarna Payments "Pay now" (Direct Debit)

x

KBT

Klarna Payments "Pay now" (Bank Transfer)

x

PIV

PAYONE Secured Invoice

x

PDD

PAYONE Secured Direct Debit

x

PIN

PAYONE Secured Installment

x

Overview of "onlinebanktransfertype" in use with "clearingtype=sb"

Format

LIST 

Value Comment Server-API Client-API Frontend

BCT

Bancontact

x

x

EPS

eps – online transfer (AT)

x

x

x

IDL

iDEAL (NL)

x

x

x

MBC

Multibanco

x

x

MYB

MyBank

x

x

P24

Przelewy24 (PL)

x

x

x

PFF

PostFinance E-Finance (CH)

x

x

x

PPI

PayPal Installment

x

x

x

PFC

PostFinance Card (CH)

x

x

x

PNT

SOFORT Überweisung

x

x

x

TRL

Trustly

x

x

VKP

Verkkopankki

x

x

Overview of "wallettype" in use with "clearingtype=wlt"
 

Used with "clearingtype=wlt" to identify wallet payment types

Format

LIST 

Value Comment Server-API Client-API Frontend

ALP

Alipay

x

x

x

AMZ

Amazon Payments

x

x

PDT

Giropay

x

x

x

PPE

PayPal

x

x

x

APL

Apple Pay

x

x

successurl

URL for "payment successful"

Format

CHAR(2..255)

Scheme

<scheme>://<host>/<path>
<scheme>://<host>/<path>?<query>


scheme-pattern: [a-zA-Z]{1}[a-zA-Z0-9]{1,9}

URL is required for any type of redirect payments, e.g.

- Bancontact, EPS, Giropay, iDEAL, Multibanco, PostFinance, Przelewy24, SOFORT, Trustly, ...
- PayPal, ...
- credit card with 3-D secure
Allowed schemes for URL:
- For Channel "Frontend" / "Client-API" only schemes "http" or "https" allowed.
- For Channel "Server-API" individual schemes like "app://app.domain.com" is allowed
URL can be
-either defined in PMI -> configuration -> portal
-> then this URL is used as default
(this requires channel "Frontend" to be avalibale)
- or it can be specified via API parameter
-> then this URL overrides the PMI-configuration.
Example
Valid for all channels (Server, Client, Frontend):
https://www.domain.com/success.html
https://www.domain.com/success.html?exit=success&txid=__txid__
https://www.domain.com/back.html?exit=back

Valid additionally for Server-API:
app://app.domain.com/success.html?exit=success&txid=__txid__
myscheme://myapp.domain.com/success.html?exit=success&txid=__txid__

Payment specific:

Payment type Comment

Redirect payment

For redirect payments (e.g. PayPal, Giropay, SOFORT, ...) an URL has to be provided.
It can be
- either defined in PMI -> configuration -> portal
-> then this URL is used as default
- or it can be specified via API parameter
-> then this URL overrides the PMI-configuration.

scorevalue

The scorevalue is a more detailed indication of credit worthiness of customers than the score (traffic light).

Please pay attention that the values and the interpretation are provider specific.

Format

NUMERIC(1..4), values and ranges see table below.

consumerscoretype Provider Range Remarks

IA, IB, IH, IF

Arvato Infoscore

Score: 100-990

  1. The higher the value, the higher the degree of creditworthiness
  2. Please refer to Decision matrix Arvato Infoscore Boni-Score/Informa-Score

CE

Boniversum VERITA

Score: 0-6000

  1. The higher the value, the lower the degree of creditworthiness
  2. Please refer to Decision matrix Boniversum VERITA score

SFS, SFM

SCHUFA B2B
 

Score: 100-600

The higher the value, the lower the degree of creditworthiness; values e.g. “100”, “204”, “202.3”

SFS

SCHUFA B2C

Score: 1-9999

The higher the value, the higher the degree of creditworthiness
secscore

For consumerscoretype: IA, IB, IH, IF; Negative criteria if registered.

Format

LIST

Negative criteria; details see code list: Consumer score Arvato Infoscore - secscore

T

targetwindow

Specifies target window for Frontend form.

Format

LIST 

Value Comment

window

default

opener

top

parent

blank

self

tel

Type “tel” can be used to display a simple, numeric phone keyboard on mobile devices.

telephonenumber

Phone number of customer

Format

CHAR(1..50)

Payment specific: 

Payment Type Comment

KLV, KLS

Parameter is mandatory for this payment type

title

Title of the customer

Format

CHAR(1..20)

Samples

Dr
Prof.
Dr.-Ing.

ti_recurring[n]

Title (subsequent term)

Format

CHAR(1..100)

Array

Array elements [n] starting with [1]; serially numbered; max [100]

ti_trail[n]

Title (initial term)

Format

CHAR(1..100)

Array

Array elements [n] starting with [1]; serially numbered; max [100]

transaction_param

Optional parameter for merchant information (per payment request)

Format

CHAR(1..50)

Permitted Symbols

[0-9][A-Z][a-z][.-_/]

- In case of Paypal this parameter is passed to Paypal as "PAYMENTREQUEST_n_CUSTOM" to appear as merchant customizable value in Paypal settlement files.
- Only used for reporting purpose on PMI-export “Export -> Payment events”.
- param is an individual parameter per payment process, which can be exported with PMI -> export -> payments
- transaction_param is an individual parameter per payment request which can be exported with PMI -> export -> payment events
transactiontype

Type of payment request

Format

LIST

Value Comment

RL

Direct debit return fee

MG

Dunning charge

VZ

Default interest

VD

Delivery charges

FD

Payment request (default for amount > 0)

GT

Credit (default for amount < 0)

RT

Returns

truncatedcardpan

Masked cardpan, i.e. 411111xxxxxx1111 (is returned if storecarddata=yes)

Format

CHAR(13..19)

The first six and the last four digits are visible - the rest ist masked.
This presentation is PCI DSS compliant and may be stored and logged.
txid

The txid specifies the payment process within the PAYONE platform

Format

NUMERIC(9..12)

type

Type of request:

getuser:
Can be used to retrieve debtor data. Must not be used together with “getusertoken”

Format

LIST

Request Value Comment

getuser

userdata

Returns user data of debtor (in JSON only)
 

HTTP Accept header in the API request has to be set to “Accept: application/json” to indicate that a JSON response should be sent.

getuser

usertoken

Get usertoken for further authorization/preauthorization

U

use_customerdata

Use account details from debtor's master data

Format

CHAR(1..50)

Value Comment

yes

Uses current account details from debtor's master data (default)
 

no

Uses the last known account details in the payment process

UsedInHash

The parameters with a "+" must be included in the calculation of the hash value to prevent changes by the customer.

userid

PAYONE User ID, defined by PAYONE

Format

NUMERIC(6..12)

"userid" can be used to refer to an existing customer record. "userid" must already exist and mode (test/live) must must match.

If "userid" is used then stored customer data are loaded automatically.
usertoken

PAYONE User token, defined by PAYONE

Format

CHAR(30)

Reference to debtor which can be used for authorization / preauthorization within 15 minutes from another merchant id.

V

vaccountname

ID/name of the merchant's billing account

Format

CHAR(1..20)

Permitted Symbols
[0-9, a-z, A-Z, .,-,_,/]
va[n]

VAT rate (% or bp)

Format

NUMERIC(4)

Array

Array elements [n] starting with [1]; serially numbered; max [400] 

- value <= 99 = per cent (e.g. 19 = 19%)
 
- value > 99 = basis points (e.g. 1900 = 19%)

Payment specific:

Payment Type Comment

KLS, KLV

Mandatory 

va_recurring[n]

VAT rate (% or bp) (subsequent term)

Format

NUMERIC(4)

Array

Array elements [n] starting with [1]; serially numbered; max [100] 

- value <= 99 = per cent (e.g. 19 = 19%)
 
- value > 99 = basis points (e.g. 1900 = 19%)
va_trail[n]

VAT rate (% or bp) (first term)

Format

NUMERIC(4)

Array

Array elements [n] starting with [1]; serially numbered; max [100] 

- value <= 99 = per cent (e.g. 19 = 19%)
 
- value > 99 = basis points (e.g. 1900 = 19%)
vaid

Billing account ID

Format

NUMERIC(1..8)

vatid

VAT identification number. Used for b2b transactions to indicate VAT number of customer.

Format

CHAR(1..50)

vor
vreference

Merchant's transaction reference number

Format

CHAR(1..20)

Special limits / restrictions:
Payment Type Format

GPY

CHAR(4..16)

vxid

Reference number on the virtual account

Format

NUMERIC(9..12)

W

wallettype

Used with "clearingtype=wlt" to identify wallet payment types

Format

LIST 

Value Comment Server-API Client-API Channel Frontend

ALP

Alipay

x

x

x

AMZ

Amazon Payments

x

x

PDT

Giropay

x

x

x

PPE

PayPal

x

x

x

APL

Apple Pay

x

x

WCP

Meaning: WeChat Pay

workorderid

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.

Format

CHAR(1..50)

X

xid

3-D Secure transaction ID (if the request "3dscheck" was used previous transactions), i.e.:

  1. value for "xid" is returned by request 3dscheck (optional request)
  2. and then has to be used for request authorization, preauthorization or createaccess in request data

Format

CHAR(1..60)

Y

Z

zip

Postcode

Format

CHAR(2..10)

Permitted Symbols

[0-9][A-Z][a-z][_.-/ ]

Payment specific: 

Payment  Type Comment

KLV, KLS

Mandatory

PYV, PYM, PYS, PYD

Mandatory

ELV

Mandatory for direct debit (ELV) used with IBAN-countries CH, SM, MC, PM, JE, GG

According to the new regulation on the transfer of funds (Geldtransferverordnung) address data (name, street, zip, city) is mandatory for cross border bank transfers (EEA / EWR), e.g.: CH, SM, MC, PM, JE, GG. This is mandatory from 2017-11-19. This takes effect when “capture” is done.