API requests:

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


RequestComments

1.)

Preauthorization/Authorizationrequest=preauthorization/authorization
2.)Capturerequest=capture
3.)Refundrequest=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+LISTSet to "fnc" = Financing
financingtype+LIST

Set to "PDD" = PAYONE Secured Direct Debit

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.

ValueComment

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+LISTSpecifies 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..255Device 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.

ValueComments
goodsGoods
shipment

Shipping charges

handling

Handling fee

voucherVoucher / discount

Example

https://api.pay1.de/post-gateway/
add_paydata[device_token]=abcdefghijklmn123456789 (your customer device token)
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=PDD
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
zip=12345

Response 

Example 

status=APPROVED
txid=753359579
userid=483104612 

Capture

Additional parameters for use with "capture".

Request 

Common Parameter

RequiredFormat

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.

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

ValueComment
consumer_requestThe consumer requested a cancellation of the Order
undeliverableThe merchant cannot fulfill the Order
duplicateThe Order was created twice accidentally
fraudulentConsumer 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.
ValueComment
yesSettlement of outstanding balances is carried out.
noDo not carry out settlement of outstanding balances, book request only.
autoThe 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.

ValueComments
goodsGoods
shipment

Shipping charges

handling

Handling fee

voucherVoucher / 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+LISTSpecifies 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..255Reason 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 Direct Debit overview with Preauthorization, Capture, Reversal and Refund.

  • No labels