Implementation guide Web Services V4. Version 1.4b

(1)

Implementation guide

Web Services V4

(2)

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

(3)

SUMMARY

1. Purpose ... 1

2. Notions of timeout ... 2

3. Error Handling ... 3

4. Data Types definitions ... 8

5. Maintain HTTP session ... 9

6. Signature computation ... 10

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

(4)

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

(5)

Systempay – Implementation Guide – webservices V4 @Lyra Network- 1/79

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.

(6)

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

(7)

Systempay – Implementation Guide – webservices V4 @Lyra Network- 3/ 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 Error Message

Error

0 Action successfully completed 62 Invalid input field ‘orderInfo2’ 1 Unauthorized request 63 Invalid input field ‘orderInfo3’ 2 TransactionID was not found 64 Invalid input field ‘paymentSource’ 3 Bad transaction status 65 Invalid input field ‘cardNetwork’ 4 Transaction already exists 66 Invalid input field ‘contractNumber’ 5 Incorrect signature computation 67 Invalid input field ‘customerId’ 6 TransmissionDate is too far from current

UTC date 68 Invalid input field ‘customerTitle’ 10 Invalid input field ‘amount’ 69 Invalid input field ‘customerName’ 11 Invalid input field ‘currency’ 70 Invalid input field ‘customerPhone’ 12 Unknown card type 71 Invalid input field ‘customerMail’ 13 Invalid input field ‘expiryDate’ 72 Invalid input field ‘customerAddress’ 14 Invalid input field ‘cvv’ 73 Invalid input field ‘customerZipCode’ 15 Unknown contract number 74 Invalid input field ‘customerCity’ 16 Invalid input field ‘cardNumber’ 75 Invalid input field ‘customerCountry’ 17 CardIdent not found 76 Invalid input field ‘customerLanguage’ 18 Invalid cardIdent (cancelled, …) 77 Invalid input field ‘customerIp’

19 SubscriptionID was not found 78 Invalid input field ‘customerSendMail’ 20 Invalid Subscription 79 Invalid input field ‘customerMobilePhone’ 21 CardIdent already exists 80 Invalid input field ‘subPaiementType’ 22 cardIdent creation declined 81 Invalid input field ‘subReference’ 23 cardIdent purged 82 Invalid input field ‘initialAmount’ 26 Nothing has changed 83 Invalid input field ‘occInitialAMount’ 27 Amount not authorized 84 Invalid input field ‘effectDate’ 40 Card range not found 85 Invalid input field ‘state’

50 Invalid input field ‘siteId’ invalide 86 Invalid input field ‘customerAddressNumber’ 51 Invalid input field ‘transmissionDate’ 87 Invalid input field ‘customerDistrict

52 Invalid input field ‘transactionId’ 88 Invalid input field ‘customerState 53 Invalid input field ‘ctxMode’ 90 Invalid input field ‘enrolled’ 54 Invalid input field ‘comment’ 91 Invalid input field ‘authStatus’ 55 Invalid input field ‘AutoNb’ 92 Invalid input field ‘eci’ 56 Invalid input field ‘AutoDate’ 93 Invalid input field ‘xid’ 57 Invalid input field ‘captureDate’ 94 Invalid input field ‘cavv’ 58 Invalid input field ‘newTransactionId’ 95 Invalid input field ‘cavvAlgo’ 59 Invalid input field ‘validationMode’ 96 Invalid input field ‘brand’ 60 Invalid input field ‘orderId’ 98 Invalid input field ‘requestId’ 61 Invalid input field ‘orderInfo1’ 99 Unknown error

(8)

ErrorCode in a veResPAReqInfo object:

Error

Code Description

Error

Code Description

0 Action successfully completed 8 Invalid ACS Signature 1 Unauthorized request 9 Technical error 2 Incorrect signature computation 10 Wrong Parameter

3 Brand not found 11 Incorrect date format

4 Invalid card number 12 3DS Disabled

5 No suitable contract 13 cardIdent not found

6 Ambiguous contract 14 PAN not found

7 Merchant not enrolled 99 Unknown error

PaymentError in a transactionInfo object

Error

1 Transaction not found. 72 #N/A

2 Transaction not found. 73 Pre-authorization declined. 3 This action is not authorized on a transaction

with the status {0}. 74 Invalid payment configuration. 4 This transaction is not authorized in this

context. 75 The operation was declined by Paypal.

5 This transaction already exists. 76 A technical problem occurred. We are not able to process your request.

6 Invalid transaction amount. 77 Following a technical problem, we are not able to process your request.

7 This operation is no longer allowed for a

transaction created on this date. 78 #N/A 8 The card expiry date does not allow this

operation. 79 #N/A

9 CVV is compulsory for this card. 80 #N/A 10 The credit amount is higher than the initial

amount. 81 The content of the configuration theme is not valid. 11 The credit amount is higher than the initial

amount. 82 Refund is not authorized for this contract. 12 The duplication of a refund is not

authorized. 83 Transaction amount outside the allowed values. 13 A technical problem occurred. We are not

able to process your request. 84

A technical problem occurred. We are not able to process your request.

14 A technical problem occurred. We are not

17 The remote setting of the Aurore contract

failed. 88

18 The analysis of the Cetelem response failed. 89 This modification is not authorized.

19 Unknown currency. 90 An error occurred during the refund of this transaction.

20 Invalid type of card. 91 No payment option enabled for this contract. 21

No contract found for this payment. Please change the data or contact your manager in case of multiple failures.

92 #N/A

22 POS not found. 93 #N/A

23 Ambiguous contract. 94 #N/A

24 Invalid contract. 95 A technical problem occurred. We are not able to process your request.

An error occurred during the capture of this transaction.

(9)

able to process your request. 97 #N/A

26 Invalid card number. 98 Invalid transaction date.

27 Invalid card number. 99 #N/A

28 Invalid card number. 100 #N/A

29 Invalid card number. 101 Declined because the first installment has been declined.

30 Invalid card number. (Luhn) 102 The operation was declined by Buyster.

31 Invalid card number. (length) 103 The transaction status failed to be synchronized with the external system

32 Invalid card number. (not found) 104 An error occurred during the capture of this transaction.

33 Invalid card number. (not found) 105 A security error occurred when processing 3DS information for this transaction.

34 Card with unconditional authorization

control failed. 106 Unsupported currency on this contract and/or shop. 35 E-carte bleue control failed. 107 #N/A

36 The risk control has caused a declined

transaction. 108

37 #N/A 109 #N/A

able to process your request. 110 Payment card not supported by the contract. 39 3-D Secure was declined for this transaction. 111 Refusal of transactions without liability shift. 40 A technical problem occurred. We are not

able to process your request. 112 The cancellation is not authorized 41 A technical problem occurred. We are not

able to process your request. 113 Duplication is not permitted

42 #N/A 114 Forcing is not authorized

43 #N/A 115 Refund is not authorized

44 It is not possible to force an imprint 116 MOTO payment is not authorized for this card 45 Invalid currency for this change. 118 Multiple installments are not authorized for this card 46 The amount exceeds the maximum

authorized amount. 119 The date submitted is not valid 47 The presentation date that was requested is

later than the authorization's validity date. 120

The option of payment of the initial transaction is not applicable

48 The required change is not valid. 121 #N/A 49 Invalid definition of multiple installment. 122 #N/A

50 Unknown POS. 123 #N/A

51 Unknown exchange rate. 124 #N/A 52 This contract was closed on {0}. 125 #N/A 53 The shop {0} is closed since {1}. 126 #N/A 54 This parameter that was rejected may

include sensitive data {0}. 128 #N/A 55 A technical problem occurred. We are not

able to process your request. 129 #N/A 57 Problem with the buyer account recovery. 130 #N/A 58 This buyer account is not compatible with

this operation 131 #N/A

59 Problem with the buyer account recovery. 132 A technical problem occurred. We are not able to process your request.

60 This buyer account already exists. 133 #N/A

61 Invalid buyer ID. 134 #N/A

62 Creation of the buyer account declined. 135 The integration of the payment page into an iframe is not authorized.

63 This recurring payment already exists. 136 Refusal of the derived transactions, without liability shift on the primary transaction.

64 This recurring payment is already

terminated. 137 #N/A

65 Invalid recurring payment. 138 #N/A 66 The rule of recurring payment is not valid. 139 #N/A 67 Creation of the recurring payment

(10)

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.

(11)

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.

(12)

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 Alphabetic characters A--Z and a--z

n Numeric digit 0-9

s Special character

an Alphabetic and numeric characters (excluding space and

special characters)

ans Alphabetic, numeric, space and special characters

Data Length Notations indicates the format of the data length. Data length Notations Description

digit Fixed length in number of positions

…digit(s) Variable length, with maximum number of positions specified.

Data types Description

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

dateTime

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.

(13)

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.

(14)

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.

(15)

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.

(16)

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 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) o 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++++

+++

(17)

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/vads-payment/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>

(18)

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 Mandatory

Field

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)

MD 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“

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/vads-payment/acs.silent_authenticate.a;jsessionid=B420BF68835F6563FB6E4B289ABB9080.bdxvad3" > ...

</form>

(19)

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>

function submitForm(){

document.redirectForm.submit(); }

--> </script> </head>

<body onLoad="setTimeout(\'submitForm()'.'\',500);"> <span class="message">redirection ACS</span> <br/>

</body> </html>

(20)

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>

<?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>

(21)

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.

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>

<pares>eJzNWdmSzV2XWkt237ljP9DzcTEsDnAgPD/xyxFY58H+BBDAnKg1UFuXBwK/wQdNBdN</pares> <wsSignature>e92d7e22d10076c4e67fbadc631c6a2898c43eac</wsSignature>

(22)

7.3. Create a transaction without 3D-Secure authentication

1. Create a new paymentCreationInfo objet.

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

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.

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++++

++++

(23)

SOAP Example

<ns1:create> <createInfo>

</paymentGeneralInfo>

</cardInfo> <extraInfo>

(24)

7.4. Create a payment with 3D-Secure handled by merchant’s MPI plugin

1. Create a new paymentCreationInfo objet.

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

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.

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+++

(25)

SOAP Example

<ns1:create> <createInfo>

</paymentGeneralInfo> <cardInfo>

</cardInfo> <threeDsResult>

<threeDSXid>VXJjeXY0VXZWUjRsWWJaOUo4b3A=</threeDSXid> <threeDSCavv>Q2F2dkNhdnZDYXZ2Q2F2dkNhdnY=</threeDSCavv> <threeDSCavvAlgorithm>2</threeDSCavvAlgorithm>

</threeDsResult> <extraInfo>

</createInfo>

(26)

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>

wsSignature = SHA1(siteId+transactionId+sequenceNumber+ctxMode +amount+currency+validate+comment+certificate)

(27)

7.6. Cancel a transaction

• siteId

SHA1 (siteId+transactionId+sequenceNumber+ctxMode+comment+certificate)

SOAP Example

<ns1:cancel>

<wsSignature>c67470864c0dc0f2dfbfdd28e45c5e4e3b4c6e84</wsSignature> </ns1:cancel>

SOAP Example Response

<ns1:cancelResponse xmlns:ns1='http://v4.ws.vads.lyra.com/'> <return>

(28)

7.7. Refund a transaction

• siteId

• newTransactionId • amount

• currency

• presentationDate • comment

• wsSignature

wsSignature = SHA1 (siteId+transactionId+sequenceNumber+ctxMode +newTransactionId+amount+currency+validationMode +comment+certificate)

SOAP Example

<ns1:refund>

<comment>Remboursement partiel</comment>

(29)

7.8. Duplicate a transaction

• siteId

• orderId

• orderInfo (can be empty) • orderInfo2 (can be empty) • orderInfo3 (can be empty) • amount

• currency

• newTransactionId • presentationDate • validationMode • comment • wsSignature

wsSignature = SHA1(siteId+transactionId+sequenceNumber+ctxMode+orderId+orderInfo +orderInfo2+orderInfo3+amount+currency+newTransactionId+validationMode +comment+certificate)

SOAP Example

<ns1:duplicate>

<wsSignature>da962cd70b7121dbedfd6b7a44ac580e66f17614</wsSignature> </ns1:duplicate>

(30)

7.9. Retrieve a transaction

• siteId

• wsSignature

wsSignature = SHA1 (siteId+transactionId+sequenceNumber+ctxMode+certificate)

SOAP Example

<ns1:getInfo>

(31)

7.10. Validate a transaction

• siteId

wsSignature = SHA1 (siteId+transactionId+sequenceNumber+ctxMode+comment+certificate)

SOAP Example

<ns1:validate>

SOAP Example Response

<ns1:validateResponse xmlns:ns1='http://v4.ws.vads.lyra.com/'> <return>

(32)

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

Field

createInfo createPaymentInfo Payment request message

wsSignature String Signature (see below)

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.

(33)

finalyzeWithThreeDS()

Use finalyzeWithThreeDS() to:

return the response from 3D-Secure server, back to the payment gateway complete the transaction

Arguments

Name Data

Type Description

Mandatory Field

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)

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.

(34)

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

Field

createInfo paymentCreationInfo Payment request message

paymentCreationInfo.paymentGeneralInfo, paymentCreationInfo.cardInfo, paymentCreationInfo.threeDsResult, paymentCreationInfo.subPaymentInfo, paymentCreationInfo.customerInfo, paymentCreationInfo.shippingInfo, paymentCreationInfo.extraInfo

Returns

(35)

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 Mandatory

Field

siteId String / n8 Shop ID transmissionDate dateTime /

ans..40

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

transactionId String / an6 Unique ID of the transaction to modify

sequenceNumber Int / n..3

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

ctxMode String Indicates if the request is made in test mode or live mode. (Expected value: “TEST” or “PRODUCTION”)

amount Long / n..12

Transaction amount.

Positive integer, smallest possible unit per currency (for euro, we’re calculating the amount in cents) If you do not wish to modify the amount of the transaction, you have to populate this field with the initial amount value.

currency Int / n3 Currency code according to the ISO 4217 standard (e.g « 978 » for EURO)

presentationDate dateTime / ans..40

Defines the day of automatic capture of an authorized payment, according to the W3C guidelines (e.g. 2012-06-08T08:16:43+00:00

validate bool Indicates if you want to validate the transaction. 0 = NO, 1 = YES

comment String Use this field to record comments about the payment.

(36)

siteId, transactionId, sequenceNumber, ctxMode, amount, currency, validate, comment

Returns

(37)

cancel()

Use cancel() to cancel definitely a transaction not captured yet.

WAITING_AUTHORISATION_TO_VALIDATE WAITING_AUTHORISATION

AUTHORISED

Arguments

Field

siteId String / n8 Shop ID

transmissionDate dateTime / ans..40

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

transactionId String / an6 Unique ID of the transaction to cancel

Sequence number of the transaction to be cancelled.

Values:

ctxMode String

Indicates if the request is made in test mode or live mode

(Expected value: “TEST” or “PRODUCTION”) comment String Use this field to record comments about the

payment.

siteId, transactionId, sequenceNumber, ctxMode, comment

Returns

(38)

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

Field

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 Unique ID of the transaction to refund (Initial transaction)

Sequence number of the transaction to be refunded.

Values:

ctxMode String

(Expected value: “TEST” or “PRODUCTION”) newTransactionId String / an6 Unique ID of the transaction generated by the

merchant.

amount Long / n..12 Amount of the refund. currency Int / n3

Currency code according to the ISO 4217 standard

(e.g « 978 » for EURO) presentationDate dateTime /

ans..40

validationMode Int / n..1 Payment validation mode 0= Automatic ; 1= Manual

(39)

siteId, transactionId, sequenceNumber, ctxMode, newTransactionId, amount, currency, validationMode, comment

Returns

(40)

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

Field

siteId 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

transactionId String / an6 Unique ID of the transaction to be duplicated (Initial transaction)

Sequence number of the transaction to be duplicated.

Values:

ctxMode String

(Expected value: “TEST” or “PRODUCTION”) orderId String / ans..64 Order reference

orderInfo String

Order description orderInfo2 String

orderInfo3 String

amount Long / n..12

Transaction amount.

Positive integer, smallest possible unit per currency (for euro, we’re calculating the amount in cents)

currency Int / n3

Currency code according to the ISO 4217 standard

(e.g « 978 » for EURO)

newTransactionId String / an6 Unique ID of the transaction, generated by the merchant.

validationMode Int / n..1 Payment validation mode 0= Automatic ; 1= Manual

(41)

siteId, transactionId, sequenceNumber, ctxMode, orderId, orderInfo, orderInfo2, orderInfo3, amount, currency, newTransactionId, validationMode, comment

Returns

(42)

getInfo()

Use getInfo() to retrieve the data of an existing transaction.

Arguments

Field

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

transactionId String / an6 Unique ID of the transaction to retrieve

Sequence number of the transaction to be retrieved.

Values:

ctxMode String

(Expected value: “TEST” or “PRODUCTION”) wsSignature String Signature (see below)

siteId, transactionId, sequenceNumber, ctxMode

Returns

(43)

validate()

Use validate() to allow the automatic capture of a transaction to be launched at the day specified in the payment creation request.

WAITING_AUTHORISATION_TO_VALIDATE

Arguments

Field

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

transactionId String / an6 Unique ID of the transaction to be validated

Sequence number of the transaction to be validated.

Values:

ctxMode String

(Expected value: “TEST”,“PRODUCTION”) comment String Use this field to record comments about the

payment.

siteId, transactionId, sequenceNumber, ctxMode, comment

Returns

(44)

force()

(45)

9. Objects

createPaymentInfo

Definition

Represents a payment request. It is used for the createWithThreeDS function calls.

Properties

Field

paymentGeneralInfo createPaymentGeneralInfo Characteristics of the transaction

cardInfo createCardInfo Credit card information

subPaymentInfo createSubPaymentInfo Reserved for future use customerInfo createCustomerInfo Details about the customer shippingInfo createShippingInfo Details about delivery

extraInfo createExtraInfo Extra information

(46)

createPaymentGeneralInfo

Definiton

Contains the transaction’s characteristics.

Properties

Field

siteId String / n8 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) transactionId String / an6

6 digit number representing the transaction ID. Must be unique on a same day (from 00h00:00 UTC to 23h59:59UTC).

paymentSource string

Origin of the payment: - EC: E-commerce

- MOTO : mail or phone order - CC : call center

- OTHER : other channel of sale

Note :

EC must be used to make transactions with 3D-Secure authentication.

orderId String / an..64 Order reference orderInfo String / an..255

Order description orderInfo2 String / an..255

orderInfo3 String / an..255 amount Long / n..12

Transaction amount. Positive integer, smallest possible unit per currency (for euro, we’re calculating the amount in cents)

currency Int / n3 Currency code according to the ISO 4217 standard (e.g « 978 » for EURO)

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.

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

(47)

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) validationMode Int / n..1 Payment validation mode

0= Automatic ; 1= Manual

createPaymentGeneralInfo.siteId, createPaymentGeneralInfo.transactionId, createPaymentGeneralInfo.paymentSource, createPaymentGeneralInfo.orderId, createPaymentGeneralInfo.orderInfo, createPaymentGeneralInfo.orderInfo2, createPaymentGeneralInfo.orderInfo3, createPaymentGeneralInfo.amount, createPaymentGeneralInfo.currency, createPaymentGeneralInfo.validationMode

(48)

createCardInfo

Contains all necessary data of the card presented for the purchase.

Properties

Field

cardNumber string The card number, as string without any separators

cardNetwork string Card type used ("AMEX", "CB", "MASTERCARD", "VISA", "MAESTRO", "E-CARTEBLEUE", "JCB") expiryMonth Int / n..2

1-12 digit number representing the card's expiration month (e.g. 3 for March, 10 for October)

expiryYear Int / n4 Four digit number representing the card's expiration year (e.g. 2023)

cvv string

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

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.

paymentOptionCode string Reserved for future use

createCardInfo.cardNumber, createCardInfo.cardNetwork, createCardInfo.expiryMonth, createCardInfo.expiryYear, createCardInfo.cvv, createCardInfo.cardBirthDay,

createCardInfo.cardIdent, createCardInfo.contractNumber, createCardInfo.paymentOptionCode