SA - Initiating a payment process in the billing module (vauthorization)

Introduction

For booking a request on a billing account in the billing module, the PAYONE Platform can automatically initiate a settlement to settle the balance of the account.

The number of articles per settlement period is limited top 400 articles. Please shorten the settlement period if necessary.

This option is available in the "Shop" and "Access" option.

Request "vauthorization"

Common Parameter

Required

Format

Short explanation

aid

+

Sub-Account ID, defined by PAYONE

Format

NUMERIC(5..6)

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

vreference

+

Merchant's transaction reference number

Format

CHAR(1..20)

Permitted Symbols

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

vaccountname

+

ID/name of the merchant's billing account

Format

CHAR(1..20)

Permitted Symbols

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

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

currency

+

Specifies currency for this transaction

Format

LIST

Permitted values

 ISO 4217 (currencies) 3-letter-codes

Samples

EUR

USD

GBP

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

settletime

-

Date for the next invoicing Unixtimestamp in the future.

Format

Unixtimestamp

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

param

-

Individual parameter (per payment process)

Format

CHAR(1..255)

Parameter ( Invoicing )

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

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][()[]{} +-_#/:]

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]

no[n]

+

Quantity of this item

Format

NUMERIC(6)

Array

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

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

va[n]

-

VAT rate (% or bp)

Format

NUMERIC(4)

Array

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

sd[n]

-

Delivery date (YYYYMMDD)

Format

DATE(8), YYYYMMDD

Array

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

ed[n]

-

Delivery period end date (YYYYMMDD)

Format

DATE(8), YYYYMMDD

Array

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

Parameter ( personal data )

customerid

-

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

Format

CHAR(1..20)

Permitted Symbols

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

userid

-

PAYONE User ID, defined by PAYONE

Format

NUMERIC(6..12)

salutation

-

The customer's salutation

Format

CHAR(1..10)

title

-

Title of the customer

Format

CHAR(1..20)

Samples

Dr

Prof.

Dr.-Ing.

firstname

o

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

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

Format

CHAR(1..50)

lastname

+

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

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

Format

CHAR(2..50)

company

-

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)

street

-

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

Format

CHAR(1..50)

addressaddition

-

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

Format

CHAR(1..50)

Samples

7th floor

c/o Maier

zip

-

Postcode

Format

CHAR(2..10)

Permitted Symbols

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

city

-

City of customer

Format

CHAR(2..50)

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"

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.

telephonenumber

-

Phone number of customer

Format

CHAR(1..30)

birthday

-

Date of birth of customer

Format

DATE(8), YYYYMMDD

Samples

20190101

19991231

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 values

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

vatid

-

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

Format

CHAR(1..50)

ip

-

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

Format

CHAR(1..39)

Parameter ( debit payment )

iban

o

IBAN to be used for payment or to be checked

Format

CHAR(10..34)

Permitted Symbols

[0-9][A-Z]

bic

o

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.

bankcountry

o

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

bankaccount

o

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)

bankcode

o

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.

Format

NUMERIC(8)

bankaccountholder

-

Account holder

Format

CHAR(1..50)

mandate_identification

o

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

Parameter ( credit card )

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

value	Comment	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
C	~~Discover~~
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.

cardexpiredate

+

Credit card expiry date YYMM

Format

NUMERIC(4), YYMM

cardcvc2

o

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.

cardissuenumber

-

Card issue number (only Maestro UK cards)

Format

NUMERIC(1..2)

cardholder

-

Cardholder of credit card.

Format

CHAR(1..50)

Parameter ( credit card with pseudo card number )

pseudocardpan

+

Pseudo primary account number for a credit card.

Format

NUMERIC(16..19)

Response "vauthorization"
Common Parameter	Required	Format	Short explanation
status	+	Default	APPROVED / ERROR
Parameter (APPROVED)
vxid	+		Reference number on the virtual account Format NUMERIC(9..12)
vaid	+		Billing account ID Format NUMERIC(1..8)
userid	+		PAYONE User ID, defined by PAYONE Format NUMERIC(6..12)
Parameter (ERROR)
errorcode	+		In case of error the PAYONE Platform returns an error code for your internal usage. Format NUMERIC(1..6)
errormessage	+		In case of error the PAYONE Platform returns an error message for your internal usage. Format CHAR(1..1024)
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)

Page tree

Introduction

Request "vauthorization"

Common Parameter

Parameter ( Invoicing )

Parameter ( personal data )

Parameter ( debit payment )

Parameter ( credit card )

Parameter ( credit card with pseudo card number )

Response "vauthorization"

Common Parameter

Parameter (APPROVED)

Parameter (ERROR)

Content

Social Media

PAYONE

Help

Intranet Tools