Implementation guide Web Services V4
Transcription
Implementation guide Web Services V4
Implementation guide Web Services V4 Version 1.4b Confidentiality All the information in the current document is considered confidential. Using it outside the context of this consultation or disclosing it to exterior persons is subject to prior approval by Lyra Network. SUMMARY 1. 2. 3. 4. 5. 6. 7. Purpose ............................................................................................................................................................ 1 Notions of timeout ........................................................................................................................................... 2 Error Handling .................................................................................................................................................. 3 Data Types definitions .................................................................................................................................... 8 Maintain HTTP session ..................................................................................................................................... 9 Signature computation ................................................................................................................................ 10 API Use Cases and Examples ...................................................................................................................... 11 7.1. 3D-Secure transaction process......................................................................................................... 11 7.2. Create a transaction with 3D-Secure authentication (card enrolled) ......................................... 12 Verify the cardholder’s enrolment status ............................................................................................ 12 Redirect the cardholder to ACS ......................................................................................................... 14 Handle ACS Response ...................................................................................................................... 16 Handle the authentication result and complete the transaction ......................................................... 17 7.3. Create a transaction without 3D-Secure authentication ............................................................... 18 7.4. Create a payment with 3D-Secure handled by merchant’s MPI plugin ..................................... 20 7.5. Update a transaction ......................................................................................................................... 22 7.6. Cancel a transaction ......................................................................................................................... 23 7.7. Refund a transaction .......................................................................................................................... 24 7.8. Duplicate a transaction ..................................................................................................................... 25 7.9. Retrieve a transaction ........................................................................................................................ 26 7.10. Validate a transaction ..................................................................................................................... 27 8. Methods ......................................................................................................................................................... 28 createWithThreeDS().................................................................................................................................. 28 finalyzeWithThreeDS................................................................................................................................... 29 create() ....................................................................................................................................................... 30 modify() ...................................................................................................................................................... 31 cancel() ...................................................................................................................................................... 33 refund() ....................................................................................................................................................... 34 duplicate() .................................................................................................................................................. 36 getInfo() ...................................................................................................................................................... 38 validate() .................................................................................................................................................... 39 force() ......................................................................................................................................................... 40 9. Objects ........................................................................................................................................................... 41 createPaymentInfo .................................................................................................................................... 41 createPaymentGeneralInfo ..................................................................................................................... 42 createCardInfo .......................................................................................................................................... 44 createSubPaymentInfo ............................................................................................................................. 45 createCustomerInfo .................................................................................................................................. 46 createShippingInfo .................................................................................................................................... 47 createExtraInfo........................................................................................................................................... 48 paymentCreationInfo ................................................................................................................................ 49 threeDsResult .............................................................................................................................................. 50 custStatus .................................................................................................................................................... 52 deliverySpeed ............................................................................................................................................ 52 deliveryType ............................................................................................................................................... 52 extInfo ......................................................................................................................................................... 52 createWithThreeDSResponse.................................................................................................................... 53 veResPAReqInfo ......................................................................................................................................... 54 transactionInfo ........................................................................................................................................... 55 transactionPaymentGeneralInfo ............................................................................................................. 56 transactionCardInfo .................................................................................................................................. 57 transactionThreeDSInfo ............................................................................................................................. 58 transactionAuthorizationInfo .................................................................................................................... 60 transactionMarkInfo .................................................................................................................................. 61 transactionWarrantyDetailsInfo ................................................................................................................ 62 localControl ................................................................................................................................................ 63 transactionCaptureInfo ............................................................................................................................. 64 transactionCustomerInfo .......................................................................................................................... 65 transactionShippingInfo ............................................................................................................................ 66 transactionExtraInfo................................................................................................................................... 67 standardResponse ..................................................................................................................................... 68 10. Appendices ................................................................................................................................................... 69 Test credit card numbers .......................................................................................................................... 69 Transaction statuses .................................................................................................................................. 70 Bank response code (used for authResult and markResult). ............................................................... 71 .Net .............................................................................................................................................................. 72 PHP Sample code : signature computation (create method) ............................................................. 73 1. Purpose This document presents the standard Web services which allow you to create transactions (with or without 3D-Secure authentication) and to act on the transactions. Web services have been developed in accordance with the following SOAP protocol (Simple Object Access Protocol). The web service description language document for the service is available at https://paiement.systempay.fr/vads-ws/v4.3?wsdl In order to make exchanges secure, Web services (SOAP) are encrypted thanks to the HTTPS protocol. Moreover, a signature mechanism has been set up to validate and authenticate data exchange. Systempay – Implementation Guide – webservices V4 @Lyra Network- 1/79 2. Notions of timeout A Web service request’s processing is made of a series of asynchronous operations such as: sending of the request via the merchant site’s network, transferring data across the Internet, payment’s processing by the payment gateway, requesting the acquirer and the issuer, etc… A connection failure may occur in every step and increase the process’s runtime. A response can take a long time for several reasons: High response time from issuer bank‘s server, (foreign credit cards, period of high server load, ...) high response time from acquirer bank‘s server when sending the authorization, high response time from merchant side during peaks in traffic, High response time from payment gateway. Internet Peering issues, etc... Depending how you have configured timeouts in your application, you can give up and close the connection, while the payment gateway is still processing your request. Be careful, a long response time must not be considered as a payment declined. You should configure your code to handle potential problems with connecting to the SOAP API. Best practices The average response time to handle a payment request is less than 5s. So, you should set client-side timeout to 20 to 30s. When a Web Service request exceeds the timeout limit time, you should not inform the shopper that the payment has been declined. If you do so, the shopper will try to make another payment while the first try is still in progress by the gateway. It would be better to choose one of the following solutions: 1. Inform the shopper that the payment is in progress. Asynchronously, ask the gateway for the status of the transaction. Then you can notify the shopper with the result of his purchase. 2. Inform the shopper that the payment has been declined Make sure you won’t validate the transaction (suppose the payment to be created with manual validation). Systempay – Implementation Guide – webservices V4 @Lyra Network- 2/ 79 3. Error Handling You can review the codes below to help troubleshoot your development efforts and fix any problems you might have. ErrorCode in a TransactionInfo Object: Error Code 0 1 2 3 4 5 6 10 11 12 13 14 15 16 17 18 19 20 21 22 23 26 27 40 50 51 52 53 54 55 56 57 58 59 60 61 Error Code Error Message Action successfully completed Unauthorized request TransactionID was not found Bad transaction status Transaction already exists Incorrect signature computation TransmissionDate is too far from current UTC date Invalid input field ‘amount’ Invalid input field ‘currency’ Unknown card type Invalid input field ‘expiryDate’ Invalid input field ‘cvv’ Unknown contract number Invalid input field ‘cardNumber’ CardIdent not found Invalid cardIdent (cancelled, …) SubscriptionID was not found Invalid Subscription CardIdent already exists cardIdent creation declined cardIdent purged Nothing has changed Amount not authorized Card range not found Invalid input field ‘siteId’ invalide Invalid input field ‘transmissionDate’ Invalid input field ‘transactionId’ Invalid input field ‘ctxMode’ Invalid input field ‘comment’ Invalid input field ‘AutoNb’ Invalid input field ‘AutoDate’ Invalid input field ‘captureDate’ Invalid input field ‘newTransactionId’ Invalid input field ‘validationMode’ Invalid input field ‘orderId’ Invalid input field ‘orderInfo1’ Error Message 62 63 64 65 66 67 Invalid input field ‘orderInfo2’ Invalid input field ‘orderInfo3’ Invalid input field ‘paymentSource’ Invalid input field ‘cardNetwork’ Invalid input field ‘contractNumber’ Invalid input field ‘customerId’ 68 Invalid input field ‘customerTitle’ 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 90 91 92 93 94 95 96 98 99 Invalid input field ‘customerName’ Invalid input field ‘customerPhone’ Invalid input field ‘customerMail’ Invalid input field ‘customerAddress’ Invalid input field ‘customerZipCode’ Invalid input field ‘customerCity’ Invalid input field ‘customerCountry’ Invalid input field ‘customerLanguage’ Invalid input field ‘customerIp’ Invalid input field ‘customerSendMail’ Invalid input field ‘customerMobilePhone’ Invalid input field ‘subPaiementType’ Invalid input field ‘subReference’ Invalid input field ‘initialAmount’ Invalid input field ‘occInitialAMount’ Invalid input field ‘effectDate’ Invalid input field ‘state’ Invalid input field ‘customerAddressNumber’ Invalid input field ‘customerDistrict Invalid input field ‘customerState Invalid input field ‘enrolled’ Invalid input field ‘authStatus’ Invalid input field ‘eci’ Invalid input field ‘xid’ Invalid input field ‘cavv’ Invalid input field ‘cavvAlgo’ Invalid input field ‘brand’ Invalid input field ‘requestId’ Unknown error Systempay – Implementation Guide – webservices V4 @Lyra Network- 3/ 79 ErrorCode in a veResPAReqInfo object: Error Code 0 1 2 3 4 5 6 7 Error Code Description Action successfully completed Unauthorized request Incorrect signature computation Brand not found Invalid card number No suitable contract Ambiguous contract Merchant not enrolled 8 9 10 11 12 13 14 99 Description Invalid ACS Signature Technical error Wrong Parameter Incorrect date format 3DS Disabled cardIdent not found PAN not found Unknown error PaymentError in a transactionInfo object Error Code 1 2 Error Code Error Message Error Message Transaction not found. Transaction not found. This action is not authorized on a transaction with the status {0}. This transaction is not authorized in this context. 72 73 #N/A Pre-authorization declined. 74 Invalid payment configuration. 75 The operation was declined by Paypal. 5 This transaction already exists. 76 6 Invalid transaction amount. 77 3 4 A technical problem occurred. We are not able to process your request. Following a technical problem, we are not able to process your request. 18 This operation is no longer allowed for a transaction created on this date. The card expiry date does not allow this operation. CVV is compulsory for this card. The credit amount is higher than the initial amount. The credit amount is higher than the initial amount. The duplication of a refund is not authorized. A technical problem occurred. We are not able to process your request. A technical problem occurred. We are not able to process your request. A technical problem occurred. We are not able to process your request. A technical problem occurred. We are not able to process your request. The remote setting of the Aurore contract failed. The analysis of the Cetelem response failed. 19 Unknown currency. 90 20 91 92 #N/A 22 23 Invalid type of card. No contract found for this payment. Please change the data or contact your manager in case of multiple failures. POS not found. Ambiguous contract. A technical problem occurred. We are not able to process your request. A technical problem occurred. We are not able to process your request. A technical problem occurred. We are not able to process your request. A technical problem occurred. We are not able to process your request. A technical problem occurred. We are not able to process your request. This modification is not authorized. An error occurred during the refund of this transaction. No payment option enabled for this contract. 93 94 24 Invalid contract. 95 25 A technical problem occurred. We are not able to process your request. 96 #N/A #N/A A technical problem occurred. We are not able to process your request. An error occurred during the capture of this transaction. 7 8 9 10 11 12 13 14 15 16 17 21 78 #N/A 79 #N/A 80 #N/A 81 The content of the configuration theme is not valid. 82 Refund is not authorized for this contract. 83 Transaction amount outside the allowed values. 84 85 86 87 88 89 Systempay – Implementation Guide – webservices V4 @Lyra Network- 4/ 79 97 #N/A 26 27 28 A technical problem occurred. We are not able to process your request. Invalid card number. Invalid card number. Invalid card number. 98 99 100 29 Invalid card number. 101 30 Invalid card number. (Luhn) 102 31 Invalid card number. (length) 103 32 Invalid card number. (not found) 104 33 Invalid card number. (not found) 105 Invalid transaction date. #N/A #N/A Declined because the first installment has been declined. The operation was declined by Buyster. The transaction status failed to be synchronized with the external system An error occurred during the capture of this transaction. A security error occurred when processing 3DS information for this transaction. 25 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 57 58 Card with unconditional authorization control failed. E-carte bleue control failed. The risk control has caused a declined transaction. #N/A A technical problem occurred. We are not able to process your request. 3-D Secure was declined for this transaction. A technical problem occurred. We are not able to process your request. A technical problem occurred. We are not able to process your request. #N/A #N/A It is not possible to force an imprint Invalid currency for this change. The amount exceeds the maximum authorized amount. The presentation date that was requested is later than the authorization's validity date. The required change is not valid. Invalid definition of multiple installment. Unknown POS. Unknown exchange rate. This contract was closed on {0}. The shop {0} is closed since {1}. This parameter that was rejected may include sensitive data {0}. A technical problem occurred. We are not able to process your request. Problem with the buyer account recovery. This buyer account is not compatible with this operation 106 Unsupported currency on this contract and/or shop. 107 109 #N/A A technical problem occurred. We are not able to process your request. #N/A 110 Payment card not supported by the contract. 111 Refusal of transactions without liability shift. 112 The cancellation is not authorized 113 Duplication is not permitted 114 115 116 118 Forcing is not authorized Refund is not authorized MOTO payment is not authorized for this card Multiple installments are not authorized for this card 119 The date submitted is not valid 108 121 122 123 124 125 126 The option of payment of the initial transaction is not applicable #N/A #N/A #N/A #N/A #N/A #N/A 128 #N/A 129 #N/A 130 #N/A 131 #N/A 120 59 Problem with the buyer account recovery. 132 60 61 This buyer account already exists. Invalid buyer ID. 133 134 62 Creation of the buyer account declined. 135 63 This recurring payment already exists. 136 64 65 66 67 This recurring payment is already terminated. Invalid recurring payment. The rule of recurring payment is not valid. Creation of the recurring payment declined. A technical problem occurred. We are not able to process your request. #N/A #N/A The integration of the payment page into an iframe is not authorized. Refusal of the derived transactions, without liability shift on the primary transaction. 137 #N/A 138 139 #N/A #N/A 140 #N/A Systempay – Implementation Guide – webservices V4 @Lyra Network- 5/ 79 69 A technical problem occurred. We are not able to process your request. 141 The risk analyzer rejected this transaction. 70 Invalid country code. 142 The used type of card is not valid for the requested payment mode. 71 Invalid web service parameter. Systempay – Implementation Guide – webservices V4 @Lyra Network- 6/ 79 Specification about TransactionInfo error codes 0 Action successfully completed This means that the request has been processed with success and therefore that the request's format is correct. Note: In case of a payment creation (create and createWithThreeDS() method) this error code must not be mistaken with the transactionStatus field which returns the payment result. It is indeed possible to get a 0 errorCode and an 8 transactionStatus. This case matches with a transaction creation which authorization request has been declined. 1 Unauthorized request You do not have access to web services. Please contact Systempay support. 15 Unknown contract number Something is wrong with the merchant's contract. Several cases are possible: The value contained in the request does not match with any contract associated with the shop (siteId), There is no contract associated with the shop, The contract is closed, The type of contract is not allowed to process the payment. Occurs when your merchant account doesn’t support CNP (card-not-present) transactions and the value of the field paymentSource is either MOTO, CC or OTHER in your payment request. 27 Amount not authorized The amount you want to debit or refund, doesn’t match with your merchant account specifications (such as minimal and maximum amount allowed per transaction). Please contact Systempay support for more informations. Specification about veResPAReqInfo error codes 9 technical error This error code can be returned in several cases. Most frequently, the contract number (createCardInfo.contractNumber) provided in your request is invalid. Please contact Systempay support to obtain more details. Systempay – Implementation Guide – webservices V4 @Lyra Network- 7/ 79 4. Data Types definitions Data Types are used to form a message type and either be populated by merchant (request) or by PayZen (Response). Data Representation Notations indicates how data is represented. Data Representation Notations Description a n s Alphabetic characters A--Z and a--z Numeric digit 0-9 Special character Alphabetic and numeric characters (excluding space and special characters) Alphabetic, numeric, space and special characters an ans Data Length Notations indicates the format of the data length. Data length Notations Description digit …digit(s) Fixed length in number of positions Variable length, with maximum number of positions specified. Data types boolean dateTime Description A Boolean data type can only have one of two values: true or false. These values can also be represented as true, yes, or 1 (one), or false, no, or 0 (zero). A dateTime data type represents a specific moment in time as both a date and a time. It contains a year, a month, and a date, and also hours, seconds, and milliseconds. The value is in the Coordinated Universal Time (UTC). Unlike local time, any given date and time in UTC is the same everywhere on earth simultaneously. Int An int (integer) data type is a whole number without a decimal point or any value that would follow a decimal point. For example, 1 is an integer. However, 1.0 and 1. are not integers. Long The long data type is a 64-bit signed two's complement integer. This data type is used when the int data type is not large enough (to specify transaction amount for example). String The string data type can contain characters, line feeds, carriage returns, and tab characters. Systempay – Implementation Guide – webservices V4 @Lyra Network- 8/ 79 5. Maintain HTTP session Important: As the payment platform architecture works with load balanced servers, on a short time interval it is necessary that every request concerning the same payment are processed on the same HTTP session in order to keep the process' continuity. To do so, for each request a session is created by the server. The session ID is sent back in the HTTP header of the response. It has to be sent back within the following requests in order that they can be processed by the same server. JAVA code sample Use the SESSION_MAINTAIN_PROPERTY property and make sure to set it to true in order to maintain the session. Service service = Service.create(wsdlURL, qname); ThreeDSecure port = service.getPort(ThreeDSecure.class); ((BindingProvider) port).getRequestContext().put(BindingProvider.SESSION_MAINTAIN_PROPERTY, true); PHP code sample First of all, you need to get the SESSION ID sent back in the response of the first call. Use the __getLastResponseHeader method and save the cookie named JSESSIONID. Then use the __setCookie method to add the JSESSIONID cookie in the header of each call of a series of API calls. /* Get all the response headers */ $header = $client->__getLastResponseHeaders(); /* Find the « JSESSIOND » field : */ if(!preg_match("#JSESSIONID=([A-Za-z0-9\._]+)#",$header, $matches)){ return "NO SESSIONID SENT BY THE SERVER." ; //technical error } $cookie = $matches[1]; /*Add a new cookie in the header of the next request */ $client->__setCookie ("JSESSIONID", $cookie); We recommend you to store the JSESSIONID in your data base. You will have to send it in your request to finalize the payment after a 3D-Secure authentication. The payer authentication may take a few minutes. Systempay – Implementation Guide – webservices V4 @Lyra Network- 9/ 79 6. Signature computation A certificate is mandatory to communicate with the payment gateway. It is available for every person who have the right to view your shop's certificates. They appear in PayZen's Merchant Back Office in Setting / Shops, Certifcates tab. There are two distinct certificates: one for the test platform and the other for the production platform. The signature is computed as follows: Creation of a string composed of the parameters separated with the "+" symbol. Addition of the "certificate" (test or production depending on the context) to this string. Hash of the final string with the SHA1algorithm. The payment gateway always checks the signature. It is on the merchant's responsibility to check the signature returned by the payment gateway. The order of the fields must be respected. The numerical fields must not have any 0 on the first digit's left. The boolean fields can only take these two values: - 1 for true - 0 for false The string fields that are not valued must be left empties. To simplify the computation, object of class dateTime are not taken in account. ________________________________________________________________________________________________ On TEST mode, if the signature's computation is not correct, the error code returns 5. The string used to compute the signature on the server's side is then returned in the extendedErrorCode field. ________________________________________________________________________________________________ Systempay – Implementation Guide – webservices V4 @Lyra Network- 10/ 79 7. API Use Cases and Examples 7.1. 3D-Secure transaction process Step 1 - Shopper browses at merchant site and finalizes purchase. Step 2 - The merchant invokes a web service (createWithThreeDS request) to the PayZen gateway with the necessary data to process the payment. Step 3 - PayZen sends query including card number to VISA or MASTERCARD Directory Servers. Step 4 - If card number is not participating, PayZen process the authorization request and returns a transactionInfo object to merchant and processing ends. If card number is in a participating card range, Systempay returns a veResPAReqInfo object containing: - the Access Control Server (ACS) URL - the Payer Authentication Request message (PAReq) - the 3DS request ID (threeDSRequestId) Step 5 - The merchant stores in the field MD (merchant data), the session ID (JSESSIONID) transmitted in the HTTP response header, and the 3DS request ID (threeDSRequestId). Step 6 - The merchant initiates a form post (ACS Request) that posts the values retrieved from veResPAReqInfo to the ACS via the shopper’s browser, including the field MD. It is at this stage that the card holder will be prompted for their 3D-Secure PIN code. Step 7 - ACS authenticates shopper as appropriate for the card number then formats the ACS Result message. Step 8 - ACS returns the ACS result (PARes) and the merchant data (MD) to merchant via shopper’s browser. Step 9 - The merchant invokes a web service (finalizeWithThreeDS) to the PayZen gateway with the 3DS request ID (transmitted in the field MD) and the ACS Result (PARes). Step 10 - PayZen validates Payer Authentication Response signature. If successful, PayZen proceeds with authorization exchange with acquirer. Step 11 - PayZen returns a transactionInfo object to merchant and processing ends. Systempay – Implementation Guide – webservices V4 @Lyra Network- 11/ 79 7.2. Create a transaction with 3D-Secure authentication (card enrolled) Verify the cardholder’s enrolment status 1. Create a new createPaymentInfo objet. 2. Populate at least all of the required fields for the paymentGeneralInfo object. 3. Populate at least all of the required fields for the cardInfo object. 4. Populate at least all of the required fields for the extraInfo object. 5. If you need, you can use some optional fields. Refer to the createWithThreeDS method description’s section. 6. Proceed with the signature computation (see below). 7. Call the createWithThreeDS() method, passing in the createPaymentInfo object created in the previous steps and the wsSignature field. 8. Systempay returns a createWithThreeDSReponse object. Check for the value of the errorCode field. o o If the errorCode value is 0, o Get the veResPAReqInfo object from the response. o Get the JSESSIONID cookie from the HTTP headers of the response. o Proceed with the browser redirection to the ACS (refer to next section) If the errorCode value is not 0, then process the errors. Signature computation wsSignature = SHA1(siteId+transactionId+paymentSource+orderId+orderInfo+orderInfo2+orderInfo3 +amount+currency+validationMode+cardNumber+cardNetwork+expiryMonth +expiryYear+cvv+cardIdent+cardBirthDay+contractNumber+paymentOptionCode +subPaymentInfo+custormerInfo+shippingInfo +ctxMode+browesrUserAgent+browserAccept+certificate) wsSignature = SHA1(70258842+420582+EC+cmde-test+++ +12590+978+1+4970100000000009+VISA+12 +2021+111++++ +++ +TEST+++certificate) Systempay – Implementation Guide – webservices V4 @Lyra Network- 12/ 79 SOAP Request example <ns1:createWithThreeDS> <createInfo> <paymentGeneralInfo> <siteId>70258842</siteId> <transmissionDate>2014-03-11T10:40:58+00:00</transmissionDate> <transactionId>420582</transactionId> <paymentSource>EC</paymentSource> <orderId>cmde-test</orderId> <amount>12590</amount> <currency>978</currency> <presentationDate>2014-03-11T10:40:58+00:00</presentationDate> <validationMode>1</validationMode> </paymentGeneralInfo> <cardInfo> <cardNumber>4970100000000009</cardNumber> <cardNetwork>VISA</cardNetwork> <expiryMonth>12</expiryMonth> <expiryYear>2021</expiryYear> <cvv>111</cvv> </cardInfo> <extraInfo> <ctxMode>TEST</ctxMode> </extraInfo> </createInfo> <wsSignature>8696c57d909498c2a0d1b7dbc2daea98c85f346b</wsSignature> </ns1:createWithThreeDS> Response header [Response Header] HTTP/1.1 200 OK Date: Tue, 11 Mar 2014 10:40:58 GMT Server: Apache Set-Cookie: JSESSIONID=2B42D2D1A7A0F34598113A7534D2844A.bdxvad2;Path=/vads-ws;Secure; HttpOnly Access-Control-Allow-Origin: * Vary: Accept-Encoding,User-Agent Connection: close Transfer-Encoding: chunked Content-Type: text/xml;charset=UTF-8 SOAP Response example <ns1:createWithThreeDSResponse xmlns:ns1='http://v4.ws.vads.lyra.com/'> <return> <errorCode>0</errorCode> <timestamp>1394534458504</timestamp> <signature>5e9bc4c4145d59297f7f6a1534629075832c1067</signature> <veResPAReqInfo> <errorCode>0</errorCode> <signature>5755b5cdd881527ed355b917fb6b37db9335ff1f</signature> <timestamp>1394534458504</timestamp> <threeDSAcctId>aee5962cddb048aab650bac6f7d1</threeDSAcctId> <threeDSAcsUrl>https://paiement.systempay.fr:443/vadspayment/acs.interactive_authenticate.a</threeDSAcsUrl> <threeDSBrand>VISA</threeDSBrand> <threeDSEncodedPareq> eJxVUtty4jAM/ZVM3S4OrIBdR2sZaOK+il1s83cGaibYHjXj7gPKKkowV4wL/pfkyxpc+S0AYmlI5FKy0E= </threeDSEncodedPareq> <threeDSEnrolled>Y</threeDSEnrolled> <threeDSRequestId>_c13b0d69-ad0e-4fa1-926f-23cc90b723c0</threeDSRequestId> </veResPAReqInfo> </return> </ns1:createWithThreeDSResponse> Systempay – Implementation Guide – webservices V4 @Lyra Network- 13/ 79 Redirect the cardholder to ACS Once the veResPAReqInfo received, you have to redirect the browser to the ACS by means of a form POST submitted automatically. This form POST is sent to the ACS’s url received in the createWithThreeDS response (threeDSAcsUrl). <form method=”POST” action=”threeDSAcsUrl value”> … </form> It must contain the fields below: Name Data Type Description PaReq String Payer Authentication Request. This is the threeDSEncodedPareq variable in the createWithThreeDS response. (see veResPAReqInfo object) TermUrl String The TermUrl is the url that the card holder will get redirected to once the ACS has completed authentication. (see next section) String ‘Merchant DATA’. In this field, you can send some data needed after the authentication to identify the customer and resume the process. We recommend to populate it with a combination of the JSESSIONID and the threeDSRequestId, separated by a “+” character : “JSESSIONID+requestId“ MD Mandatory Field Note for test mode ONLY In test mode, you have to send the JSESSIONID when redirecting the browser to the ACS’s test URL in order to maintain HTTP session. To do so, you have to add the JSESSIONID to the ACS’s URL, separated by a semi column character as shown below: ${URL};jsessionid=${session} Example: <form name="Form" method="post" action="https://paiement.systempay.fr/vadspayment/acs.silent_authenticate.a;jsessionid=B420BF68835F6563FB6E4B289ABB9080.bdxvad3" > ... </form> When working in LIVE MODE, you MUST NOT SEND the JSESSIONID to the ACS. Systempay – Implementation Guide – webservices V4 @Lyra Network- 14/ 79 Example <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="fr" lang="fr"> <head> <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"/> <title>---</title> <script type="text/javascript"> <!-function submitForm(){ document.redirectForm.submit(); } --> </script> </head> <body onLoad="setTimeout(\'submitForm()'.'\',500);"> <span class="message">redirection ACS</span> <br/> <br/> <br/> <form name="redirectForm" action="acsUrl" method="POST"> <input type="hidden" name="PaReq" value=" threeDSAcsUrl "/> <input type="hidden" name="TermUrl" value="url_de_retour"/> <input type="hidden" name="MD" value="threeDSrequestId " /> <noscript><input type="submit" name="Go" value="Click to continue"/></noscript> </form> </body> </html> Systempay – Implementation Guide – webservices V4 @Lyra Network- 15/ 79 Handle ACS Response Once submitting the Payer authentication request, the ACS server will authenticating the request and redirect to page passed as TermUrl in the above section. On the redirected page, you will find: PaRes : PARes message (Payer Authentication Response) MD : Merchant Data sent in the request You have to extract from the field MD the values of Jsession ID and threeDSrequestId. Pass these values to call finalizeWithThreeDS method (see next section). Example of TermUrl page: In the following example, the field MD consists of the Jsession ID and the request ID, separated by the character “+”. <?php session_start(); ?> <html> <head></head> <body> <?php $PaRes = $_POST['PaRes']; List($JSESSIONID, $requestId) = explode (« + », $_POST['MD']) ; //Initialiaation du client SOAP $client = new soapclient($wsdl,array('trace' =>1)); //Définition du cookie qui sera envoyé avec la requête SOAP $client-> __setCookie('JSESSIONID', $JSESSIONID); finalizeWithThreeDS function call … </body> </html> Systempay – Implementation Guide – webservices V4 @Lyra Network- 16/ 79 Handle the authentication result and complete the transaction 1. Get the PaRes message and the field MD sent to your TermUrl. 2. Extract the value of JSESSIONID and threeDSRequestId form the field MD. 3. Proceed with the signature computation. 4. Set a new cookie called “JSESSIONID” with the value extracted previously and call the finalyzeWithTreeDS() method, passing in threeDSRequestId and pares field. 5. Systempay returns a transactionInfo object. Check for the value of the errorCode field. o If the errorCode value is 0, read the other values returned in the transactionInfo object such as transactionStatusLabel. o If the errorCode value is not 0, then process the errors. Signature computation wsSignature = SHA1(threeDSRequestId+pares+certificate) Request header [Request Header] POST /vads-ws/v4.3 HTTP/1.1 Host: paiement.systempay.fr Connection: Keep-Alive User-Agent: PHP-SOAP/5.4.14 Content-Type: text/xml; charset=utf-8 SOAPAction: "" Content-Length: 5332 Cookie: JSESSIONID=F51526885F7C69B419344A577959C9BA.bdxvad2; SOAP Request example <ns1:finalizeWithThreeDS> <threeDSrequestId>_cc563079-1ac6-48d6-b07d-3eb3618cb0df</threeDSrequestId> <pares>eJzNWdmSzV2XWkt237ljP9DzcTEsDnAgPD/xyxFY58H+BBDAnKg1UFuXBwK/wQdNBdN</pares> <wsSignature>e92d7e22d10076c4e67fbadc631c6a2898c43eac</wsSignature> </ns1:finalizeWithThreeDS> Systempay – Implementation Guide – webservices V4 @Lyra Network- 17/ 79 7.3. Create a transaction without 3D-Secure authentication 1. Create a new paymentCreationInfo objet. 2. Populate at least all of the required fields for the paymentGeneralInfo object. 3. Populate at least all of the required fields for the cardInfo object. 4. Do not populate the threeDsResult object. 5. Populate at least all of the required fields for the extraInfo object. 6. If you need, you can use some optional fields. Refer to the create method description’s section. 7. Proceed with the signature computation (see below). 8. Call the create() method, passing in the paymentCreationInfo object created in the previous steps and the wsSignature field. 9. Systempay returns a transactionInfo object. Check for the value of the errorCode field. o If the errorCode value is 0, read the other values returned in the transactionInfo object such as transactionStatusLabel. o If the errorCode value is not 0, then process the errors. Example This example show how to create a payment without 3D-Secure authentication. validationMode and presentationDate are used as optional fields. threeDsResult, subPaymentInfo, customerInfo, shippingInfo are not populated in the request. Their value in the signature computation will be empty. Signature computation wsSignature = SHA1(siteId+transactionId+paymentSource+orderId+orderInfo+orderInfo2+orderInfo3 +amount+currency+validationMode+cardNumber+cardNetwork+expiryMonth +expiryYear+cvv+cardIdent+cardBirthDay+contractNumber+paymentOptionCode +threeDsResult+subPaymentInfo+custormerInfo+shippingInfo +ctxMode+browesrUserAgent+browserAccept+certificate) wsSignature = SHA1(70258842+361145+EC+cmde-test+++ +12500+978+1+4970100000000009+VISA+12 +2021+111++++ ++++ +TEST+++certificate) Systempay – Implementation Guide – webservices V4 @Lyra Network- 18/ 79 SOAP Example <ns1:create> <createInfo> <paymentGeneralInfo> <siteId>70258842</siteId> <transmissionDate>2014-03-11T09:46:56+00:00</transmissionDate> <transactionId>388160</transactionId> <paymentSource>EC</paymentSource> <orderId>cmde-test</orderId> <amount>12500</amount> <currency>978</currency> <presentationDate>2014-03-13T09:46:56+00:00</presentationDate> <validationMode>1</validationMode> </paymentGeneralInfo> <cardInfo><cardNumber>4970100000000009</cardNumber> <cardNetwork>VISA</cardNetwork> <expiryMonth>12</expiryMonth> <expiryYear>2021</expiryYear> <cvv>111</cvv> </cardInfo> <extraInfo> <ctxMode>TEST</ctxMode> </extraInfo></createInfo> <wsSignature>97fd9257bb87ae03dcf58660b2292ee2e6761558</wsSignature> </ns1:create> Systempay – Implementation Guide – webservices V4 @Lyra Network- 19/ 79 7.4. Create a payment with 3D-Secure handled by merchant’s MPI plugin 1. Create a new paymentCreationInfo objet. 2. Populate at least all of the required fields for the paymentGeneralInfo object. 3. Populate at least all of the required fields for the cardInfo object. 4. Populate at least all of the required fields for the threeDsResult object with the result of the payer authentication performed by the merchant: threeDSBrand threeDSEnrolled threeDSStatus, only if threeDSEnrolled = “Y” threeDSXid, only if threeDSEnrolled = “Y” threeDSEci, only if threeDSEnrolled = “Y” AND threeDSStatus = “Y” or “A” threeDSCavv, only if threeDSEnrolled = “Y” AND threeDSStatus = “Y” or “A” threeDSCavvAlgorithm, only if threeDSEnrolled = “Y” AND threeDSStatus = “Y” or “A” 5. Populate at least all of the required fields for the extraInfo object. 6. If you need, you can use some optional fields. Refer to the create method description’s section. 7. Proceed with the signature computation (see below). 8. Call the create() method, passing in the paymentCreationInfo object created in the previous steps and the wsSignature field. 9. Systempay returns a transactionInfo object. Check for the value of the errorCode field. o If the errorCode value is 0, read the other values returned in the transactionInfo object such as transactionStatusLabel. o If the errorCode value is not 0, then process the errors. Example This example show how to create a payment after the payer has been successfully authenticated by the ACS. validationMode and presentationDate are used as optional fields. subPaymentInfo, customerInfo, shippingInfo are not populated in the request. Their value in the signature computation will be empty. Signature computation wsSignature = SHA1(siteId+transactionId+paymentSource+orderId+orderInfo+orderInfo2+orderInfo3 +amount+currency+validationMode+cardNumber+cardNetwork+expiryMonth +expiryYear+cvv+cardIdent+cardBirthDay+contractNumber+paymentOptionCode +threeDSBrand+threeDSEnrolled+threeDSStatus+threeDSEci+threeDSXid +threeDSCavv+threeDSCavvAlgorithm+subPaymentInfo+custormerInfo+shippingInfo +ctxMode+browesrUserAgent+browserAccept+certificate) wsSignature = SHA1(70258842+706338+EC+cmde-test+++ +12500+978+1+4970100000000009+VISA+12 +2021+111++++ +VISA+Y+Y+05+VXJjeXY0VXZWUjRsWWJaOUo4b3A= +Q2F2dkNhdnZDYXZ2Q2F2dkNhdnY=+2+++ +TEST+++certificate) Systempay – Implementation Guide – webservices V4 @Lyra Network- 20/ 79 SOAP Example <ns1:create> <createInfo> <paymentGeneralInfo> <siteId>70258842</siteId> <transmissionDate>2014-03-10T15:59:54+00:00</transmissionDate> <transactionId>611949</transactionId> <paymentSource>EC</paymentSource> <orderId>cmde-test</orderId> <amount>12500</amount> <currency>978</currency> <presentationDate>2014-03-12T15:59:54+00:00</presentationDate> <validationMode>1</validationMode> </paymentGeneralInfo> <cardInfo> <cardNumber>4970100000000009</cardNumber> <cardNetwork>VISA</cardNetwork> <expiryMonth>12</expiryMonth> <expiryYear>2021</expiryYear> <cvv>111</cvv> </cardInfo> <threeDsResult> <threeDSBrand>VISA</threeDSBrand> <threeDSEnrolled>Y</threeDSEnrolled> <threeDSStatus>Y</threeDSStatus> <threeDSEci>05</threeDSEci> <threeDSXid>VXJjeXY0VXZWUjRsWWJaOUo4b3A=</threeDSXid> <threeDSCavv>Q2F2dkNhdnZDYXZ2Q2F2dkNhdnY=</threeDSCavv> <threeDSCavvAlgorithm>2</threeDSCavvAlgorithm> </threeDsResult> <extraInfo> <ctxMode>TEST</ctxMode> </extraInfo> </createInfo> <wsSignature>fb1c4815471154737d10179cb33b6794e55db905</wsSignature> </ns1:create> Systempay – Implementation Guide – webservices V4 @Lyra Network- 21/ 79 7.5. Update a transaction The following fields are required: • • • • • • • • • • • siteId transmissionDate transactionId sequenceNumber ctxMode amount currency presentationDate validate comment wsSignature SOAP Code <ns1:modify> <siteId>70258842</siteId> <transmissionDate>2013-05-16T08:09:22+00:00</transmissionDate> <transactionId>965805</transactionId> <sequenceNumber>1</sequenceNumber> <ctxMode>TEST</ctxMode> <amount>15800</amount> <currency>978</currency> <presentationDate>2013-05-16T08:09:22+00:00</presentationDate> <validate>true</validate> <comment></comment> <wsSignature>532bfc85fac7b4af69323e9026806b5392019c62</wsSignature> </ns1:modify> Signature computation wsSignature = SHA1(siteId+transactionId+sequenceNumber+ctxMode +amount+currency+validate+comment+certificate) Systempay – Implementation Guide – webservices V4 @Lyra Network- 22/ 79 7.6. Cancel a transaction The following fields are required: • • • • • • • siteId transmissionDate transactionId sequenceNumber ctxMode comment wsSignature Signature computation SHA1 (siteId+transactionId+sequenceNumber+ctxMode+comment+certificate) SOAP Example <ns1:cancel> <siteId>70258842</siteId> <transmissionDate>2014-03-07T14:15:19+00:00</transmissionDate> <transactionId>549195</transactionId> <sequenceNumber>1</sequenceNumber> <ctxMode>TEST</ctxMode> <comment/> <wsSignature>c67470864c0dc0f2dfbfdd28e45c5e4e3b4c6e84</wsSignature> </ns1:cancel> SOAP Example Response <ns1:cancelResponse xmlns:ns1='http://v4.ws.vads.lyra.com/'> <return> <timestamp>1394204107971</timestamp> <signature>37aac278bf5e6f305708aebf7873742a620c2771</signature> <errorCode>0</errorCode> <transactionStatus>9</transactionStatus> </return> </ns1:cancelResponse> Systempay – Implementation Guide – webservices V4 @Lyra Network- 23/ 79 7.7. Refund a transaction The following fields are required: • • • • • • • • • • • siteId transmissionDate transactionId sequenceNumber ctxMode newTransactionId amount currency presentationDate comment wsSignature Signature computation wsSignature = SHA1 (siteId+transactionId+sequenceNumber+ctxMode +newTransactionId+amount+currency+validationMode +comment+certificate) SOAP Example <ns1:refund> <siteId>70258842</siteId> <transmissionDate>2014-03-07T15:21:02+00:00</transmissionDate> <transactionId>594750</transactionId> <sequenceNumber>1</sequenceNumber> <ctxMode>TEST</ctxMode> <newTransactionId>570152</newTransactionId> <amount>90</amount> <currency>978</currency> <presentationDate>2014-03-10T14:50:15+00:00</presentationDate> <validationMode>1</validationMode> <comment>Remboursement partiel</comment> <wsSignature>c6e8cf8b4445e9a8c263d8702861261fb0ef59b0</wsSignature> </ns1:refund> Systempay – Implementation Guide – webservices V4 @Lyra Network- 24/ 79 7.8. Duplicate a transaction The following fields are required: • • • • • • • • • • • • • • • • siteId transmissionDate transactionId sequenceNumber ctxMode orderId orderInfo (can be empty) orderInfo2 (can be empty) orderInfo3 (can be empty) amount currency newTransactionId presentationDate validationMode comment wsSignature Signature computation wsSignature = SHA1(siteId+transactionId+sequenceNumber+ctxMode+orderId+orderInfo +orderInfo2+orderInfo3+amount+currency+newTransactionId+validationMode +comment+certificate) SOAP Example <ns1:duplicate> <siteId>70258842</siteId> <transmissionDate>2014-03-07T14:15:19+00:00</transmissionDate> <transactionId>549195</transactionId> <sequenceNumber>1</sequenceNumber> <ctxMode>TEST</ctxMode> <orderId>cmde-test</orderId> <orderInfo/> <orderInfo2/> <orderInfo3/> <amount>34000</amount> <currency>978</currency> <newTransactionId>625424</newTransactionId> <presentationDate>2014-03-07T16:22:22+00:00</presentationDate> <validationMode>1</validationMode> <comment/> <wsSignature>da962cd70b7121dbedfd6b7a44ac580e66f17614</wsSignature> </ns1:duplicate> Systempay – Implementation Guide – webservices V4 @Lyra Network- 25/ 79 7.9. Retrieve a transaction The following fields are required: • • • • • • siteId transmissionDate transactionId sequenceNumber ctxMode wsSignature Signature computation wsSignature = SHA1 (siteId+transactionId+sequenceNumber+ctxMode+certificate) SOAP Example <ns1:getInfo> <siteId>70258842</siteId> <transmissionDate>2014-03-07T14:15:19+00:00</transmissionDate> <transactionId>549195</transactionId> <sequenceNumber>1</sequenceNumber> <ctxMode>TEST</ctxMode> <wsSignature>e0823f7326d94d09878495bccc2e9e1472ff5ad9</wsSignature> </ns1:getInfo> Systempay – Implementation Guide – webservices V4 @Lyra Network- 26/ 79 7.10. Validate a transaction The following fields are required: • • • • • • • siteId transmissionDate transactionId sequenceNumber ctxMode comment wsSignature Signature computation wsSignature = SHA1 (siteId+transactionId+sequenceNumber+ctxMode+comment+certificate) SOAP Example <ns1:validate> <siteId>70258842</siteId> <transmissionDate>2014-03-07T16:31:15+01:00</transmissionDate> <transactionId>594750</transactionId> <sequenceNumber>1</sequenceNumber> <ctxMode>TEST</ctxMode> <comment/> <wsSignature>2b2a2775b8ddf9525d034ba32dd2313ad9801bd1</wsSignature> </ns1:validate> SOAP Example Response <ns1:validateResponse xmlns:ns1='http://v4.ws.vads.lyra.com/'> <return> <timestamp>1394206294707</timestamp> <signature>05d9f8a28a740df9f55b9b4996997c962a6169ae</signature> <errorCode>0</errorCode> <transactionStatus>4</transactionStatus> </return> </ns1:validateResponse> Systempay – Implementation Guide – webservices V4 @Lyra Network- 27/ 79 8. Methods createWithThreeDS() Use createWithThreeDS() to verify if cardholder participates in 3D-Secure program, and generates the Payer Authentication Request message. If cardholder is not enrolled, PayZen submits a traditional authorization request and create a new transaction. Arguments Name Data Type Description createInfo wsSignature createPaymentInfo String Payment request message Signature (see below) Signature computation Use the following fields in this order: createPaymentInfo.paymentGeneralInfo, createPaymentInfo.cardInfo, createPaymentInfo.subPaymentInfo, createPaymentInfo.customerInfo, createPaymentInfo.shippingInfo, createPaymentInfo.extraInfo Returns Returns a createWithThreeDSResponse object. If the card is enrolled, the response contains a veResPAReqInfo object. Otherwise, the response contains a transactionInfo object. Systempay – Implementation Guide – webservices V4 @Lyra Network- 28/ 79 Mandatory Field finalyzeWithThreeDS() Use finalyzeWithThreeDS() to: return the response from 3D-Secure server, back to the payment gateway complete the transaction Arguments Name Data Type Description threeDSRequestId String This is the threeDSRequestId (extracted from the MD parameter returned from ACS Server) pares String Returned parameter from ACS Server wsSignature String Signature (see below) Mandatory Field Signature computation Use the following fields in this order: threeDSrequestId, pares Returns Returns a transactionInfo object. ________________________________________________________________________________________________ Note : The PARes message can contain newline characters (‘CR’, ‘LF’ ou ‘\r’,’\n’). Some systems replace these characters by a ‘LF’ character in the SOAP message. It is the case in particular in ASP.NET To avoid signature computation problem, we recommend to delete newline characters and white spaces, both finalyzeWithThreeDS request and in the signature computation. This does not alter the integrity of the PARes message. ________________________________________________________________________________________________ Systempay – Implementation Guide – webservices V4 @Lyra Network- 29/ 79 create() Use create() to create: a single payment without 3D-Secure authentication a single payment with 3D-Secure handled by merchant’s MPI plugin a payment by ID without 3D-Secure a payment by ID with 3D-Secure handled by merchant’s MPI plugin. Arguments Name Data Type Description createInfo wsSignature paymentCreationInfo String Payment request message Signature (see below) Signature computation Use the following fields in this order: paymentCreationInfo.paymentGeneralInfo, paymentCreationInfo.cardInfo, paymentCreationInfo.threeDsResult, paymentCreationInfo.subPaymentInfo, paymentCreationInfo.customerInfo, paymentCreationInfo.shippingInfo, paymentCreationInfo.extraInfo Returns Returns a transactionInfo object. Systempay – Implementation Guide – webservices V4 @Lyra Network- 30/ 79 Mandatory Field modify() Use modify() to: modify the amount of a transaction (only with a smaller value) modify the day of capture validate the transaction Transactions must have one of the following statuses (Transaction statuses): AUTHORISED_TO_VALIDATE WAITING_AUTHORISATION_TO_VALIDATE WAITING_AUTHORISATION AUTHORISED This method will return an error: when called with an incorrect value of amount (null, 0, or greater than the original amount), when called with the same values for amount, day of capture and validation mode, as the original values. Arguments Name Data type Description siteId String / n8 transmissionDate dateTime / ans..40 transactionId String / an6 sequenceNumber Int / n..3 ctxMode String Shop ID Date and time of creation of the transaction to be modified, according to the W3C guidelines. E.g. 2012-06-08T08:16:43+00:00 Unique ID of the transaction to modify Sequence number of the transaction to be modified. Values: 1 for a single payment. The number of term in the case of an installment payment Indicates if the request is made in test mode or live mode. (Expected value: “TEST” or “PRODUCTION”) Transaction amount. Positive integer, smallest possible unit per currency (for euro, we’re calculating the amount in cents) amount Long / n..12 currency Int / n3 presentationDate dateTime / ans..40 validate bool comment String wsSignature String If you do not wish to modify the amount of the transaction, you have to populate this field with the initial amount value. Currency code according to the ISO 4217 standard (e.g « 978 » for EURO) Defines the day of automatic capture of an authorized payment, according to the W3C guidelines (e.g. 2012-06-08T08:16:43+00:00 Indicates if you want to validate the transaction. 0 = NO, 1 = YES Use this field to record comments about the payment. Signature (see below) Systempay – Implementation Guide – webservices V4 @Lyra Network- 31/ 79 Mandatory Field Signature computation Use the following fields in this order: siteId, transactionId, sequenceNumber, ctxMode, amount, currency, validate, comment Returns Returns a transactionInfo object. Systempay – Implementation Guide – webservices V4 @Lyra Network- 32/ 79 cancel() Use cancel() to cancel definitely a transaction not captured yet. Transactions must have one of the following statuses (Transaction statuses): AUTHORISED_TO_VALIDATE WAITING_AUTHORISATION_TO_VALIDATE WAITING_AUTHORISATION AUTHORISED Arguments Name Data Type Description siteId String / n8 transmissionDate dateTime / ans..40 transactionId String / an6 sequenceNumber Int / n..3 ctxMode String comment String wsSignature String Shop ID Date and time of creation of the transaction to be cancelled, according to the W3C guidelines. E.g. 2012-06-08T08:16:43+00:00 Unique ID of the transaction to cancel Sequence number of the transaction to be cancelled. Values: 1 for a single payment. The number of term in the case of an installment payment Indicates if the request is made in test mode or live mode (Expected value: “TEST” or “PRODUCTION”) Use this field to record comments about the payment. Signature (see below) Signature computation Use the following fields in this order: siteId, transactionId, sequenceNumber, ctxMode, comment Returns Returns a standardResponse object. Systempay – Implementation Guide – webservices V4 @Lyra Network- 33/ 79 Mandatory Field refund() Use refund() to refund a transaction that has previously been captured. You can either refund the full amount of the debit or you can issue a partial refund. You can do so as many times as you wish until the entire transaction has been refunded. Once entirely refunded, a transaction can’t be refunded again. Refund operation may be refused if the credit card expiry date is exceeded. This method will return an error: when called on a transaction that has been not yet captured when called on an already-refunded transaction when trying to refund more money than is left Transactions must have the following statuses (Transaction statuses): • CAPTURED Arguments Name Data Type Description siteId String / n8 Shop ID transmissionDate dateTime / ans..40 Date and time of creation of the transaction to be refunded, according to the W3C guidelines. E.g. 2012-06-08T08:16:43+00:00 transactionId String / an6 sequenceNumber Int / n..3 ctxMode String Indicates if the request is made in test mode or live mode (Expected value: “TEST” or “PRODUCTION”) newTransactionId String / an6 Unique ID of the transaction generated by the merchant. amount Long / n..12 currency Int / n3 presentationDate dateTime / ans..40 validationMode Int / n..1 comment String wsSignature String Unique ID of the transaction to refund (Initial transaction) Sequence number of the transaction to be refunded. Values: 1 for a single payment. The number of term in the case of an installment payment Amount of the refund. Currency code according to the ISO 4217 standard (e.g « 978 » for EURO) Defines the day of automatic capture of an authorized payment, according to the W3C guidelines (e.g. 2012-06-08T08:16:43+00:00 Payment validation mode 0= Automatic ; 1= Manual Use this field to record comments about the payment. Signature (see below) Signature computation Systempay – Implementation Guide – webservices V4 @Lyra Network- 34/ 79 Mandatory Field Use the following fields in this order: siteId, transactionId, sequenceNumber, ctxMode, newTransactionId, amount, currency, validationMode, comment Returns Returns a transactionInfo object. Systempay – Implementation Guide – webservices V4 @Lyra Network- 35/ 79 duplicate() Use duplicate() on an existing transaction to create a new transaction with the same characteristics. Transactions must have one of the following statuses (Transaction statuses): CAPTURED EXPIRED CANCELLED REFUSED Arguments Name Data Type Description siteId String transmissionDate dateTime / ans..40 transactionId String / an6 sequenceNumber Int / n..3 ctxMode String orderId orderInfo orderInfo2 orderInfo3 String / ans..64 String String String Shop ID Date and time of creation of the transaction to be duplicated, according to the W3C guidelines. E.g. 2012-06-08T08:16:43+00:00 Unique ID of the transaction to be duplicated (Initial transaction) Sequence number of the transaction to be duplicated. Values: 1 for a single payment. The number of term in the case of an installment payment Indicates if the request is made in test mode or live mode (Expected value: “TEST” or “PRODUCTION”) Order reference amount Long / n..12 currency Int / n3 newTransactionId String / an6 presentationDate dateTime / ans..40 validationMode Int / n..1 comment String wsSignature String Order description Transaction amount. Positive integer, smallest possible unit per currency (for euro, we’re calculating the amount in cents) Currency code according to the ISO 4217 standard (e.g « 978 » for EURO) Unique ID of the transaction, generated by the merchant. Defines the day of automatic capture of an authorized payment, according to the W3C guidelines (e.g. 2012-06-08T08:16:43+00:00 Payment validation mode 0= Automatic ; 1= Manual Use this field to record comments about the payment. Signature (see below) Systempay – Implementation Guide – webservices V4 @Lyra Network- 36/ 79 Mandatory Field Signature computation Use the following fields in this order: siteId, transactionId, sequenceNumber, ctxMode, orderId, orderInfo, orderInfo2, orderInfo3, amount, currency, newTransactionId, validationMode, comment Returns Returns a transactionInfo object. Systempay – Implementation Guide – webservices V4 @Lyra Network- 37/ 79 getInfo() Use getInfo() to retrieve the data of an existing transaction. Arguments Name Data Type Description siteId String / n8 transmissionDate dateTime / ans..40 transactionId String / an6 sequenceNumber Int / n..3 ctxMode String wsSignature String Shop ID Date and time of creation of the transaction to be retrieved, according to the W3C guidelines. E.g. 2012-06-08T08:16:43+00:00 Unique ID of the transaction to retrieve Sequence number of the transaction to be retrieved. Values: 1 for a single payment. The number of term in the case of an installment payment Indicates if the request is made in test mode or live mode (Expected value: “TEST” or “PRODUCTION”) Signature (see below) Signature computation Use the following fields in this order: siteId, transactionId, sequenceNumber, ctxMode Returns Returns a transactionInfo object. Systempay – Implementation Guide – webservices V4 @Lyra Network- 38/ 79 Mandatory Field validate() Use validate() to allow the automatic capture of a transaction to be launched at the day specified in the payment creation request. Transactions must have one of the following statuses (Transaction statuses): AUTHORISED_TO_VALIDATE WAITING_AUTHORISATION_TO_VALIDATE Arguments Name Data Type Description siteId String / n8 transmissionDate dateTime / ans..40 transactionId String / an6 sequenceNumber Int / n..3 ctxMode String comment String wsSignature String Shop ID Date and time of creation of the transaction to be validated, according to the W3C guidelines. E.g. 2012-06-08T08:16:43+00:00 Unique ID of the transaction to be validated Sequence number of the transaction to be validated. Values: 1 for a single payment. The number of term in the case of an installment payment Indicates if the request is made in test mode or live mode (Expected value: “TEST”,“PRODUCTION”) Use this field to record comments about the payment. Signature (see below) Signature computation Use the following fields in this order: siteId, transactionId, sequenceNumber, ctxMode, comment Returns Returns a standardResponse object. Systempay – Implementation Guide – webservices V4 @Lyra Network- 39/ 79 Mandatory Field force() Deprecated. Systempay – Implementation Guide – webservices V4 @Lyra Network- 40/ 79 9. Objects createPaymentInfo Definition Represents a payment request. It is used for the createWithThreeDS function calls. Properties Name Data Type Description paymentGeneralInfo cardInfo subPaymentInfo customerInfo shippingInfo extraInfo createPaymentGeneralInfo createCardInfo createSubPaymentInfo createCustomerInfo createShippingInfo createExtraInfo Characteristics of the transaction Credit card information Reserved for future use Details about the customer Details about delivery Extra information Signature computation Use the following fields in this order: paymentGeneralInfo, cardInfo, subPaymentInfo, customerInfo, shippingInfo, extraInfo Systempay – Implementation Guide – webservices V4 @Lyra Network- 41/ 79 Mandatory Field createPaymentGeneralInfo Definiton Contains the transaction’s characteristics. Properties Name Data Type Description siteId String / n8 transmissionDate dateTime / ans..40 transactionId String / an6 paymentSource string Shop ID. UTC date and time of the transaction according to the W3C guidelines (e.g. 2012-06-08T08:16:43+00:00). Represents the date and time of the request. If the value of this field is too far from the current UTC time, the request will be rejected. (errorCode 6) 6 digit number representing the transaction ID. Must be unique on a same day (from 00h00:00 UTC to 23h59:59UTC). Origin of the payment: - EC: E-commerce - MOTO : mail or phone order - CC : call center - OTHER : other channel of sale orderId orderInfo orderInfo2 orderInfo3 String / an..64 String / an..255 String / an..255 String / an..255 amount Long / n..12 currency Int / n3 Note : EC must be used to make transactions with 3D-Secure authentication. Order reference Order description Transaction amount. Positive integer, smallest possible unit per currency (for euro, we’re calculating the amount in cents) Currency code according to the ISO 4217 standard (e.g « 978 » for EURO) Defines the day of automatic capture of an authorized payment, according to the W3C guidelines (e.g. 201206-08T08:16:43+00:00 When the date of capture is greater than the validity period of the authorization request, a pre-authorization request is performed for an amount of 1 euro in order to check the credit card validity. presentationDate dateTime / ans..40 For example, in France, the validity period of the authorization request is: 7 days for VISA, MasterCard, CB, American Express cards 30 days for MAESTRO cards The authorization for the global amount will be processed between 7 and 0 days before the date of capture, depending on your shop setting (with or without anticipated authorization). Systempay – Implementation Guide – webservices V4 @Lyra Network- 42/ 79 Mandatory Field validationMode Int / n..1 If you want to be notified of this authorization request result, you have to activate the Instant Payment Notification rule named “URL serveur sur autorisation par batch” from the Systempay portal (Menu Setting/Notification rules) Payment validation mode 0= Automatic ; 1= Manual Signature computation Use the following fields in this order: createPaymentGeneralInfo.siteId, createPaymentGeneralInfo.transactionId, createPaymentGeneralInfo.paymentSource, createPaymentGeneralInfo.orderId, createPaymentGeneralInfo.orderInfo, createPaymentGeneralInfo.orderInfo2, createPaymentGeneralInfo.orderInfo3, createPaymentGeneralInfo.amount, createPaymentGeneralInfo.currency, createPaymentGeneralInfo.validationMode Systempay – Implementation Guide – webservices V4 @Lyra Network- 43/ 79 createCardInfo Contains all necessary data of the card presented for the purchase. Properties Name Data Type cardNumber string cardNetwork string expiryMonth Int / n..2 expiryYear Int / n4 cvv string Description Mandatory Field The card number, as string without any separators Card type used ("AMEX", "CB", "MASTERCARD", "VISA", "MAESTRO", "E-CARTEBLEUE", "JCB") 1-12 digit number representing the card's expiration month (e.g. 3 for March, 10 for October) Four digit number representing the card's expiration year (e.g. 2023) 3-4 digit representing the security code of the card. Some cards do not have a security code, so the security code is optional in createWithTreeDS and create methods. This field is required when the card has a security code and when the customer entered it. This field is required for payment by ID. cardIdent string Identifier of the customer account (payment created by ID) In case of a payment created by ID, this field is mandatory and must contain an existing ID (errorCode 17) In other cases this field mustn’t be sent (errorCode 22) cardBirthDay dateTime / ans..40 Date of birth of the customer. contractNumber string paymentOptionCode string Merchant ID If this field is filled, make sure to use the right contract depending on the card's network. For example, the VISA contract can’t be used for an AMEX transaction. Reserved for future use Signature computation Use the following fields in this order: createCardInfo.cardNumber, createCardInfo.cardNetwork, createCardInfo.expiryMonth, createCardInfo.expiryYear, createCardInfo.cvv, createCardInfo.cardBirthDay, createCardInfo.cardIdent, createCardInfo.contractNumber, createCardInfo.paymentOptionCode Systempay – Implementation Guide – webservices V4 @Lyra Network- 44/ 79 createSubPaymentInfo Reserved for future use. ________________________________________________________________________________________________ subPaymentInfo mustn’t be populated in the request. Its value in the signature computation must be empty. ________________________________________________________________________________________________ Properties Name Data Type Description subPaymentType subReference subPaymentNumber int string int Do not populate. Signature computation Use the following fields in this order: createSubPaymentInfo.subPaymentType, createSubPaymentInfo.subReference, createSubPaymentInfo.subPaymentNumber Systempay – Implementation Guide – webservices V4 @Lyra Network- 45/ 79 Mandatory Field createCustomerInfo Definition Contains the customer’s information. Properties Name Data Type customerId String / an..80 customerTitle customerStatus customerCountry String / ans..80 custStatus String / ans..128 String / ans..32 String / ans..150 String / an..5 String / ans..255 String / ans..127 String / an..64 String / ans..128 String / ans..128 String / ans..40 language String / a2 customerIP string customerSendEmail Boolean customerCellPhone extInfo String / ans..32 extInfo[] customerName customerPhone customerEmail customerAddressNumber customerAddress customerDistrict customerZip customerCity customerState Description Mandatory Field Customer ID (i.e. his reference in the merchant site) Title Type of customer Customer name Customer phone number Customer e-mail address Billing address number Billing address street Billing address district Billing address Postal code/zip code Billing address city Billing address state Billing address country Customer language (ISO 639-1 standard - 2 letters). IP address of the customer’s browser Send payment confirmation by e-mail to the customer. 0= No ; 1=Yes. Customer mobil phone number An array of extInfo(key;value) Signature computation Use the following fields in this order: createCustomerInfo.customerId, createCustomerInfo.customerTitle, createCustomerInfo.customerStatus, createCustomerInfo.customerName, createCustomerInfo.customerPhone, createCustomerInfo.customerEmail, createCustomerInfo.customerAddressNumber, createCustomerInfo.customerAddress, createCustomerInfo.customerDistrict createCustomerInfo.customerZip, createCustomerInfo.customerCity, createCustomerInfo.customerCountry, createCustomerInfo.language, createCustomerInfo.customerIP, createCustomerInfo.customerSendEmail, createCustomerInfo.customerCellPhone, createCustomerInfo.extInfo Note: customerState mustn’t be included the signature computation. Systempay – Implementation Guide – webservices V4 @Lyra Network- 46/ 79 createShippingInfo Definition Contains the customer’s shipping address details. Properties Name Data Type Description shippingStatus custStatus String / ans..128 String / ans..32 Type of customer The customer’s shipping name shippingName shippingPhone String / an..5 shippingStreetNumber shippingStreet String / ans..128 shippingStreet2 String / ans..128 shippingDistrict shippingZipCode shippingCity shippingState shippingCountry shippingDeliveryCompanyName shippingSpeed shippingType String / ans..127 String / ans..64 String / ans..128 String / ans..128 String / ans..128 String / ans..128 deliverySpeed deliveryType Mandatory Field The customer’s shipping phone number The customer’s shipping address number The customer’s shipping address The customer’s shipping address, line 2 The customer’s shipping disctrict The customer’s shipping zip The customer’s shipping city The customer’s shipping state The customer’s shipping country Name of the delivery company Shipping method’s speed Shipping method Signature computation Use the following fields in this order: createShippingInfo.shippingCity, createShippingInfo.shippingCountry, createShippingInfo.shippingDeliveryCompanyName, createShippingInfo.shippingName, createShippingInfo.shippingPhone, createShippingInfo.shippingSpeed, createShippingInfo.shippingState, createShippingInfo.shippingStatus, createShippingInfo.shippingStreetNumber, createShippingInfo.shippingStreet, createShippingInfo.shippingStreet2, createShippingInfo.shippingDistrict, createShippingInfo.shippingType, createShippingInfo.shippingZipCode Systempay – Implementation Guide – webservices V4 @Lyra Network- 47/ 79 createExtraInfo Definition Contains extra info such as the mode, the browser’s user Agent of the customer … Properties Name Data Type ctxMode string browserUserAgent string browserAccept string Description Mandatory Field Indicates if the request is made in test mode or live mode (Expected value: “TEST” or “PRODUCTION”) The User-Agent request-header field, following standard HTTP/1.1 (RFC. 2616) The HTTP Accept request-header field , following standard HTTP/1.1 (RFC. 2616) Signature computation Use the following fields in this order: createExtraInfo.ctxMode, createExtraInfo.browserUserAgent, createExtraInfo.browserAccept Systempay – Implementation Guide – webservices V4 @Lyra Network- 48/ 79 paymentCreationInfo Definition Represents a payment request. It is used for the create function call. Properties Name Data Type Description paymentGeneralInfo cardInfo threeDsResult subPaymentInfo customerInfo shippingInfo extraInfo createPaymentGeneralInfo createCardInfo threeDSResult createSubPaymentInfo createCustomerInfo createShippingInfo createExtraInfo Characteristics of the transaction Credit card information Result of the 3D-S process Reserved for future use Details about the customer Details about delivery Extra information Mandatory Field Signature computation Use the following fields in this order: paymentGeneralInfo, cardInfo, threeDsResult, subPaymentInfo, customerInfo, shippingInfo, extraInfo Systempay – Implementation Guide – webservices V4 @Lyra Network- 49/ 79 threeDsResult Definition Contains the result of the payer authentication performed by the merchant. Properties Name Data Type Description threeDSBrand string threeDSEnrolled string threeDSStatus string threeDSEci threeDSXid threeDSCavv string string string threeDSCavvAlgorithm string Card brand ("VISA" or "MASTERCARD") Verify Enrollment Response : "Y" : Authentication available, cardholder is enrolled "N" : Cardholder not participating, cardholder is not enrolled "U" : Unable to authenticate or card not eligible for attempts (e.g. commercial or prepaid card) Transaction Status relating to payment authentication results: "Y" : Successful cardholder authentication "N" : Failed cardholder authentication "U" : ACS unable to perform payment authentication "A" : Proof of Attempt occurred and authentication could not be performed Electronic Commerce Indicator Unique transaction reference Cardholder Authentication Verification Value Algorithm used by the ACS to generate the cavv value : "0" : HMAC "1" : CVV "2" : CVV_ATN "3" : Mastercard SPA Mandatory Field Signature computation Use the following fields in this order: threeDsResult.threeDSBrand, threeDsResult.threeDSEnrolled, threeDsResult.threeDSStatus, threeDsResult.threeDSEci, threeDsResult.threeDSXid, threeDsResult.threeDSCavv, threeDsResult.threeDSCavvAlgorithm Note: When creating a transaction using the create() method, threeDsResult object is optional. When the merchant performs 3D-Secure process, this object becomes mandatory (even if the authentication is successful or failed). Systempay – Implementation Guide – webservices V4 @Lyra Network- 50/ 79 Case of cards not enrolled (threeDSEnrolled = "N"): The merchant must provide these fields: threeDSBrand, threeDSEnrolled. The other fields (threeDSStatus, threeDSEci, threeDSXid, threeDSCavv, and threeDSCavvAlgorithm) must not be sent. Case of cards enrolled (threeDSEnrolled = "Y"): The merchant must provide this fields: threeDSBrand, threeDSEnrolled, threeDSStatus, threeDSXid. In case of successful authentication (threeDSStatus = "Y" or "A") : threeDSEci, threeDSCavv and threeDSCavvAlgorithm become mandatory. In case of failed authentication (threeDSStatus = "N" or "U") : threeDSEci, threeDSCavv and threeDSCavvAlgorithm mustn’t be sent. Case of unknown enrollment status (threeDSEnrolled = "U"): The merchant must provide these fields: threeDSBrand, threeDSEnrolled. ThreeDSStatus, threeDSEci, threeDSXid, threeDSCavv, and threeDSCavvAlgorithm) mustn’t be sent. Systempay – Implementation Guide – webservices V4 @Lyra Network- 51/ 79 custStatus Values used to define a customer. Name Description Private customer Company PRIVATE COMPANY deliverySpeed Values used to define the shipping method’s speed. Name Description Standard shipping Express shipping STANDARD EXPRESS deliveryType Values used to define the shipping method. Name RECLAIM_IN_STATION PACKAGE_DELIVERY_COMPANY Description Pick-up the order in store Use of a pick-up point network (i.e Kiala, Alveol, etc.) Pick-up in a station (airport, train station, travel agency) Delivery company (La poste, Colissimo, UPS, DHL…) ETICKET E-ticket or downloadable product RECLAIM_IN_SHOP RELAY_POINT extInfo Definition Use this extra field to persist informations in the transaction details (e.g : items of the shopping cart etc.). Properties Field key value Data type string string Description Data name Data value Signature computation Use the following fields in this order: extInfo.key, extInfo.value Systempay – Implementation Guide – webservices V4 @Lyra Network- 52/ 79 createWithThreeDSResponse Definition The createWithThreeDSResponse message response is sent in response to a createWithThreeDS function call. Properties Name errorCode Data Type int extendedErrorCode string timestamp signature long string veResPAReqInfo veResPAReqInfo transactionInfo transactionInfo Description Error Handling Extra information about error code when errorCode is different from 0 Timestamp Response signature (see below) This field is returned only if the card is enrolled: threeDSEnrolled = « Y » (in this case the transactionInfo field is not sent). It contains the encoded PaReq message. See veResPAReqInfo definition 0 Description of the transaction. See 0 If threeDSEnrolled = « Y », this field is not returned. Signature computation Use the following fields in this order: errorCode, extendedErrorCode, timestamp, veResPAReqInfo, transactionInfo The errorCode value present in the response will match with: the veResPAReqInfo table (see Error codes), when the veResPAReqInfo field is returned, the transactionInfo table (see Error codes), when the transactionInfo field is returned. Systempay – Implementation Guide – webservices V4 @Lyra Network- 53/ 79 veResPAReqInfo The veResPAReqInfo object contains all necessary data to perform the payer authentication request. Properties Name errorCode errorDetail signature timestamp Type int string string long threeDSAcctId String threeDSAcsUrl threeDSBrand threeDSEncodedPareq String String String threeDSEnrolled String threeDSRequestId String Description Error Handling Extra information about the error when errorCode is different from 0 Signature for the veResPAReqInfo object (see below) Timestamp Account Identifier provided by the Directory Server and useful for the ACS the Access Control Server (ACS) URL Card brand Payer authentication message (PAReq) Payer enrollment status : • « Y »: Enrolled 3DS request ID used in the finalizeWithThreeDS() method Signature computation Use the following fields in this order: errorCode, errorDetail, timestamp, threeDSAcctId , threeDSAcsUrl, threeDSBrand, threeDSEncodedPareq, threeDSEnrolled threeDSRequestId Systempay – Implementation Guide – webservices V4 @Lyra Network- 54/ 79 transactionInfo Definition The transactionInfo object defines all the characteristics of a transaction. Properties Name errorCode Data Type int extendedErrorCode string transactionStatus timestamp signature transactionStatusLabel paymentGeneralInfo cardInfo threeDSInfo authorizationInfo markInfo int long string String transactionPaymentGeneralInfo transactionCardInfo transactionThreeDSInfo transactionAuthorizationInfo transactionMarkInfo warrantyDetailsInfo transactionWarrantyDetailsInfo captureInfo customerInfo shippingInfo extraInfo paymentOptionInfo boletoInfo transactionCaptureInfo transactionCustomerInfo transactionShippingInfo transactionExtraInfo transactionPaymentOptionInfo transactionBoletoExtraInfo Description Error Handling Extra information about the error when errorCode is different from 0 Transaction status. Deprecated Timestamp Signature for the transactionInfo object Characteristics of the transaction Credit card information Result of the 3D-S process Details about authorization request Details about pre-authorization request Information about Liability Shift and risk management controls. Information about the capture Details about the customer Details about delivery Extra information Reserved for future use Reserved for future use Signature computation Use the following fields in this order: transactionInfo.errorCode, transactionInfo.extendedErrorCode, transactionInfo.transactionStatus, transactionInfo.timestamp, transactionInfo.paymentGeneralInfo, transactionInfo.cardInfo, transactionInfo.threeDSInfo, transactionInfo.authorizationInfo, transactionInfo.markInfo, transactionInfo.warrantyDetailsInfo, transactionInfo.captureInfo, transactionInfo.customerInfo, transactionInfo.shippingInfo, transactionInfo.extraInfo, transactionInfo.transactionStatusLabel Systempay – Implementation Guide – webservices V4 @Lyra Network- 55/ 79 transactionPaymentGeneralInfo Definition The transactionPaymentGeneralInfo object contains information about a transaction. Properties Name siteId Data Type string paymentSource string orderId orderInfo orderInfo2 orderInfo3 string string string string transmissionDate dateTime transactionId sequenceNumber string int amount string initialAmount string currency int effectiveAmount string effectiveCurrency int presentationDate dateTime type multiplePayment effectiveCreationDate int int dateTime Description Shop ID Origin of the payment : - "E_COMMERCE" : e-Commerce - "MAIL_OR_TELEPHONE" : Mail or phone order - "CALL_CENTER" : call center - "OTHER" : other channel of sale Order reference. Returned unchanged from the request Order description. Returned unchanged from the request Order description. Returned unchanged from the request Order description. Returned unchanged from the request UTC date and time of the transaction according to the W3C guidelines (e.g. 2012-06-08T08:16:43+00:00). Transaction ID Sequence number of the transaction Actual transaction amount, in the smallest possible unit per currency Initial transaction amount (before any modification, in the smallest possible unit per currency ISO 4217 formatted currency code (e.g « 978 » for EURO) Exchange value of the amount, in the smallest possible unit per currency Exchange value of the currency (ISO 4217 formatted currency code) Bank settlement date when the funds will be settled into the merchant’s account Operation type : 0 = DEBIT, 1 = CREDIT Installment payment : 0=No, 1= Yes UTC date and time of the record of the transaction Signature computation Use the following fields in this order: transactionPaymentGeneralInfo.siteId, transactionPaymentGeneralInfo.paymentSource, transactionPaymentGeneralInfo.orderId, transactionPaymentGeneralInfo.orderInfo, transactionPaymentGeneralInfo.orderInfo2, transactionPaymentGeneralInfo.orderInfo3, transactionPaymentGeneralInfo.transactionId, transactionPaymentGeneralInfo.sequenceNumber, transactionPaymentGeneralInfo.amount, transactionPaymentGeneralInfo.initialAmount, transactionPaymentGeneralInfo.currency, transactionPaymentGeneralInfo.effectiveAmount, transactionPaymentGeneralInfo.effectiveCurrency, transactionPaymentGeneralInfo.type, transactionPaymentGeneralInfo.multiplePayment, Systempay – Implementation Guide – webservices V4 @Lyra Network- 56/ 79 transactionCardInfo Definition The transactionCardInfo object defines the card details. Properties: Name Data Type cardNumber string cardNetwork cardBrand cardCountry cardProductCode cardBankCode string string long string string expiryMonth int expiryYear int contractNumber string Description Truncated credit card number. Contains first 6 digits of the card number, followed by “XXXXXX” and then the last 4 digits of the card number. Card network Card brand ISO 3166-1 Country code of the card. Bank product of the card Bank code of the issuer 1-12 digit number representing the card's expiration month (e.g. 3 for March, 10 for October) Four digit number representing the card's expiration year (e.g. 2023) Merchant ID Signature computation Use the following fields in this order: transactionCardInfo.cardNumber, transactionCardInfo.cardNetwork, transactionCardInfo.cardBrand, transactionCardInfo.cardCountry, transactionCardInfo.expiryMonth, transactionCardInfo.expiryYear, transactionCardInfo.contractNumber, transactionCardInfo.cardBankCode, transactionCardInfo.cardProductCode Systempay – Implementation Guide – webservices V4 @Lyra Network- 57/ 79 transactionThreeDSInfo Definition The transactionThreeDSInfo object contains information about the 3D-Secure process such as cardholder authentication result. Properties Data Type Name threeDSEnrolled string threeDSStatus string threeDSEci threeDSXid string string threeDSCavvAlgorithm string threeDSCavv threeDSSignValid threeDSBrand string string string threeDSTransactionCondition string Description Verify Enrollment Response : "Y" : Authentication available, cardholder is enrolled "N" : Cardholder not participating, cardholder is not enrolled "U" : Unable to authenticate or card not eligible for attempts (e.g. commercial or prepaid card) Transaction Status relating to payment authentication results: "Y" : Successful cardholder authentication "N" : Failed cardholder authentication "U" : ACS unable to perform payment authentication "A" : Proof of Attempt occurred and authentication could not be performed Electronic Commerce Indicator Unique transaction reference Algorithm used by the ACS to generate the cavv value : "0" : HMAC "1" : CVV "2" : CVV_ATN "3" : Mastercard SPA Cardholder Authentication Verification Value Signature used to check the pares integrity Card brand ("VISA" or "MASTERCARD") "COND_3D_SUCCESS", "COND_3D_FAILURE", "COND_3D_ERROR", "COND_3D_NOTENROLLED", "COND_3D_ATTEMPT", "COND_SSL" See details below. Systempay – Implementation Guide – webservices V4 @Lyra Network- 58/ 79 Values for threeDSTransactionCondition: Value "COND_3D_SUCCESS" Description Successful cardholder authentication. The cardholder is enrolled and has been authenticated by the issuer. Failed cardholder authentication. " COND_3D_FAILURE" The cardholder is enrolled and fails to correctly enter the authentication information (or cancels authentication page). Authentication could not be performed. " COND_3D_ERROR" Unable to complete the authentication request. An error occurred during the enrollment verification or during the cardholder authentication. Cardholder Not Participating " COND_3D_NOTENROLLED" Cardholder is NOT registered for 3D Secure. Attempt processing performed. " COND_3D_ATTEMPT" The cardholder is enrolled but authentication was not available. A proof the merchant attempted 3D Secure authentication has been generated by the issuer. 3D Secure Not Applicable "COND_SSL" Merchant account is not participating or 3D Secure authentication is not applicable for this form of payment. Signature computation Use the following fields in this order: transactionThreeDSInfo.threeDSTransactionCondition, transactionThreeDSInfo.threeDSEnrolled, transactionThreeDSInfo.threeDSStatus, transactionThreeDSInfo.threeDSEci, transactionThreeDSInfo.threeDSXid, transactionThreeDSInfo.threeDSCavvAlgorithm, transactionThreeDSInfo.threeDSCavv, transactionThreeDSInfo.threeDSSignValid, transactionThreeDSInfo.threeDSBrand Systempay – Implementation Guide – webservices V4 @Lyra Network- 59/ 79 transactionAuthorizationInfo Definition The transactionAuthorizationInfo object defines the details of an authorization request. Properties Name Data Type Description "MARK": A pre-authorization request was performed for an amount of 1 euro in order to check the credit card validity. authMode string This value is returned when the date of capture is greater than the validity period of the authorization request. For example, in France, the validity period of the authorization request is: 7 days for VISA, MasterCard, CB, American Express cards 30 days for MAESTRO cards "FULL": authorization request performed with the global amount. Authorized amount in the smallest unit per currency. Returned when the value of the authMode field is FULL. ISO 4217 currency code of the currency used in the authorization request. Returned when the value of the authMode field is FULL. authAmount string authCurrency string authDate string The date when the authorization request was performed. Returned when the value of the authMode field is FULL. authNumber string The authorization request ID. Returned when the value of the authMode field is FULL. authResult int The bank response code to the authorization request Returned when the value of the authMode field is FULL. authCVV2_CVC2 string Information about verification process of the security code. Signature computation Use the following fields in this order: transactionAuthorizationInfo.authMode, transactionAuthorizationInfo.authAmount, transactionAuthorizationInfo.authCurrency, transactionAuthorizationInfo.authNumber, transactionAuthorizationInfo.authResult, transactionAuthorizationInfo.authCVV2_CVC2 Systempay – Implementation Guide – webservices V4 @Lyra Network- 60/ 79 transactionMarkInfo Definition The transactionMarkInfo object defines the details of a pre-authorization request. Properties Name Data Type Description Authorized amount in the smallest unit per currency. E.g:100 for 1 euro ISO 4217 currency code of the currency used in the authorization request. Returned when the value of the authMode field is MARK. markAmount long markCurrency int markDate dateTime The date when the authorization request was performed. Returned when the value of the authMode field is MARK. markNb string The authorization request ID. Returned when the value of the authMode field is MARK. markResult int The bank response code to the authorization request. Returned when the value of the authMode field is MARK. markCVV2_CVC2 string Information about verification process of the security code. Signature computation Use the following fields in this order: transactionMarkInfo.markAmount, transactionMarkInfo.markCurrency, transactionMarkInfo.markNb, transactionMarkInfo.markResult, transactionMarkInfo.markCVV2_CVC2 Systempay – Implementation Guide – webservices V4 @Lyra Network- 61/ 79 transactionWarrantyDetailsInfo Definition The transactionWarrantyDetailsInfo object defines the details about warranty/ liability shift and contains the results of risk management controls. Properties Name paymentError warrantlyResult localControl litige Data Type int string Array localControl boolean Description Extra information in case of technical error (see paymentError). Payment warranty / Liability shift (YES / NO) Result of risk management controls. Dispute Signature computation Use the following fields in this order: transactionWarrantyDetailsInfo.paymentError, transactionWarrantyDetailsInfo.warrantlyResult, transactionWarrantyDetailsInfo.localControl, transactionWarrantyDetailsInfo.litige Systempay – Implementation Guide – webservices V4 @Lyra Network- 62/ 79 localControl Definition The localControl object defines a risk management control. Properties Name name result Data Type string Boolean Description Name of the risk management rule Result Values for ‘name’: Value "CARD" "COUNTRY" "IPADDR" "AMOUNT" "BIN" " ECB" "CARD_COMMERCIAL_NATIONAL" "CARD_COMMERCIAL_FOREIGN" "CAS" "COUNTRY_CONSISTENCY" "NON_GUARANTEED_PAYMENT" "IPADDR_COUNTRY" Description The card number is recorded in the merchant grey list. The country of the customer is recorded in the merchant grey list. The customer’s IP address is recorded in the merchant grey list. The maximum amount of purchase with this card number has been reached The credit card’s BIN is recorded in the merchant grey list e-carte bleue detected National commercial card detected Foreign commercial card detected Debit card detection The country of origin of the card, the country of the IP address used and the country of the customer do not match. Transaction without warranty / liability shift. The country of the IP address used is recorded in the merchant grey list This list may lengthen, please take it into account in your implementation. Values for ‘result’: Value Description "0" The check is false "1" The check is true Signature computation Use the following fields in this order: localControl.name, localControl.result Systempay – Implementation Guide – webservices V4 @Lyra Network- 63/ 79 transactionCaptureInfo Definition The transactionCaptureInfo object defines the details of the capture, only for captured payment. Properties Name captureDate captureNumber rapprochementStatut Data Type dateTime int int refundAmount long refundCurrency int Description Capture date Capture ID Payment reconciliation status. Total of amount refunded in the smallest possible unit per currency ISO 4217 currency code of the refunded amount. (Code monnaie ISO 4217, Euro : 978) Signature computation Use the following fields in this order: transactionCaptureInfo.captureNumber, transactionCaptureInfo.rapprochementStatut, transactionCaptureInfo.refundAmount, transactionCaptureInfo.refundCurrency Systempay – Implementation Guide – webservices V4 @Lyra Network- 64/ 79 transactionCustomerInfo Definition The transactionCustomerInfo décrit les détails concernant le porteur de la carte : Properties Name customerId customerTitle customerStatus customerName customerPhone customerEmail customerAddressNumber customerAddress customerDistrict customerZip customerCity customerCountry language customerIP customerCellPhone extInfo Data Type string string custStatus string string string string string string string string string string string string extInfo[] Description Customer ID (i.e. his reference in the merchant site) Title Type of customer Customer name Customer phone number Customer e-mail address Billing address number Billing address street Billing address district Billing address Postal code/zip code Billing address city Billing address country Customer language (ISO 639-1 standard - 2 letters). Customer IP Address Customer mobile phone number Array of extInfo Signature computation Use the following fields in this order: transactionCustomerInfo.customerId, transactionCustomerInfo.customerTitle, transactionCustomerInfo.customerStatus, transactionCustomerInfo.customerName, transactionCustomerInfo.customerPhone, transactionCustomerInfo.customerEmail, transactionCustomerInfo.customerAddressNumber, transactionCustomerInfo.customerAddress, transactionCustomerInfo.customerDistrict, transactionCustomerInfo.customerZip, transactionCustomerInfo.customerCity, transactionCustomerInfo.customerCountry, transactionCustomerInfo.language, transactionCustomerInfo.customerIP, transactionCustomerInfo.customerCellPhone, transactionCustomerInfo.extInfo Systempay – Implementation Guide – webservices V4 @Lyra Network- 65/ 79 transactionShippingInfo Definition The transactionShippingInfo object contains information about the delivery: Properties Name shippingCity shippingCountry shippingDeliveryCompanyName shippingName shippingPhone shippingSpeed shippingState shippingStatus shippingStreetNumber shippingStreet shippingStreet2 shippingDistrict shippingType shippingZipCode Data Type string string string string string deliverySpeed string custStatus string string string string deliveryType string Description The customer’s delivery city The customer’s delivery country Name of the delivery company The customer’s delivery name The customer’s delivery phone number Delivery method’s speed The customer’s delivery state Type of customer The customer’s delivery address number The customer’s delivery address The customer’s delivery address, line 2 The customer’s delivery district Delivery method The customer’s delivery zip Signature computation Use the following fields in this order: transactionShippingInfo.shippingCity, transactionShippingInfo.shippingCountry, transactionShippingInfo.shippingDeliveryCompanyName, transactionShippingInfo.shippingName, transactionShippingInfo.shippingPhone, transactionShippingInfo.shippingSpeed, transactionShippingInfo.shippingState, transactionShippingInfo.shippingStatus, transactionShippingInfo.shippingStreetNumber, transactionShippingInfo.shippingStreet, transactionShippingInfo.shippingStreet2, transactionShippingInfo.shippingDistrict, transactionShippingInfo.shippingType, transactionShippingInfo.shippingZipCode Systempay – Implementation Guide – webservices V4 @Lyra Network- 66/ 79 transactionExtraInfo Definition The transactionExtraInfo object contains information about the mode (test or live): Properties Name Data Type ctxMode string Description Indicates if the request is made in test mode or live mode ("TEST", "PRODUCTION") Signature computation Use the following fields in this order: transactionExtraInfo.ctxMode Systempay – Implementation Guide – webservices V4 @Lyra Network- 67/ 79 standardResponse Definition The standardResponse object is returned by the following methods: cancel and validate. Properties Name errorCode extendedErrorCode transactionStatus timestamp signature Data Type int String int long String Description Error Handling Additional information on the error code Timestamp allowing to compute the unique signature Response signature (see below) Signature computation Use the following fields in this order: errorCode, extendedErrorCode, transactionStatus, timestamp Systempay – Implementation Guide – webservices V4 @Lyra Network- 68/ 79 10. Appendices Test credit card numbers These cards will be accepted in our system only for TEST mode. Ensure that the merchant account has been enrolled for 3D Secure by acquiring bank. Otherwise, the payment will be performed without 3D-Secure authentication. Result Number VISA MASTERCARD MAESTRO Successful transaction, successful cardholder authentication. 4970100000000000 5970100300000000 5000550000000000 Payment request with interactive 3D Secure authentication. 4970100000000009 5970100300000009 5000550000000009 Successful transaction, merchant account is not 3D Secure enabled. 4970100000000003 5970100300000003 5000550000000003 Successful transaction, cardholder is not registered for 3D Secure. 4970100000000001 5970100300000001 5000550000000001 Transaction declined. The transaction can be forced. 4970100000000002 5970100300000002 5000550000000002 Successful transaction, with no liability shift. 4970100000000007 5970100300023006 5000550000023006 Transaction declined, failed cardholder authentication. 4970100000000097 5970100300000097 5000550000000097 Transaction declined, insufficient funds available in customer account. 4970100000000098 5970100300000098 5000550000000098 Transaction declined, card security code mismatch. 4970100000000099 5970100300000099 5000550000000099 Expiration date and card security code are free. Systempay – Implementation Guide – webservices V4 @Lyra Network- 69/ 79 Transaction statuses Values for transactionStatusLabel: transactionStatusLabel transactionStatus (deprecated) Description "INITIAL" "0" In progress Reserved for special use. To be validated The transaction was successfully authorized with manual validation. The merchant must allow manually the transaction to be captured. To be validated and authorized: The requested day of capture is greater than the validity period of the authorization request. A pre-authorization request has been sent and accepted by the issuer bank. The merchant must allow manually the transaction to be authorized and captured. "AUTHORISED_TO_VALIDATE" "1" "WAITING_AUTHORISATION_TO_VALIDATE" "3" "AUTHORISED" "4" Waiting for capture : The transaction was successfully authorized and will be automatically captured. "WAITING_AUTHORISATION" "5" Waiting for authorization The requested day of capture is greater than the validity period of the authorization request. A pre-authorization request has been sent and accepted by the issuer bank. The authorization request will be automatically triggered before the day of capture. "CAPTURED" "6" Captured The payment was successfully captured. "EXPIRED" "7" Expired The day of capture has been reached but the merchant did not allow the transaction to be captured. " REFUSED " "8" Declined The payment has been refused. "CANCELLED" "9" Cancelled The payment has been cancelled by the merchant "CAPTURE_FAILED" "13" Failure The capture process has failed. Systempay – Implementation Guide – webservices V4 @Lyra Network- 70/ 79 Bank response code (used for authResult and markResult). Response code 00 02 03 04 05 07 08 12 13 14 15 17 19 20 24 25 26 27 28 29 30 31 33 34 38 41 43 51 54 55 56 57 58 59 60 61 63 68 75 76 90 91 94 96 97 98 99 Response message Approved Refer to card issuer, special condition Invalid Merchant Pick up card Do not Honour Pick-Up card, Special condition Honour with Identification Invalid transaction Invalid amount Invalid card number No such issuer Operator cancelled Re enter transaction Invalid response File update not supported Unable to locate record Duplicate record File update edit error File update file locked File update not successful Format error Bank not supported Expired card, pick-up Suspected fraud, pick-up Pin tries exceeded, pick-up Lost card Stolen card Not sufficient funds (client to contact bank) Expired card Incorrect pin No card record Transaction not permitted to cardholder Transaction not permitted on terminal Suspected fraud Contact Acquirer Exceeds withdrawal limit Security violation Response received too late PIN Tries exceeded Cardholder already in opposition Cut-off in progress Issuer or switch inoperative Duplicate transaction Communication system malfunction Communication error – Cannot connect to FNB Server unavailable, route request sent again Technical error Systempay – Implementation Guide – webservices V4 @Lyra Network- 71/ 79 .Net All optional, value-type properties of an object (such as the Int and bool types) have an additional Boolean property defined with Specified appended to the name. This property is used to tell the XML Serializer whether the corresponding property should be included when generating the XML that will be sent. When deserializing, this property indicates whether the corresponding property was included in the XML. For example, the createPaymentGeneralInfo object has an optional property called validationMode. When the proxy class is generated, a "validationModeSpecified" property will also be created. When sending an object, if you specified a value for "validationMode", you must also set "validationModeSpecified=true". If you do not, the value of "validationMode" will not be serialized and sent to the server. List of optional property Optional property createPaymentGeneralInfo.validationMode createPaymentGeneralInfo.presentationDate createSubPaymentInfo.subPaymentType createSubPaymentInfo.subPaymentNumber createCustomerInfo.customerSendEmail createCardInfo.expiryYear Associated Boolean property createPaymentGeneralInfo.validationModeSpecified createPaymentGeneralInfo.presentationDateSpecified createSubPaymentInfo.subPaymentTypeSpecified createSubPaymentInfo.subPaymentNumberSpecified createCustomerInfo.customerSendEmailSpecified createCardInfo.expiryYearSpecified Systempay – Implementation Guide – webservices V4 @Lyra Network- 72/ 79 PHP Sample code : signature computation (create method) $hashSign=''; $hashSign= /* paymentCreationInfo.paymentGeneralInfo */ getSignatureValue($createInfo->paymentGeneralInfo->siteId). getSignatureValue($createInfo->paymentGeneralInfo->transactionId). getSignatureValue($createInfo->paymentGeneralInfo->paymentSource). getSignatureValue($createInfo->paymentGeneralInfo->orderId). getSignatureValue($createInfo->paymentGeneralInfo->orderInfo). getSignatureValue($createInfo->paymentGeneralInfo->orderInfo2). getSignatureValue($createInfo->paymentGeneralInfo->orderInfo3). getSignatureValue($createInfo->paymentGeneralInfo->amount). getSignatureValue($createInfo->paymentGeneralInfo->currency). getSignatureValue($createInfo->paymentGeneralInfo->validationMode). /* paymentCreationInfo.cardInfo */ getSignatureValue($createInfo->cardInfo->cardNumber). getSignatureValue($createInfo->cardInfo->cardNetwork). getSignatureValue($createInfo->cardInfo->expiryMonth). getSignatureValue($createInfo->cardInfo->expiryYear). getSignatureValue($createInfo->cardInfo->cvv). getSignatureValue($createInfo->cardInfo->cardIdent). getSignatureValue($createInfo->cardInfo->cardBirthDay). getSignatureValue($createInfo->cardInfo->contractNumber). getSignatureValue($createInfo->cardInfo->paymentOptionCode); /* paymentCreationInfo.threeDsResult */ if (!is_null($createInfo->threeDsResult)){ $hashSign .= getSignatureValue($createInfo->threeDsResult->threeDSBrand). getSignatureValue($createInfo->threeDsResult->threeDSEnrolled). getSignatureValue($createInfo->threeDsResult->threeDSStatus). getSignatureValue($createInfo->threeDsResult->threeDSEci). getSignatureValue($createInfo->threeDsResult->threeDSXid). getSignatureValue($createInfo->threeDsResult->threeDSCavv). getSignatureValue($createInfo->threeDsResult->threeDSCavvAlgorithm); } else{ $hashSign .= "+"; } /* paymentCreationInfo.subPaymentInfo */ if (!is_null($createInfo->subPaymentInfo)){ $hashSign .= getSignatureValue($createInfo->subPaymentInfo->subPaymentType). getSignatureValue($createInfo->subPaymentInfo->subReference). getSignatureValue($createInfo->subPaymentInfo->subPaymentNumber); } else{ $hashSign .= "+"; } /* paymentCreationInfo.customerInfo */ if (!is_null($createInfo->customerInfo)){ $hashSign .= getSignatureValue($createInfo->customerInfo->customerId). getSignatureValue($createInfo->customerInfo->customerTitle). getSignatureValue($createInfo->customerInfo->customerStatus). getSignatureValue($createInfo->customerInfo->customerName). getSignatureValue($createInfo->customerInfo->customerPhone). getSignatureValue($createInfo->customerInfo->customerEmail). getSignatureValue($createInfo->customerInfo->customerAddressNumber). getSignatureValue($createInfo->customerInfo->customerAddress). getSignatureValue($createInfo->customerInfo->customerDistrict). getSignatureValue($createInfo->customerInfo->customerZip). Systempay – Implementation Guide – webservices V4 @Lyra Network- 73/ 79 getSignatureValue($createInfo->customerInfo->customerCity). getSignatureValue($createInfo->customerInfo->customerCountry). getSignatureValue($createInfo->customerInfo->language). getSignatureValue($createInfo->customerInfo->customerIP). getSignatureValue($createInfo->customerInfo->customerSendEmail). getSignatureValue($createInfo->customerInfo->customerCellPhone). getSignatureValue($createInfo->customerInfo->extInfo); } else{ $hashSign .= "+"; } /* paymentCreationInfo.shippingInfo */ if (!is_null($createInfo->shippingInfo)){ $hashSign .= getSignatureValue($createInfo->shippingInfo->shippingCity). getSignatureValue($createInfo->shippingInfo->shippingCountry). getSignatureValue($createInfo->shippingInfo->shippingDeliveryCompanyName). getSignatureValue($createInfo->shippingInfo->shippingName). getSignatureValue($createInfo->shippingInfo->shippingPhone). getSignatureValue($createInfo->shippingInfo->shippingSpeed). getSignatureValue($createInfo->shippingInfo->shippingState). getSignatureValue($createInfo->shippingInfo->shippingStatus). getSignatureValue($createInfo->shippingInfo->shippingStreetNumber). getSignatureValue($createInfo->shippingInfo->shippingStreet). getSignatureValue($createInfo->shippingInfo->shippingStreet2). getSignatureValue($createInfo->shippingInfo->shippingDistrict). getSignatureValue($createInfo->shippingInfo->shippingType). getSignatureValue($createInfo->shippingInfo->shippingZipCode); } else{ $hashSign .= "+"; } /* paymentCreationInfo.extraInfo */ $hashSign .= getSignatureValue($createInfo->extraInfo->ctxMode). getSignatureValue($createInfo->extraInfo->browserUserAgent). getSignatureValue($createInfo->extraInfo->browserAccept); /* certificate added */ $hashSign .= $key; Systempay – Implementation Guide – webservices V4 @Lyra Network- 74/ 79 getSignatureValue() description: function getSignatureValue($value){ $signatureValue=''; if (is_null($value)){ $signatureValue .= $value . '+'; } /** * boolean */ if (is_bool($value)){ $signatureValue = ($value ? '1':'0').'+'; } /** * extInfo */ elseif(get_class($value)=='extInfo'){ $signatureValue.= $value->key.'+'.$value->value.'+'; } /** * array */ elseif(is_array($value)){ foreach($value as $name=>$val) { if(is_object($val)) { $signatureValue .= getSignatureValue($val); } } } else { $signatureValue .= $value . '+'; } return $signatureValue; } Systempay – Implementation Guide – webservices V4 @Lyra Network- 75/ 79