- Created by PAYONE Writer, last modified on 2023-11-22
API requests:
The PAYONE Secured Direct Debit 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 "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.
| ||||||||||
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 | |||||||||||||
+ | 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.
|
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 | 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.
| ||||||||||
AddPayData[cancellation_reason] | - | LIST | Note: Mandatory for Capture=0 and capturemode=completed if the capture amount is lower than the reservation amount.
| ||||||||||
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.
| ||||||||||
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.
|
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 Direct Debit overview with Preauthorization, Capture, Reversal and Refund.
- No labels