- Created by PAYONE Admin, last modified on 2022-02-23
Introduction
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
HTTP request from PAYONE to the merchant's server | |||||||||||||||||||||
| Common Parameter | Required | Format | Comment | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
key | + | 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 | + | Default | "appointed", "capture", "paid", "underpaid", "cancelation", "refund", "debit", "reminder", (See explanation below) | ||||||||||||||||||
transaction_status | - | Default | “completed”, “pending” | ||||||||||||||||||
notify_version | - | Default |
| ||||||||||||||||||
mode | + | Default |
| ||||||||||||||||||
portalid | + | N..7 | Payment portal ID | ||||||||||||||||||
aid | + | N..6 | Sub account ID | ||||||||||||||||||
clearingtype | + | Default |
| ||||||||||||||||||
txtime | + | N..11 | Initiating payment process (Unix timestamp) | ||||||||||||||||||
currency | + | Default | Currency (ISO 4217) | ||||||||||||||||||
userid | + | N..12 | Debtor ID (PAYONE) | ||||||||||||||||||
customerid | - | AN1..20 | Merchant's customer ID | ||||||||||||||||||
param | - | AN..255 | Individual parameter that was, where applicable, submitted while payment was initiated | ||||||||||||||||||
Parameter ( personal data ) | |||||||||||||||||||||
Invoice-Address | |||||||||||||||||||||
firstname | o | AN..50 | First name (optional if company is used) | ||||||||||||||||||
lastname | + | AN..50 | Surname | ||||||||||||||||||
company | - | AN..50 | Company | ||||||||||||||||||
street | - | AN..50 | Street number and name | ||||||||||||||||||
zip | - | AN..10 | Postcode | ||||||||||||||||||
city | - | AN..50 | City | ||||||||||||||||||
country | + | Default | Country (ISO 3166) | ||||||||||||||||||
Delivery-Address | |||||||||||||||||||||
shipping_firstname | - | AN..50 | First name (optional if company is used) | ||||||||||||||||||
shipping_lastname | - | AN..50 | Surname | ||||||||||||||||||
shipping_company | - | AN..50 | Company | ||||||||||||||||||
shipping_street | - | AN..50 | Street number and name | ||||||||||||||||||
shipping_zip | - | AN..10 | Postcode | ||||||||||||||||||
shipping_city | - | AN..50 | City | ||||||||||||||||||
shipping_country | - | Default | Country (ISO 3166) | ||||||||||||||||||
- | AN..254 | Email address | |||||||||||||||||||
Parameter for the status message of a payment process | |||||||||||||||||||||
txid | + | N..12 | Payment process ID (PAYONE) | ||||||||||||||||||
reference | + | AN..20 | Merchant reference number for the payment process | ||||||||||||||||||
sequencenumber | + | N..2 | Sequence number at the time of the event for this payment process (0..n) | ||||||||||||||||||
price | + | N..10,2 | Payment request (in largest currency unit! e.g. Euro) | ||||||||||||||||||
receivable | - | N..10,2 | Total payment request (in largest currency unit! e.g. Euro); not set for encashment reminder status information without paid amount | ||||||||||||||||||
balance | - | N..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 | - | Default | Reason for return debit note or incorrect collection (see Reasons for return debit notes (failedcause)) | ||||||||||||||||||
errorcode | o | N..4 | Errorcode in case of txaction=”failed” | ||||||||||||||||||
reasoncode | - | N..10 | Reasoncode in case of transaction_status=”pending”. Further details for transactionhandling see payment addon documentation. Sent only with “notify_version=7.6” | ||||||||||||||||||
Additional parameter Contract for the status message of a payment process | |||||||||||||||||||||
productid | + | N..7 | ID for the offer | ||||||||||||||||||
accessid | + | N3..12 | Access ID | ||||||||||||||||||
expiretime | - | N..12 | Unix Timestamp when access expires | ||||||||||||||||||
Additional parameter for payment type debit payment | |||||||||||||||||||||
bankcountry | - | Default | Account type/ country | ||||||||||||||||||
bankaccount | - | AN..26 | Account number (masked) | ||||||||||||||||||
bankcode | - | AN..11 | Sort code | ||||||||||||||||||
bankaccountholder | - | AN..35 | Account holder | ||||||||||||||||||
Additional parameter for payment type debit payment (only for authorization with appointed and only if “due_time” is not specified) | |||||||||||||||||||||
iban | o | AN..35 | International Bank Account Number (masked) | ||||||||||||||||||
bic | o | AN..11 | Bank Identifier Code | ||||||||||||||||||
mandate_identification | o | AN..35 | Used mandate_identification | ||||||||||||||||||
creditor_identifier | o | AN..35 | Merchant’s creditor identifier | ||||||||||||||||||
clearing_date | o | N8 | clearing date (format YYYYMMDD) | ||||||||||||||||||
clearing_amount | o | N..10 | Payment request (in smallest currency unit! e.g. cent) | ||||||||||||||||||
Additional parameter for payment type credit card | |||||||||||||||||||||
cardpan | + | N..19 | Card number | ||||||||||||||||||
cardtype | + | Default | Card type
| ||||||||||||||||||
cardexpiredate | + | N4 | Expiry date YYMM | ||||||||||||||||||
cardholder | - | AN..35 | Name of cardholder | ||||||||||||||||||
| cardholder_info | - | 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. | ||||||||||||||||||
Additional parameter for payment type paypal | |||||||||||||||||||||
provider_payerid | - | AN..13 | Unique PayPal Customer Account identification number. | ||||||||||||||||||
Additional parameter for payment type iDeal | |||||||||||||||||||||
| customer_bankaccountholder | - | AN..35 | Customers bank account holder | ||||||||||||||||||
| customer_iban | - | AN..35 | Customers IBAN | ||||||||||||||||||
| customer_bic | - | AN..11 | Customers BIC | ||||||||||||||||||
Additional parameter for payment type BillSAFE / Klarna | |||||||||||||||||||||
clearing_bankaccountholder | - | AN..35 | Recipient bank account holder | ||||||||||||||||||
clearing_bankcountry | - | Default | Recipient account type/ country (e.g. DE, AT, etc.) | ||||||||||||||||||
clearing_bankaccount | - | AN..26 | Recipient bank account | ||||||||||||||||||
clearing_bankcode | - | AN..11 | Recipient sort code | ||||||||||||||||||
clearing_bankiban | - | AN..35 | Recipient IBAN | ||||||||||||||||||
clearing_bankbic | - | AN..11 | Recipient BIC | ||||||||||||||||||
clearing_bankcity | - | AN..50 | Recipient city or bank | ||||||||||||||||||
clearing_bankname | - | AN..50 | Recipient bank name | ||||||||||||||||||
clearing_legalnote | - | AN..500 | Note to claim assignment | ||||||||||||||||||
clearing_duedate | - | N8 | Due date of payment (format YYYYMMDD) | ||||||||||||||||||
clearing_reference | - | AN..50 | Reference | ||||||||||||||||||
clearing_instructionnote | - | AN..200 | Note to payment handling | ||||||||||||||||||
Additional parameter Collect (txaction=reminder) for the status message of a payment process | |||||||||||||||||||||
reminderlevel | + | Default | Customer's reminder status
| ||||||||||||||||||
encashment_statuscode | - | AN..20 | Internal status code of the encashment agency, if provided by the encashment agency. | ||||||||||||||||||
encashment_statuslongtext | - | AN..255 | Free text: if the encashment agency has reported a long text (detailed information) on the status | ||||||||||||||||||
Parameter Invoicing (txaction=invoice) | |||||||||||||||||||||
txid | + | N..12 | Payment process ID (PAYONE) | ||||||||||||||||||
reference | + | AN..20 | Merchant reference number for the payment process | ||||||||||||||||||
sequencenumber | + | N..2 | Sequence number at the time of the event for this payment process (0..n) | ||||||||||||||||||
invoiceid | + | AN..20 | Merchant's invoice number | ||||||||||||||||||
invoice_grossamount | + | N..10,2 | Gross invoice amount | ||||||||||||||||||
invoice_date | + | N8 | Invoice date (format YYYYMMDD) | ||||||||||||||||||
invoice_deliverydate | - | N8 | Delivery date (format YYYYMMDD) | ||||||||||||||||||
invoice_deliveryenddate | - | N8 | Delivery period end date (format YYYYMMDD) | ||||||||||||||||||
Parameter Billing (txaction=vauthorization/vsettlement) | |||||||||||||||||||||
vaid | + | N..8 | Billing account ID (module billing) | ||||||||||||||||||
balance | + | N..10,2 | Balance of billing account (in largest currency unit! e.g. Euro) Negative amount: positive balance Positive amount: payment request | ||||||||||||||||||
vreference | + | AN..20 | Merchant's transaction reference number (This is the reference for the corresponding payment process for a vsettlement) | ||||||||||||||||||
vxid | + | N..12 | Billing account entry ID | ||||||||||||||||||
Parameter Billing (txaction=vsettlement) | |||||||||||||||||||||
txid | o | N..12 | Corresponding payment process ID | ||||||||||||||||||
sequencenumber | o | N..2 | Sequence number of settled payment process ID | ||||||||||||||||||
settled_vxid[n] | o | N..12 | Array of settled vxid's starting with n=0. Array will not be sent if more than 500 vxid's are settled. | ||||||||||||||||||
Important note: Please note that new parameters may be added at any time without previous notice. Therefore, you should use the parameter name for the evaluation and not the sequence, which may be subject to change at any time!
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").
| 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. Important note:
|
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. |
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”.
| 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”. |
Content
- No labels