API requests:

The PAYONE Secured Invoice payment method consist of the following API requests:

	Request	Comments
1.)	Preauthorization/Authorization	request=preauthorization/authorization
2.)	Capture	request=capture
3.)	Refund	request=refund

Because the authorization request will immediatly activate the claim (start of the due date), we recommend to use the preauthorization and capture request for retail business with delivery time.

Preauthorization/Authorization

Additional parameters for use with "preauthorization" or “authorization”.

Request

Parameter

Required

Format

Comments

clearingtype

+

LIST

Set to "fnc" = Financing

financingtype

+

LIST

Set to "PIV" = PAYONE Secured Invoice

reference

+

CHAR(1..20)

Merchant reference number for the payment process.

amount

+

NUMERIC(1..10)

Specifies the total gross amount of a payment transaction.

currency

+

LIST

Specifies currency for this transaction.

Billing address

businessrelation

+

LIST

Value specifies business relation between merchant and customer.

Value	Comment
b2c	Indicates business to private customer
b2b	indicates business to business customer (company)

company

o

CHAR(2..50)

Organizational name of the consumer (in case of a B2B transaction type)

firstname

+

CHAR(1..50)

First name of customer.

lastname

+

CHAR(2..50)

Last name of customer.

street

+

CHAR(1..50)

Street number and name.

zip

+

CHAR(2..10)

Postcode

city

+

CHAR(2..10)

City of customer.

country

+

LIST

Specifies country of address for the customer.

Consumer

email

+

CHAR(5..254)

Email-address of customer.

telephonenumber

+

CHAR(1..30)

Phone number of customer.

birthday

+

DATE(8), YYYYMMDD

Date of birth of customer.

addPayData[device_token]

+

AN..255

Device fingerprinting token.

ip

+

CHAR(1..39)

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

vatid

o

CHAR(1..50)

VAT identification number. Used for b2b transactions to indicate VAT number of customer. Recommended for optimal acceptance rate.

Shopping cart

de[n]

+

NUMERIC(10)

Description of this item.

no[n]

+

NUMERIC(6)

Quantity of this item.

pr[n]

+

NUMERIC(10)

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

id[n]

+

CHAR(1..32)

Product number, SKU, etc. of this item.

it[n]

+

LIST

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

Value	Comments
goods	Goods
shipment	Shipping charges
handling	Handling fee
voucher	Voucher / discount

Example

https://api.pay1.de/post-gateway/
add_paydata[device_token]=abcdefghijklmn123456789 (your customer device token)
aid=12345 (your aid)
amount=1100
birthday=19820324
businessrelation=b2c
city=Musterstadt
clearingtype=fnc
country=DE
currency=EUR
de[1]=Testartikel 1
de[2]=Transport
email=max@mustermann.de
encoding=UTF-8
financingtype=PIV
firstname=Max
id[1]=1001001
id[2]=1001002
ip=123.123.123.123
it[1]=goods
it[2]=shipment
key=abcdefghijklmn123456789 (your key)
lastname=Mustermann
mid=54321 (your mid)
mode=live
no[1]=1
no[2]=1
portalid=12345123 (your portalid)
pr[1]=1000
pr[2]=100
reference=jv-1668434776
request=preauthorization
street=Musterweg 1
telephonenumber=491731234567
va[1]=19
va[2]=19
zip=12345

Response

Example

status=APPROVED
txid=753359579
userid=483104612

Capture

Additional parameters for use with "capture".

Request

Common Parameter

Required

Format

Comments

txid

+

NUMERIC(9..12)

The txid specifies the payment process within the PAYONE platform.

amount

+

NUMERIC(1..10)

Specifies the total gross amount of a payment transaction.

Note: With previous preauthorization an “amount = 0” can be used to cancel a reserved amount of money (with a preauthorization) at external Payment Service Provider.

currency

+

LIST

Specifies currency for this transaction.

sequencenumber

+

NUMERIC(1..3)

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)

capturemode

-

LIST

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

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

AddPayData[cancellation_reason]

-

LIST

Note: Mandatory for Capture=0 and capturemode=completed if the capture amount is lower than the reservation amount.

Value	Comment
consumer_request	The consumer requested a cancellation of the Order
undeliverable	The merchant cannot fulfill the Order
duplicate	The Order was created twice accidentally
fraudulent	Consumer turned out to be a fraudster

settleaccount

-

LIST

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.

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)

Shopping cart

de[n]

-

NUMERIC(10)

Description of this item.

no[n]

-

NUMERIC(6)

Quantity of this item.

pr[n]

-

NUMERIC(10)

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

id[n]

-

CHAR(1..32)

Product number, SKU, etc. of this item.

it[n]

-

LIST

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

Value	Comments
goods	Goods
shipment	Shipping charges
handling	Handling fee
voucher	Voucher / discount

Example

https://api.pay1.de/post-gateway/
aid=12345 (your aid)
amount=1100
currency=EUR
de[1]=Testartikel 1
de[2]=Transport
encoding=UTF-8
id[1]=1001001
id[2]=1001002
it[1]=goods
it[2]=shipment
key=abcdefghijklmn123456789 (your key)
mid=54321 (your mid)
mode=live
no[1]=1
no[2]=1
portalid=12345123 (your portalid)
pr[1]=1000
pr[2]=100
request=capture
sequencenumber=1
settleaccount=auto
txid=753359579
va[1]=19
va[2]=19

Response

Example

status=APPROVED
txid=753359579
settleaccount=yes

Refund

Additional parameters for use with "Refund”.

Request

Parameter	Required	Format	Comment
txid	+	NUMERIC(9..12)	The txid specifies the payment process within the PAYONE platform.
amount	+	NUMERIC(1..10)	Specifies the total gross amount of a payment transaction. Note: Amount must be negativ.
currency	+	LIST	Specifies currency for this transaction.
sequencenumber	+	NUMERIC(1..3)	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)
AddPayData[reason]	-	AN..255	Reason of the refund (e.g. communicated to the consumer)
Shopping cart
de[n]	-	NUMERIC(10)	Description of this item.
no[n]	-	NUMERIC(6)	Quantity of this item.
pr[n]	-	NUMERIC(10)	Unit gross price of the item in smallest unit! e.g. cent. Note: Amount must be negativ.
id[n]	-	CHAR(1..32)	Product number, SKU, etc. of this item.

Example

https://api.pay1.de/post-gateway/
aid=12345 (your aid)
amount=-1100
currency=EUR
encoding=UTF-8
key=abcdefghijklmn123456789 (your key)
mid=54321 (your mid)
mode=live
portalid=12345123 (your portalid)
request=refund
sequencenumber=2
txid=753359579

Response

Example

status=APPROVED
txid=753359579

Sequence diagram:

PAYONE Secured Invoice overview with Preauthorization, Capture, Reversal and Refund.

Page tree

API requests:

Request

Example

Response

Example

Capture

Request

Example

Response

Example

Refund

Request

Example

Response

Example

Sequence diagram:

Social Media

PAYONE

Help

Intranet Tools

Page tree

PAYONE - Secured Invoice

API requests:

Request

Example

Response

Example

Capture

Request

Example

Response

Example

Refund

Request

Example

Response

Example

Sequence diagram: