Page tree
Skip to end of metadata
Go to start of metadata

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 ParameterRequiredFormatComment

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",
"vauthorization", "vsettlement", "transfer", "invoice", “failed”

(See explanation below)

transaction_status

-

Default

“completed”, “pending”

notify_version

-

Default

7.3

without “notify_version” and without “transaction_status”

7.4

with “notify_version” and with “transaction_status” (completed/pending)

7.5

with txaction “failed”

7.6

with “transaction_status=pending” and “reasoncode”

mode

+

Default

test

Test mode

live

Live mode

portalid

+

N..7

Payment portal ID

aid

+

N..6

Sub account ID

clearingtype

+

Default

elv

Debit payment

cc

Credit card

vor

Prepayment

rec

Invoice

cod

Cash on delivery

sb

Online bank transfer

wlt

e-Wallet

fnc

Financing

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)

email

-

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

V

Visa

M

MasterCard

A

American Express

D

Diners / Discover

J

JCB

O

Maestro International

C

Discover

B

Carte Bleue

P

China Union Pay

cardexpiredate

+

N4

Expiry date YYMM

cardholder

-

AN..35

Name of cardholder

Additional parameter for payment type paypal

provider_payerid

-

AN..13

Unique PayPal Customer Account identification number.

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

reminderlevelDescription
1..4Dunning level 1-4
5Encashment
ADunning procedure ended
SDunning procedure begins
MDunning proposal list
IEncashment proposal list
0Dunning procedure completed

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

txactionDescription

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:

  • 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

for future use – not implemented yet.

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_statusDescription

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