SOAP Web service API v5 Implementation guide Document version 2.5 Contents 1. HISTORY OF THE DOCUMENT...................................................................................................... 5 2. GETTING IN TOUCH WITH TECHNICAL SUPPORT................................................................. 8 3. INTRODUCTION TO WEB SERVICES............................................................................................9 3.1. Security........................................................................................................................................................ 9 3.2. Description of web services........................................................................................................................ 9 SOAP HEADER................................................................................................................................... 11 The Body...............................................................................................................................................11 3.3. Managing error codes and exceptions.......................................................................................................13 Managing exceptions............................................................................................................................ 13 Managing application errors.................................................................................................................14 3.4. Sending multiple Web service queries (within the same HTTP session)................................................. 19 3.5. Managing the timeout................................................................................................................................21 3.6. Specifying data type..................................................................................................................................22 4. IDENTIFYING YOURSELF DURING DATA EXCHANGE..........................................................23 4.1. Proceeding to authentication..................................................................................................................... 24 4.2. Creating the SOAP HEADER in the query..............................................................................................25 Example of PHP code for creating a SOAP HEADER.......................................................................27 4.3. Verifying the SOAP header in the response.............................................................................................28 Example of PHP code for retrieving SOAP headers in the response.................................................. 28 5. GENERATING AN UUID - BACKWARD COMPATIBILITY.....................................................29 5.1. Request.......................................................................................................................................................29 legacyTransactionKeyRequest.............................................................................................................. 30 5.2. Response.................................................................................................................................................... 31 commonResponse..................................................................................................................................31 paymentResponse..................................................................................................................................31 6. PERFORMING COMMON TRANSACTION OPERATIONS...................................................... 32 6.1. Creating a payment transaction 'createPayment'.......................................................................................32 Token sharing........................................................................................................................................33 Request.................................................................................................................................................. 34 Response................................................................................................................................................46 Creating a payment without 3D Secure authentication........................................................................60 Creating a payment with 3D Secure authentication.............................................................................63 Retrying a declined payment................................................................................................................71 6.2. Updating a payment transaction (updatePayment')...................................................................................72 Request.................................................................................................................................................. 72 Response................................................................................................................................................76 6.3. Updating shopping cart information (updatePaymentDetails)..................................................................88 Request.................................................................................................................................................. 88 Response................................................................................................................................................90 6.4. Canceling a payment transaction (cancelPayment).................................................................................103 Request................................................................................................................................................ 103 Response..............................................................................................................................................104 6.5. Searching for payments (findPayments)................................................................................................. 106 Request................................................................................................................................................ 106 Response..............................................................................................................................................107 6.6. Refunding a buyer 'refundPayment'........................................................................................................ 110 Request................................................................................................................................................ 110 Response..............................................................................................................................................112 6.7. Duplicating a payment transaction 'duplicatePayment'...........................................................................126 Request................................................................................................................................................ 126 Response..............................................................................................................................................130 6.8. Validating a payment transaction (validatePayment)..............................................................................144 Request................................................................................................................................................ 144 Response..............................................................................................................................................145 6.9. Capturing a payment transaction 'capturePayment'.................................................................................147 Request................................................................................................................................................ 147 Response..............................................................................................................................................148 6.10. Obtaining payment details (getPaymentDetails)...................................................................................149 Request................................................................................................................................................ 149 Response..............................................................................................................................................150 6.11. Verifying the 3D Secure authentication (verifyThreeDSEnrollment)...................................................163 Request................................................................................................................................................ 163 Response..............................................................................................................................................166 6.12. Verifying the 3D Secure authentication status (checkThreeDSAuthentication)................................... 168 Request................................................................................................................................................ 168 Response..............................................................................................................................................169 7. MAKING