The PAYONE platform provides an asynchronous way of notifying your system of changes to a transaction. We call these notifications "TransactionStatus".
As you can see, our platform informs you of every successful action with a TransactionStatus notification.
You can configure the TransactionStatus Endpoint of your system in your payment portal configuration.
Many of today's payment methods use redirects to send customers to their site for login and finalization of the checkout. After completing the payment on the third-party site, the customer is redirected to a URL you can specify via the successurl parameter. However, fraudsters could just guess the successurl and open the URL without a successful payment.
The TransactionStatus system can help prevent this kind of fraud by sending a TransactionStatus notification before redirecting the customer to the successurl.
Note the "appointed" message prior to the redirect.
Some payment methods (like SEPA Direct Debit or PayPal) offer chargeback processes, where customers can trigger reverse cashflow after an allegedly fraudulent transaction. This mechanism can of course be used to obtain goods and then charge back the money by fraudsters.
Our TransactionStatus notification system can send notifications in case such a chargeback is triggered, allowing you to keep up with any action that's happening to a past transaction.
---end
|
---end
---end
your endpoint will have to reply synchronously with either TSOK or SSOK (just 4 characters, no html)
---end
|
---end
---end
According to the configuration of your payment portal you will receive the data and the status for each payment process via the URL you have submitted. The data transfer is based on simple HTTP-POST request (key/value pairs).
The TransactionStatus is sent from the following IP addresses: 185.60.20.0/24 (i.e. 185.60.20.1 to 185.60.20.254). Please configure your firewall to allow incoming packets from these IP addresses.
key required
|
Format AN..32
Payment portal key as MD5 value (The key hash values is currently given as MD5. This currently still remains with MD5 and is subject to change in future to SHA2-384.)
|
||||||||||||||||
txaction required
|
"appointed", "capture", "paid", "underpaid", "cancelation", "refund", "debit", "reminder", (See explanation below) |
||||||||||||||||
transaction_status optional
|
“completed”, “pending”
|
||||||||||||||||
notify_version optional
|
---end |
||||||||||||||||
mode required
|
---end |
||||||||||||||||
portalid required
|
Format NUMERIC..7
Payment portal ID
|
||||||||||||||||
aid required
|
Format NUMERIC..6
Sub account ID
|
||||||||||||||||
clearingtype required
|
Format AN..32
---end |
||||||||||||||||
txtime required
|
Format NUMERIC..11
Initiating payment process (Unix timestamp)
|
||||||||||||||||
currency required
|
Format LIST
Currency (ISO 4217)
|
||||||||||||||||
userid required
|
Format NUMERIC..12
Debtor ID (PAYONE)
|
||||||||||||||||
customerid optional
|
Format AN1..20
Merchant's customer ID
|
||||||||||||||||
param optional
|
Format AN..255
Individual parameter that was, where applicable, submitted while payment was initiated
|
---end
firstname optional
|
Format AN..50
First name (optional if company is used) |
lastname required
|
Format AN..50
Surname |
company optional
|
Format AN..50
Company name |
street optional
|
Format AN..50
Street number and name |
zip optional
|
Format AN..10
Postcode |
city optional
|
Format AN..50
City name |
country required
|
Format LIST
Country (ISO 3166) |
---end
shipping_firstname optional
|
Format AN..50
First name (optional if company is used) |
shipping_lastname optional
|
Format AN..50
Surname (optional if company is used) |
shipping_company optional
|
Format AN..50
Company |
shipping_street optional
|
Format AN..50
Street number and name |
shipping_zip optional
|
Format AN..10
Postcode |
shipping_city optional
|
Format AN..50
City |
shipping_country optional
|
Format LIST
Country (ISO 3166) |
email optional
|
Format AN..254
Email address |
shipping_street optional
|
Format AN..50
Street number and name |
---end
txid required
|
Format NUMERIC..12
Payment process ID (PAYONE) |
reference required
|
Format AN..20
Merchant reference number for the payment process |
sequencenumber required
|
Format NUMERIC..2
Sequence number at the time of the event for this payment process (0..n) |
price required
|
Format NUMERIC..10,2
Payment request (in largest currency unit! e.g. Euro) |
receivable optional
|
Format NUMERIC..10,2
Total payment request (in largest currency unit! e.g. Euro); not set for encashment reminder status information without paid amount |
balance optional
|
Format NUMERIC..10,2
Balance of transaction account (in largest currency unit! e.g. Euro) ; not set for encashment reminder status information without paid amount Negative amount: positive balance Positive amount: payment request |
failedcause optional
|
Format LIST
Reason for return debit note or incorrect collection (see Reasons for return debit notes (failedcause)) |
errorcode optional
|
Format NUMERIC..4
Errorcode in case of txaction=”failed” |
reasoncode optional
|
Format AN..10
Reasoncode in case of transaction_status=”pending”. Further details for transactionhandling see payment addon documentation. Sent only with “notify_version=7.6” |
productid required
|
Format NUMERIC..7
ID for the offer |
accessid required
|
Format NUMERIC 3..12
Access ID |
expiretime optional
|
Format NUMERIC..12
Unix Timestamp when access expires |
---end
bankcountry optional
|
Format LIST
Account type/ country |
bankaccount optional
|
Format AN..26
Account number (masked) |
bankcode optional
|
Format AN..11
Sort code |
bankaccountholder optional
|
Format AN..35
Account holder |
---end
iban optional
|
Format AN..35
International Bank Account Number (masked) |
bic optional
|
Format AN..11
Bank Identifier Code |
mandate_identification optional
|
Format AN..35
Used mandate_identification |
creditor_identifier optional
|
Format AN..35
Merchant’s creditor identifier |
clearing_date optional
|
Format NUMERIC..8
clearing date (format YYYYMMDD) |
clearing_amount optional
|
Format NUMERIC..10
Payment request (in smallest currency unit! e.g. cent) |
cardpan required
|
Format NUMERIC..19
Card number |
||||||||||||||||
cardtype required
|
Format LIST
---end Card type |
||||||||||||||||
cardexpiredate required
|
Format NUMERIC..4
Expiry date YYMM |
||||||||||||||||
cardholder optional
|
Format AN..35
Name of cardholder |
||||||||||||||||
cardholder_info optional
|
Format AN..128
Message provided by the Issuer in regards to 3DS processing. It provides valuable opportunity for the Issuers to inform the Cardholders why their payment can not proceed, and guide them to the necessary corrective action. Currently, it is optional for Merchants to display this text to Cardholders in EMV 3DS 2.1, but becomes mandatory in EMV 3DS 2.2. It is always optional for Issuers to use it, so the value might be omitted. |
---end
provider_payerid required
|
Format AN..13
Unique PayPal Customer Account identification number. |
customer_bankaccountholder optional
|
Format AN..35
Customers bank account holder |
customer_iban optional
|
Format AN..35
Customers IBAN |
customer_bic optional
|
Format AN..11
Customers BIC |
---end
clearing_bankaccountholder optional
|
Format AN..35
Recipient bank account holder |
clearing_bankcountry optional
|
Format LIST
Recipient account type/ country (e.g. DE, AT, etc.) |
clearing_bankaccount optional
|
Format AN..26
Recipient bank account |
clearing_bankcode optional
|
Format AN..11
Recipient sort code |
clearing_bankiban optional
|
Format AN..35
Recipient IBAN |
clearing_bankbic optional
|
Format AN..11
Recipient BIC |
clearing_bankcity optional
|
Format AN..50
Recipient city or bank |
clearing_bankname optional
|
Format AN..50
Recipient bank name |
clearing_legalnote optional
|
Format AN..500
Note to claim assignment |
clearing_duedate optional
|
Format NUMERIC..8
Due date of payment (format YYYYMMDD) |
clearing_reference optional
|
Format AN..50
Reference |
clearing_instructionnote optional
|
Format AN..200
Note to payment handling |
reminderlevel required
|
Format LIST
---end Customer's reminder status |
||||||||||||||||
encashment_statuscode optional
|
Format AN..20
Internal status code of the encashment agency, if provided by the encashment agency. |
||||||||||||||||
encashment_statuslongtext optional
|
Format AN..255
Free text: if the encashment agency has reported a long text (detailed information) on the status |
---end
txid
required
|
Format NUMERIC(9..12)
Payment process ID (PAYONE) |
reference required
|
Format AN..20
Merchant reference number for the payment process |
sequencenumber required
|
Format NUMERIC..2
Sequence number at the time of the event for this payment process (0..n) |
invoiceid required
|
Format AN..20
Merchant's invoice number |
invoice_grossamount required
|
Format NUMERIC..10,2
Gross invoice amount |
invoice_date required
|
Format NUMERIC..8
Invoice date (format YYYYMMDD) |
invoice_deliverydate optional
|
Format NUMERIC..8
Delivery date (format YYYYMMDD) |
invoice_deliveryenddate optional
|
Format NUMERIC..8
Delivery period end date (format YYYYMMDD) |
vaid required
|
Format NUMERIC..8
Billing account ID (module billing) |
balance required
|
Format NUMERIC..10,2
Balance of billing account (in largest currency unit! e.g. Euro) Negative amount: positive balance Positive amount: payment request |
vreference required
|
Format AN..20
Merchant's transaction reference number (This is the reference for the corresponding payment process for a vsettlement) |
vxid required
|
Format NUMERIC..12
Billing account entry ID |
---end
txid
optional
|
Format NUMERIC(9..12)
Corresponding payment process ID |
sequencenumber optional
|
Format NUMERIC..2
Sequence number of settled payment process ID |
settled_vxid[n] optional
|
Format NUMERIC..12
Array of settled vxid's starting with n=0. Array will not be sent if more than 500 vxid's are settled. |
Host: api.pay1.de Content-Type: application/x-www-form-urlencoded
Edit your payload here key1=value1 key2=value2 key3=value3 ...
Edit your response here key1=value1 key2=value2 key3=value3 ...
---
---end
As a reply to the request, the string "TSOK" is expected. Each request is repeated in a 1 to 6 hour cycle until it is answered with "TSOK". This procedure ensures that all requests will be processed by your system. Simply issue the "TSOK" in a script via the "print" command. Make sure that this character string is the first that is printed from this script, e.g. print ("TSOK");
With each payment process status change you receive a request. The last event is submitted to you via the parameter "txaction". The status of the request is provided via the balance of the payment process (parameter "balance") and the amount of the request (parameter "receivable").
txaction | Description |
---|---|
appointed |
Via "appointed" you are informed about the successful initiation of the payment process. This request is affected immediately after the first successful booking. The new parameter “transaction_status” indicates whether the event “appointed” is pending or completed.
-> see list of status (transaction_status) |
capture |
Via "capture" you are informed about the booking of a request or the collection of your reserved amount. The amount of the request (receivable) is increased in this case. If no settlement of balances occurs, the balance changes as well. |
paid |
Via "paid" you are informed that the booking has been processed by the credit institution or that the customer has paid the invoice in full. The balance for the request in this case is smaller than or equal to zero. |
underpaid |
Via "underpaid" you are informed about an underpayment. The balance for the request in this case is greater than zero. |
cancelation |
Via "cancelation" you are informed that a payment process has resulted in a return debit note. In the case of electronic direct debit processes (ELV) insufficient funds in the account may also be the cause. The balance for the request in this case is greater than zero. |
refund |
Via "refund" you are informed if an amount has been refunded. The amount of the request (receivable) is decreased in this case. |
debit |
Via "debit" you are informed about the booking of a request/credit for a request. The amount of the request (receivable) changes in this case. If no settlement of balances occurs, the balance changes as well. |
transfer |
Via "transfer" you are informed if an amount has been transferred. The amount of the open balance (balance) changes in this case. |
reminder |
Attention: This request must be activated by PAYONE. Via "reminder" you are informed about the current status of the dunning procedure. |
vauthorization |
Attention: This request must be activated by PAYONE. Via "vauthorization" you are informed about a booking affected into a billing account (module billing). |
vsettlement |
Attention: This request must be activated by PAYONE. Via "vsettlement" you are informed about a settlement effected on a particular billing account (module billing). |
invoice |
Attention: This request must be activated by PAYONE. Via "invoice" you are informed that an invoice or a credit voucher has been created. |
failed |
Via "failed" you are informed that the booking has finally failed. No further actions are possible |
---end
Via "pending" you are informed that the payment transaction is (still) pending at the external payment processor. The following transaction status may be “pending” (again), “completed” (external payment processor completed the current transaction successfully).
With each payment process status change you receive a request. The last event is submitted to you via the parameter "txaction".
The parameter “transaction_status” is currently introduced with event-txaction “appointed” only. Other event-txaction with parameter “transaction_status” may follow (e.g. “paid”, “debit”, …).
Please note:
transaction_status | Description |
---|---|
pending |
The event indicated by “txaction” is pending and may change later. i.e. an event “appointed/pending” (txaction/transaction_status) indicates that the payment is pending and in process at the 2nd payment processor. Another event may follow to inform change of status by txaction e.g. “appointed/completed”, “failed/completed”. Also another “appointed/pending” may follow to indicate that transaction is still pending. |
completed |
Indicates that the event itself has reached final status. However a new “txaction” (e.g. “paid”, “cancelation”, …) may follow to inform of change of status. The new “txaction” can then be “paid/pending”, “paid/completed”, … or “failed/completed”. |
Field | Description | Beschreibung |
---|---|---|
price |
Value of the initial claim |
Wert der initialen Forderung |
balance |
The outstanding balance of this transaction:
|
Enthält die offene Forderung der Transaktion:
|
receivable |
Account balance for the transaction.
|
Aktuelle offene Forderung für die Transaktion:
|
---end
---end
---end
|
---end
Merchant’s request | HTTP request from PAYONE to the merchant's server | ||||||
---|---|---|---|---|---|---|---|
Seq- No |
Time |
TX-Action/ transaction_state |
Seq- No |
price |
balance |
receivable |
|
Request authorization CC amount=15061 |
0 |
T=0 |
appointed/ completed |
0 |
150.61 |
150.61 |
150.61 |
0 |
+4 min |
paid |
0 |
150.61 |
0 |
150.61 |
---end
Merchant’s request | HTTP request from PAYONE to the merchant's server | Comment | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
Seq- No |
Time |
TX-Action/ transaction_state |
Seq- No |
price |
balance |
receivable |
||||||
Request authorization ELV amount=4612 |
0 |
T=0 |
appointed/ completed |
0 |
46.12 |
46.12 |
46.12 |
Merchant initiates payment via SEPA direct debit |
||||
+15 min |
paid |
0 |
46.12 |
0 |
46.12 |
PAYONE platform has processed direct debit |
||||||
+7 days |
cancelation |
0 |
46.12 |
54.72 |
54.72 |
PAYONE platform has detected a return debit note initiated by end customer and added bank charges of 8,60 EUR and 0 Euro dunning fee |
||||||
+14 days (7+7) |
debit |
1 |
46.12 |
55.72 |
55.72 |
PAYONE platform processed dunning note and added 1,00 Euro dunning fee |
||||||
+21 days |
debit |
2 |
46.12 |
57.72 |
57.72 |
PAYONE platform processed dunning note and added 2,00 Euro dunning fee |
||||||
+28 days |
debit |
3 |
46.12 |
62.72 |
62.72 |
PAYONE platform processed dunning note and added 5,00 Euro dunning fee |
---end
Merchant’s request | HTTP request from PAYONE to the merchant's server | Comment | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|
requires „notify_version=7.6“ |
Seq- No |
Time |
TX-Action/ transaction_state |
Seq- No |
price |
balance |
receivable |
|||||
Request authorization WLT amount=111 |
0 |
T=0 |
appointed/pending |
0 |
1.11 |
0 |
0 |
Server API-response "status= and “reason |
||||
0 |
+10 sec |
appointed/completed |
0 |
1.11 |
1.11 |
1.11 |
||||||
0 |
+6 min |
paid |
0 |
1.11 |
0 |
1.11 |
---end
Merchant’s request | HTTP request from PAYONE to the merchant's server | Comment | ||||||
---|---|---|---|---|---|---|---|---|
Seq- No |
Time |
TX-Action/ transaction_state |
Seq- No |
price |
balance |
receivable |
||
Request preauthorization CC amount=2950 |
0 |
T=0 |
appointed/pending |
0 |
29.50 |
0 |
0 |
|
Request capture |
1 |
+2 hours |
paid |
1 |
29.50 |
0 |
29.50 |
Merchant’s request | HTTP request from PAYONE to the merchant's server | Comment | ||||||
---|---|---|---|---|---|---|---|---|
Seq- No |
Time |
TX-Action/ transaction_state |
Seq- No |
price |
balance |
receivable |
||
Request preauthorization REC amount=11500 |
0 |
T=0 |
appointed/pending |
0 |
115.00 |
0 |
0 |
Merchant initiates payment via payment type invoice |
Request capture |
1 |
+1 day |
capture |
1 |
115.00 |
115 |
115 |
Merchant has delivered ordered items |
+27 days (14+3+10) |
debit |
2 |
115.00 |
117 |
117 |
PAYONE platform generates reminder document and added 2 Euro dunning fee |
||
+10 days |
debit |
3 |
115.00 |
121 |
121 |
PAYONE platform generates reminder document and added 4 Euro dunning fee |
||
PMI: credit note by 15,00 Euro |
4 |
+13 days |
debit |
4 |
115.00 |
106 |
106 |
PAYONE platform processed credit note initiated via PMI |
---end
Merchant’s request | HTTP request from PAYONE to the merchant's server | Comment | ||||||
---|---|---|---|---|---|---|---|---|
Seq- No |
Time |
TX-Action/ transaction_state |
Seq- No |
price |
balance |
receivable |
||
Request preauthorization WLT amount=1561 |
0 |
T=0 |
appointed/pending |
0 |
15.61 |
0 |
0 |
|
Request capture WLT amount=1561 |
1 |
+6 seconds |
capture/pending |
0 |
15.61 |
0 |
15.61 |
Server API-response "status= |
+15 seconds |
capture/- |
0 |
15.61 |
15.61 |
0 |
---end