Getting Started with TransactionStatus Notifications

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.

PMI Configuration

You can configure the TransactionStatus Endpoint of your system in your payment portal configuration.

Use Cases

Redirect Payment Methods

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.

Chargeback Processes

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.

Technical Specification

PAYONE to your Endpoint

• Status messages from PAYONE to merchant's server are always ISO-8859-1 encoded.
• Status messages are posted with application/x-www-form-urlencoded
   

key=your key as md5 hash e.g. "3c6e0b8a9c15224a8228b9a98ca1531d"
txaction=appointed
portalid=1234567
aid=12345
clearingtype=cc
notify_version=7.4
txtime=1633361234
currency=EUR
userid=12345678
mode=test
price=19.99
txid=987654321
reference=10001_2
sequencenumber=0
firstname=Max
lastname=Mustermann
street=J%E4gerweg 12
zip=12345
city=Berlin
email=mmustermann@payone.com
country=DE
cardexpiredate=2505
cardtype=V
cardpan=411111xxxxxx1111
transaction_status=completed
balance=0.00
receivable=0.00

Synchronous Reply

your endpoint will have to reply synchronously with either TSOK or SSOK (just 4 characters, no html)

• No other characters may be issued with this character string “SSOK”/”TSOK”
• Do not return an error without gathering information about this error.
• The request must be answered with SSOK (for SessionStatus) / TSOK (for TransactionStatus). The connection timeout is set to 10 seconds and can not be extended.
• Make sure the request is always answered with an SSOK (for SessionStatus) / TSOK (for TransactionStatus).
• The request is repeated a maximum of 12 times and for a maximum of 48 hours. The first retry is started after about one hour and the retry time is increasing. After 48 hours the request will not be repeated any more.
• The answer does only confirm receipt of the SessionStatus, the evaluation can and should follow asynchronously to receiving the answer.
• If a specific request shall not be processed, issue an SSOK (for SessionStatus) / TSOK (for TransactionStatus) anyway to prevent the request from interfering with the processing of other requests.
• Without the return of an SSOK (for SessionStatus) / TSOK (for TransactionStatus) you will not receive any further status reports for that subscription / payment process.
• Please verify received status responses before processing, i.e.: check whether portalid, aid and key do match your expected credentials. If credentials do not match your expected values then dismiss status response.

TSOK

Parameter for the TransactionStatus

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.

TransactionStatus

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

Expected reply to the request

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"); 

List of events (txaction)

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").

List of status (transaction_status)

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:

• The parameter “transaction_status” is optional and not available for all payment transactions (“txaction”) and all payment types (as not all payments and processors do support “pending” / “completed”).
• It may happen that you will receive two times the same txaction (e.g. “appointed”). First with “pending” and then with “completed”. 

Parameter for SessionStatus query

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

Explanation of price, balance, receivable

Samples of TransactionStatus

EXAMPLE 1:
https://shop.domain.shop/test/p1.php?key=xxxxx&txaction=appointed&portalid=2000001&aid=10001&clearingtype=cc&notify_version=7.4&txtime=1533547771&currency=EUR&userid=100000001&accessname=&accesscode=&param=&mode=test&price=1.00&id[1]=1_1&pr[1]=1.00&no[1]=1&de[1]=item+description&ti[1]=&va[1]=19.00&txid=285115882&reference=1533547769340&sequencenumber=0&company=&firstname=Max&lastname=Musterm%E4nnchen&street=Fraunhoferstra%DFe+2-4&zip=24118&city=Kiel&email=test.test%40test.com&country=DE&shipping_company=&shipping_firstname=Max&shipping_lastname=Muster&shipping_street=FRAUNHOFER+STR+2-4&shipping_zip=24103&shipping_city=Kiel&shipping_country=DE&cardexpiredate=2012&cardtype=V&cardpan=401200xxxxxx1112&transaction_status=completed&balance=1&receivable=1

EXAMPLE 2:
https://shop.domain.shop/test/p1.php?key=xxxxx&txaction=invoice&portalid=2000001&aid=10001&clearingtype=cc&notify_version=7.4&txtime=1533547771&currency=EUR&userid=100000001&accessname=&accesscode=&param=&mode=test&price=1.00&txid=285115882&reference=1533547769340&sequencenumber=0&company=&firstname=Max&lastname=Musterm%E4nnchen&street=Fraunhoferstra%DFe+2-4&zip=24118&city=Kiel&email=test.test%40test.com&country=DE&shipping_company=&shipping_firstname=Max&shipping_lastname=Muster&shipping_street=FRAUNHOFER+STR+2-4&shipping_zip=24103&shipping_city=Kiel&shipping_country=DE&cardexpiredate=2012&cardtype=V&cardpan=401200xxxxxx1112&invoiceid=RG-285115882-0&invoice_grossamount=1&invoice_date=20180806

EXAMPLE 3:
https://shop.domain.shop/test/p1.php?key=xxxxx&txaction=paid&portalid=2000001&aid=10001&clearingtype=cc&notify_version=7.4&txtime=1533547771&currency=EUR&userid=100000001&accessname=&accesscode=&param=&mode=test&price=1.00&id[1]=1_1&pr[1]=1.00&no[1]=1&de[1]=item+description&ti[1]=&va[1]=19.00&txid=285115882&reference=1533547769340&sequencenumber=0&company=&firstname=Max&lastname=Musterm%E4nnchen&street=Fraunhoferstra%DFe+2-4&zip=24118&city=Kiel&email=test.test%40test.com&country=DE&shipping_company=&shipping_firstname=Max&shipping_lastname=Muster&shipping_street=FRAUNHOFER+STR+2-4&shipping_zip=24103&shipping_city=Kiel&shipping_country=DE&cardexpiredate=2012&cardtype=V&cardpan=401200xxxxxx1112&balance=0&receivable=1