Introduction

SOAP Interface Formatting

Real XMLs would not contain newlines and formatting: it is added to enhance readability of this document. If you wish to construct response XMLs using newlines and formatting, you are free to do it, because the XML parser ignores whitespaces.

Names of the XML schemas namespaces can differ from the ones shown in this example.

The order of details is not fixed. For instance, amount can be placed first, last, or anywhere in between. Additional details and tags can be passed in the response. Merchant’s system should be able to ignore them if such additional details appear. All input details are required to be passed in the order they are stated to be in, except for the optional details.

Response may contain a tag <needDetails>. This tag shows mandatory details that are still needed for the payment processing in the following form:

    <item>
        <name>detail_name</name>
        <screen></screen>
        <type>detail_type</type>
    </item>

Project Scope

This section describes the format of SOAP messages that Payment Service Provider (PSP) will send to DECTA SOAP interface.

Payment Response Messages

The payment execution web service response messages will contain all request elements, except billerRef, payinstrRef, switchingID, and language. Response messages may contain details that were not specified in the request. Merchant's system must be able to handle such cases by ignoring the optional details. Web service method response messages may differ between methods. Additionally to payment details, response messages may contain action, status, and NeedDetails elements. NeedDetails element shows which mandatory details are missing. Its presence together with Action1 is normal for all payment Step 1.

Payment Execution Timeout

All payments have a built-in timeout value which is 7 days (10080 minutes) for the two-step based scenarios and 28 days (40320 minutes) for the three-step based scenarios. If the payment is not finished within this time frame, it will be canceled automatically. For the simple payments, the DMS case captured funds on the cardholder's account will be unblocked.

Exception Handling

In cases when RTPS EBPP responds in a way that is not expected (e.g., action does not match the expected value), timeout is received (recommended timeout value is 60 seconds), or an exception is raised. Merchant's system must execute payment cancellation. In most but not all cases fault element will be returned in the response message, and it will contain the following elements:

• Faultcode - “SOAP-ENV:Client”
• Faultstring – human readable explanation of the fault, filled when SOAP related errors occur
• Detail - PaymentServerException
• Provider – identifies system components where the fault occured
  • EBPP – fault within CardSuite RTPS EBPP component
  • SOAP – fault within communication with 3rd party system
  • RSW – fault within CardSuite RTPS Switching component
  • FARE – fault within CardSuite RTPS Fraud prevention/detection component
  • NETSW – fault within CardSuite RTPS Netswitch component
• Error – error code, numeric or string value
• Description – human readable errors description
• Screen – internal information

For payment failure troubleshooting all previously mentioned elements and further listed details should be provided to DECTA:

• paymentID
• clientID
• biller_client_id
• auth_stan
• auth_stan2
• perspayee_id

Fraud Prevention / Detection Component Error Handling

In case of getting the error with description “SCORE is greater than fare_max_score” in Step 2 or Step 3, GetPayment method can be used to receive fare_matched_rules detail. Customer managers can explain which fraud rule was triggered by fare_matched_rules detail value.

    <item>
                        <name>fare_matched_rules</name>
                        <value>AP0003</value>
                    </item>
                </details>
            </ebppif1:GetPaymentResponse>
        </SOAP-ENV:Body>
    </SOAP-ENV:Envelope>

In this case, the value of the item fare_matched_rules is AP00003 and it must be passed to the customer manager for additional information about the rejection reason.