- Created by PAYONE Writer, last modified on 2023-06-30
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.
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.
| ||||||||||
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. | ||||||||||
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=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.
| ||||||||||
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=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.
- No labels