Skip to end of metadata
Go to start of metadata

Notes

Availability by Country/Currency

Payment Type

Countries

Currency

B2C

B2B

Invoice

Germany

Austria

Switzerland

EUR

yes

yes

Functional Limitations and Additional Information

Right now there are certain limitations for PAYONE Secure Invoice that need to be taken into account during the implementation. All information that is relevant for the merchant is summarized here.

  • Currently no support for increasing receivables with a debit request.
  • Request preauthorization is only valid for 28 days.
  • Processing only possible for EUR currency for Switzerland.
  • Currently no support for refunds after start of encashment.
  • To set up your merchant account for secure invoice, we need to configure a new dedicated payment portal for this payment method. Please make sure, that you send the dedicated portalid and key within your requests for clearingtype REC with subtype POV.
  • Shipping address and invoice address must be same for a payment guarantee to be granted.

Shop-Plugins

In some shop systems, there is no dedicated switch for B2B/B2C transactions. To solve this, a transaction is flagged as B2B when the parameter company is filled. There is no further check, if the company name is correct.

Request "preauthorization"

During the preauthorization and authorization a risk check for the customer is performed. Depending on the result the customer qualifies or disqualifies from using this payment method. When the risk of payment default is deemed too high the transaction can’t be insured and the customer is denied, yielding an error message and the status “ERROR”.

Generally, the more customer data you send, the better the risk check can decide to give an insurance or not. Nonetheless, there following table contains flags, if a parameter is optional or not.

If the preauthorization/authorization is successful the response will contain the status “APPROVED”.

Using the Preauthorization request does NOT finalize the claim. In order to start the dunning process the transactions need to be captured first. See: capture

Please bear in mind, that a preauthorization is valid for 28 days. You need to make sure, that you capture this preauthorization in this period. Otherwise, if you know that you won’t capture the amount, please send a cancel (capture with amount=0), to free the reserved guarantee.

Request "capture"

If the transaction was initialized with a preauthorization request, you have to capture the transaction after fulfillment. The dunning process will not be started before capturing the transaction.

Request "authorization"

The authorization request simply combines both the prauthorization and the capture steps.

Remarks to API parameters

Clearingtype / Clearingsubtype

ParameterRequiredValueComments

clearingtype

+


Format

LIST
valueCommentDescription / Comments
elvDebit 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.

ccCredit card
recInvoice
codCash on deliverynot allowed for vauthorization, createaccess, updateaccess
vorPrepaymentnot allowed for vauthorization, createaccess, updateaccess
sbOnline Bank Transfernot allowed for vauthorization, createaccess, updateaccess
wlte-walletnot allowed for vauthorization, createaccess, updateaccess
fncFinancingnot allowed for vauthorization, createaccess, updateaccess
cshCash or Hybrid Paymentsnot allowed for vauthorization, createaccess, updateaccess

fixed value "rec"
clearingsubtype+

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

Format

LIST
ValueComment
POV

PAYONE secure purchase on invoice

fixed value "POV"
companyo

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

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

Format

CHAR(2..50)

If the company name is set the transaction will be considered B2B. There is no further check, if the company name is
correct.
businessrelation-

Value specifies business relation between merchant and customer

Format

LIST
valueComment

b2c

Indicates business to private customer

b2b

indicates business to business customer (company)

Not mandatory by now, but strongly recommended to be used.

Please use parameter "businessrelation" to specify whether the customer is a person or a company.

This identifier will replace company as b2b/b2c identifier in a future version.

birthdayo

Date of birth of customer


Format

DATE(8), YYYYMMDD

Samples

20190101
19991231

Mandatory for b2c transactions.
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:

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

Mandatory for POV.
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


goodsGoods
shipment

Shipping charges


handling

Handling fee

  • Not to be used with PDT
voucherVoucher / discount
  • Not to be used with PDT

Mandatory for POV.
id[n]+

Product number, SKU, etc. of this item

Format

CHAR(1..32)

Array

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

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

Mandatory for POV.
pr[n]+

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

Format

NUMERIC(10) max. 19 999 999 99

Array

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

Mandatory for POV.
no[n]+

Quantity of this item

Format

NUMERIC(6)

Array

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

Mandatory for POV.
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

Mandatory for POV.
va[n]+

VAT rate (% or bp)

Format

NUMERIC(4)

Array

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

Mandatory for POV.

Special Test Cases

See: Secure purchase on invoice

Sequence Diagram


  • No labels