API requests:

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

	Request	Comments
1.)	Installment Options	request=genericpayment
2.)	Preauthorization/Authorization	request=preauthorization/authorization
3.)	Capture	request=capture
4.)	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.

Genericpayment – installment_options

Genericpayment request for retrieving the installment options from the service provider.

Request

Common Parameter	Required	Format	Comments
add_paydata[action]	+	AN..255	Set to "installment_options"
add_paydata[businessRelation]	+	AN..255	Set to "b2c"
clearingtype	+	LIST	Set to "fnc" = Financing
financingtype	+	LIST	Set to "PIN" = PAYONE Secured Installment
amount	+	NUMERIC(1..10)	Specifies the total gross amount of a payment transaction.
currency	+	LIST	Specifies currency for this transaction.

Example

https://api.pay1.de/post-gateway/
add_paydata[action]=installment_options
add_paydata[businessRelation]=b2c
aid=12345 (your aid)
amount=20000
clearingtype=fnc
currency=EUR
encoding=UTF-8
financingtype=PIN  
key=abcdefghijklmn123456789 (your key)
mid=54321 (your key)
mode=live  
portalid=12345123 (your portalid)
request=genericpayment

Response

Parameter	Required	Format	Comment
workorderid	+	CHAR(1..50)	The workorderid is used for the genericpayment request.
add_paydata[installment_option_id]	+	AN..255	Installment Option Identifier.
add_paydata[amount_value]	+	AN..255	Amount to calculate installment options.
add_paydata[amount_currency]	+	AN..255	Currency of the amount.
add_paydata[total_amount_value]	+	AN..255	Total rate amount.
add_paydata[total_amount_currency]	+	AN..255	Currency of the amount.
add_paydata[first_rate_date]	+	AN..255	Due date of first rate.
add_paydata[last_rate_amount_value]	+	AN..255	Amount of money, represented as a decimal value.
add_paydata[last_rate_amount_currency]	+	AN..255	Currency of the amount.
add_paydata[nominal_interest_rate]	+	AN..255	Nominal interest amount.
add_paydata[effective_interest_rate]	+	AN..255	Effective interest amount.
add_paydata[number_of_payments]	+	AN..255	The number of monthly payments for this installment.
add_paydata[monthly_amount_value]	+	AN..255	Monthly rate amount.
add_paydata[monthly_amount_currency]	+	AN..255	Currency of the amount.
add_paydata[link_credit_information_type]	+	AN..255	Link with credit information.
add_paydata[link_credit_information_href]	+	AN..255	URL of link.
add_paydata[link_credit_information_type]	+	AN..255	Content type of linked data.

Example

status=OK
workorderid=ABCDEFGHIJKLMNOP123
add_paydata[total_amount_currency_0]=EUR
add_paydata[total_amount_currency_1]=EUR
add_paydata[first_rate_date_0]=2022-11-28
add_paydata[link_credit_information_type_0]=application/pdf
add_paydata[nominal_interest_rate_0]=999
add_paydata[nominal_interest_rate_1]=1199
add_paydata[amount_currency]=EUR
add_paydata[nominal_interest_rate_2]=1499
add_paydata[last_rate_amount_value_0]=17033
add_paydata[first_rate_date_1]=2022-11-28
add_paydata[last_rate_amount_value_2]=4521
add_paydata[last_rate_amount_value_1]=8670
add_paydata[first_rate_date_2]=2022-11-28
add_paydata[total_amount_currency_2]=EUR
add_paydata[amount_value]=50000
add_paydata[effective_interest_rate_2]=1510
add_paydata[number_of_payments_1]=6
add_paydata[number_of_payments_0]=3
add_paydata[total_amount_value_1]=52035
add_paydata[total_amount_value_0]=51099
add_paydata[number_of_payments_2]=12
add_paydata[total_amount_value_2]=54351
add_paydata[installment_option_id_2]=IOP_bbc08f0a1b2a41268048b41e2efb31a4
add_paydata[installment_option_id_1]=IOP_78094545483947868a68a2fb01ac3015
add_paydata[link_credit_information_type_2]=application/pdf
add_paydata[installment_option_id_0]=IOP_06f07670e25645d49de8ebf62a7030da
add_paydata[link_credit_information_type_1]=application/pdf
add_paydata[last_rate_amount_currency_0]=EUR
add_paydata[last_rate_amount_currency_1]=EUR
add_paydata[monthly_amount_value_2]=4530
add_paydata[monthly_amount_value_1]=8673
add_paydata[last_rate_amount_currency_2]=EUR
add_paydata[monthly_amount_value_0]=17033
add_paydata[monthly_amount_currency_1]=EUR
add_paydata[monthly_amount_currency_2]=EUR
add_paydata[monthly_amount_currency_0]=EUR
add_paydata[effective_interest_rate_0]=1013
add_paydata[link_credit_information_href_1]=https://api.playground.payla.io/v1/installment_options/IOP_78094545483947868a68a2fb01ac3015/credit_information?amount=500.00&currency=EUR&shop_id=SHO_b2cf317247314c08bce8759c3672e991
add_paydata[link_credit_information_href_0]=https://api.playground.payla.io/v1/installment_options/IOP_06f07670e25645d49de8ebf62a7030da/credit_information?amount=500.00&currency=EUR&shop_id=SHO_b2cf317247314c08bce8759c3672e991
add_paydata[effective_interest_rate_1]=1212
add_paydata[link_credit_information_href_2]=https://api.playground.payla.io/v1/installment_options/IOP_bbc08f0a1b2a41268048b41e2efb31a4/credit_information?amount=500.00&currency=EUR&shop_id=SHO_b2cf317247314c08bce8759c3672e991

Preauthorization/Authorization

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

Request

Parameter

Required

Format

Comments

workorderid

+

CHAR(1..50)

Reference ID to the generic Request.

add_paydata[installment_option_id]

+

AN..255

Installment Option Identifier.

clearingtype

+

LIST

Set to "fnc" = Financing

financingtype

+

LIST

Set to "PIN" = PAYONE Secured Installment

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)

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.

bankaccountholder

+

CHAR(1..50)

Account holder

iban

+

CHAR(10..34)

IBAN to be used for payment or to be checked

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)
add_paydata[installment_option_id]=IOP_78094545483947868a68a2fb01ac3015
aid=12345 (your aid)
amount=20000
bankaccountholder=Max Mustermann
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=PIN
firstname=Max
iban=DE12345678910111213141
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
workorderid=PP2ACV24K99WDPTB
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=20000
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]=10000
pr[2]=10000
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=-20000
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 Installment overview with Installment options, Preauthorization, Capture, Reversal and Refund.

Page tree

API requests:

Request

Example

Response

Example

Preauthorization/Authorization

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 Installment

API requests:

Request

Example

Response

Example

Preauthorization/Authorization

Request

Example

Response

Example

Capture

Request

Example

Response

Example

Refund

Request

Example

Response

Example

Sequence diagram: