5.8. XML accounting API

5.8.1. Web Services

The XML accounting API provides means to retrieve payment and settlement data with SOAP. With these services you may query the state of any payment and retrieve an accounting report over a time interval with all the wanted batch and payment data. The following chapters describe the complex data types used in SOAP queries. Interfaces are described as well. To better understand the complex data types, check out the WSDL files for interfaces.

When using payment methods with direct contracts (as interfaces), Paytrail cannot confirm these payments. Thus, if information about paid payment is not retrieved with the actual payment (redirect from bank service), these payments are never marked as paid in Paytrail's service. When payment methods are used with Paytrail's contracts, Paytrail confirms all payments automatically from the banks.

Note

Using web services always requires an additional agreement with Paytrail. Please contact customer service when you wish to use these services.

5.8.2. Complex data types

Table 5.19. SVAuthentication

TypeNameDescription
xsd:intmerchantIdMerchant ID (for example 13466)
xsd:stringmerchantXMLPasswordMerchant XML password. Paytrail delivers this password when the service is ordered.

Table 5.20. SVBatch

TypeNameDescription
xsd:stringbatchIdBatch reference number
xsd:intcreatedBatch timestamp (Unix timestamp)
xsd:doubletotalTotal sum of payments to be accounted in this batch.
tns:SVPaymentArraypaymentsList of payments which are included in this batch.

Table 5.21. SVPayment

TypeNameDescription
xsd:stringorderNumberPayment's order number
xsd:stringreferenceNumberPayment's reference number
xsd:intcreatedPayment creation time as Unix timestamp
xsd:doubletotalPayment's original sum
xsd:doubleprovisionProvision that was deducted from original amount. Accounted sum is original sum subtracted by provision.
xsd:stringpayerThe name of the owner of the account from which the payment was made. The name is received from the banking materials, and can be partial. This information is only available for payments completed with bank payment methods, and NULL for others.

Table 5.22. SVBatchArray

TypeNameDescription
arrayType, SVBatch[] List of batches.

Table 5.23. SVPaymentArray

Type NameDescription
arrayType, SVPayment[] List of payments.

5.8.3. Error messages

If something goes wrong with the SOAP service, functions will return SOAPFault error messages. These are the possible SOAPFault messages:

Table 5.24. Error Codes

Error codeDescription
SVXML100Missing merchant ID or XML password
SVXML101Invalid merchant ID or XML password
SVXML200Payment was not found with the given order number
SVXML300Problem with the time interval

5.8.4. Reporting service

The SOAP service for retrieving bookkeeping reports is available at https://ws.paytrail.com/soap/?soap=Report.wsdl

The function used for retrieving bookkeeping reports is called getBatches.

Function getBatches returns a list of batches within a given time interval. The maximum interval length is two months. Return value is of type SVBatchArray.

Table 5.25. getBatches

TypeDescription
SVAuthenticationMerchant identification data
xsd:stringInterval start date in format yyyy-mm-dd
xsd:stringInterval end date in format yyyy-mm-dd

Function getPayments returns a list of successful payments from a given time interval. Return value is of type SVPaymentArray. The maximum interval to retrieve payments for is two months. The function does not ensure that returned payments are in any specific order.

Table 5.26. getPayments

TypeDescription
SVAuthenticationMerchant identification data
xsd:stringInterval start date in format yyyy-mm-dd
xsd:stringInterval end date in format yyyy-mm-dd

5.8.5. Payment service

The SOAP service used for retrieving payment data is available at: https://ws.paytrail.com/soap/?soap=Payment.wsdl

The payment service allows payment state queries with method getPaymentState.

Table 5.27. getPaymentState

Type Description
SVAuthenticationMerchant identification data
xsd:stringOrder number to fetch state for

This function returns the payment state as a string. The possible return values with descriptions are listed below:

Table 5.28. Return values

Return valueDescription
PENDINGPayment is not paid. Order is pending for payment or payment has been cancelled. Cancelled payments will move to state NOT_PAID later.
CANCELLEDPayment is not paid. Payment has been cancelled with cancel button.
NOT_PAIDPayment is not paid.
PAIDPayment has been paid.
CONFIRMEDPayment has been paid and Paytrail has confirmed the payment.
TO_BE_ACCOUNTEDPayment has been paid and confirmed. It is moved to to be accounted.
ACCOUNTEDPayment has been accounted.