Implementation guide Web Services V4 - Version 1.4b - Systempay
←
→
Page content transcription
If your browser does not render page correctly, please read the page content below
Implementation guide
Web Services V4
Version 1.4bConfidentiality
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. 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
transactionThreeDSInfo ............................................................................................................................. 58transactionAuthorizationInfo .................................................................................................................... 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) ............................................................. 731. 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/792. 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/ 793. 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 Error
Error Message Error Message
Code Code
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’
TransmissionDate is too far from current
6 68 Invalid input field ‘customerTitle’
UTC date
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
Systempay – Implementation Guide – webservices V4
@Lyra Network- 3/ 79ErrorCode in a veResPAReqInfo object:
Error Error
Description Description
Code Code
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 Error
Error Message Error Message
Code Code
1 Transaction not found. 72 #N/A
2 Transaction not found. 73 Pre-authorization declined.
This action is not authorized on a transaction
3 74 Invalid payment configuration.
with the status {0}.
This transaction is not authorized in this
4 75 The operation was declined by Paypal.
context.
A technical problem occurred. We are not able to
5 This transaction already exists. 76
process your request.
Following a technical problem, we are not able to
6 Invalid transaction amount. 77
process your request.
This operation is no longer allowed for a
7 78 #N/A
transaction created on this date.
The card expiry date does not allow this
8 79 #N/A
operation.
9 CVV is compulsory for this card. 80 #N/A
The credit amount is higher than the initial
10 81 The content of the configuration theme is not valid.
amount.
The credit amount is higher than the initial
11 82 Refund is not authorized for this contract.
amount.
The duplication of a refund is not
12 83 Transaction amount outside the allowed values.
authorized.
A technical problem occurred. We are not A technical problem occurred. We are not able to
13 84
able to process your request. process your request.
A technical problem occurred. We are not A technical problem occurred. We are not able to
14 85
able to process your request. process your request.
A technical problem occurred. We are not A technical problem occurred. We are not able to
15 86
able to process your request. process your request.
A technical problem occurred. We are not A technical problem occurred. We are not able to
16 87
able to process your request. process your request.
The remote setting of the Aurore contract A technical problem occurred. We are not able to
17 88
failed. process your request.
18 The analysis of the Cetelem response failed. 89 This modification is not authorized.
An error occurred during the refund of this
19 Unknown currency. 90
transaction.
20 Invalid type of card. 91 No payment option enabled for this contract.
No contract found for this payment. Please
21 change the data or contact your manager 92 #N/A
in case of multiple failures.
22 POS not found. 93 #N/A
23 Ambiguous contract. 94 #N/A
A technical problem occurred. We are not able to
24 Invalid contract. 95
process your request.
A technical problem occurred. We are not An error occurred during the capture of this
25 96
able to process your request. transaction.
Systempay – Implementation Guide – webservices V4
@Lyra Network- 4/ 79A technical problem occurred. We are not
25 97 #N/A
able to process your request.
26 Invalid card number. 98 Invalid transaction date.
27 Invalid card number. 99 #N/A
28 Invalid card number. 100 #N/A
Declined because the first installment has been
29 Invalid card number. 101
declined.
30 Invalid card number. (Luhn) 102 The operation was declined by Buyster.
The transaction status failed to be synchronized with
31 Invalid card number. (length) 103
the external system
An error occurred during the capture of this
32 Invalid card number. (not found) 104
transaction.
A security error occurred when processing 3DS
33 Invalid card number. (not found) 105
information for this transaction.
Card with unconditional authorization
34 106 Unsupported currency on this contract and/or shop.
control failed.
35 E-carte bleue control failed. 107 #N/A
The risk control has caused a declined A technical problem occurred. We are not able to
36 108
transaction. process your request.
37 #N/A 109 #N/A
A technical problem occurred. We are not
38 110 Payment card not supported by the contract.
able to process your request.
39 3-D Secure was declined for this transaction. 111 Refusal of transactions without liability shift.
A technical problem occurred. We are not
40 112 The cancellation is not authorized
able to process your request.
A technical problem occurred. We are not
41 113 Duplication is not permitted
able to process your request.
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
The amount exceeds the maximum
46 119 The date submitted is not valid
authorized amount.
The presentation date that was requested is The option of payment of the initial transaction is not
47 120
later than the authorization's validity date. 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
This parameter that was rejected may
54 128 #N/A
include sensitive data {0}.
A technical problem occurred. We are not
55 129 #N/A
able to process your request.
57 Problem with the buyer account recovery. 130 #N/A
This buyer account is not compatible with
58 131 #N/A
this operation
A technical problem occurred. We are not able to
59 Problem with the buyer account recovery. 132
process your request.
60 This buyer account already exists. 133 #N/A
61 Invalid buyer ID. 134 #N/A
The integration of the payment page into an iframe
62 Creation of the buyer account declined. 135
is not authorized.
Refusal of the derived transactions, without liability
63 This recurring payment already exists. 136
shift on the primary transaction.
This recurring payment is already
64 137 #N/A
terminated.
65 Invalid recurring payment. 138 #N/A
66 The rule of recurring payment is not valid. 139 #N/A
Creation of the recurring payment
67 140 #N/A
declined.
Systempay – Implementation Guide – webservices V4
@Lyra Network- 5/ 79A technical problem occurred. We are not
69 141 The risk analyzer rejected this transaction.
able to process your request.
The used type of card is not valid for the requested
70 Invalid country code. 142
payment mode.
71 Invalid web service parameter.
Systempay – Implementation Guide – webservices V4
@Lyra Network- 6/ 79Specification 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/ 794. 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
Alphabetic and numeric characters (excluding space and
an
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
A Boolean data type can only have one of two values: true or false.
boolean
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.
dateTime 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.
An int (integer) data type is a whole number without a decimal point or any value
Int that would follow a decimal point.
For example, 1 is an integer. However, 1.0 and 1. are not integers.
The long data type is a 64-bit signed two's complement integer.
Long This data type is used when the int data type is not large enough (to specify
transaction amount for example).
The string data type can contain characters, line feeds, carriage returns, and tab
String
characters.
Systempay – Implementation Guide – webservices V4
@Lyra Network- 8/ 795. 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/ 796. 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/ 797. 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/ 797.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++++
+++
+TEST+++certificate)
Systempay – Implementation Guide – webservices V4
@Lyra Network- 12/ 79SOAP Request example
70258842
2014-03-11T10:40:58+00:00
420582
EC
cmde-test
12590
978
2014-03-11T10:40:58+00:00
1
4970100000000009
VISA
12
2021
111
TEST
8696c57d909498c2a0d1b7dbc2daea98c85f346b
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
0
1394534458504
5e9bc4c4145d59297f7f6a1534629075832c1067
0
5755b5cdd881527ed355b917fb6b37db9335ff1f
1394534458504
aee5962cddb048aab650bac6f7d1
https://paiement.systempay.fr:443/vads-
payment/acs.interactive_authenticate.a
VISA
eJxVUtty4jAM/ZVM3S4OrIBdR2sZaOK+il1s83cGaibYHjXj7gPKKkowV4wL/pfkyxpc+S0AYmlI5FKy0E=
Y
_c13b0d69-ad0e-4fa1-926f-23cc90b723c0
Systempay – Implementation Guide – webservices V4
@Lyra Network- 13/ 79Redirect 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).
…
It must contain the fields below:
Mandatory
Name Data Type Description
Field
Payer Authentication Request.
This is the threeDSEncodedPareq variable in the
PaReq String
createWithThreeDS response.
(see veResPAReqInfo object)
The TermUrl is the url that the card holder will get redirected
TermUrl String to once the ACS has completed authentication.
(see next section)
‘Merchant DATA’.
In this field, you can send some data needed after the
authentication to identify the customer and resume the
MD String 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:
...
When working in LIVE MODE, you MUST NOT SEND the JSESSIONID to the ACS.
Systempay – Implementation Guide – webservices V4
@Lyra Network- 14/ 79Example
---
redirection ACS
Systempay – Implementation Guide – webservices V4
@Lyra Network- 15/ 79Handle 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 “+”.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
_cc563079-1ac6-48d6-b07d-3eb3618cb0df
eJzNWdmSzV2XWkt237ljP9DzcTEsDnAgPD/xyxFY58H+BBDAnKg1UFuXBwK/wQdNBdN
e92d7e22d10076c4e67fbadc631c6a2898c43eac
Systempay – Implementation Guide – webservices V4
@Lyra Network- 17/ 797.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/ 79SOAP Example
70258842
2014-03-11T09:46:56+00:00
388160
EC
cmde-test
12500
978
2014-03-13T09:46:56+00:00
1
4970100000000009
VISA
12
2021
111
TEST
97fd9257bb87ae03dcf58660b2292ee2e6761558
Systempay – Implementation Guide – webservices V4
@Lyra Network- 19/ 797.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/ 79SOAP Example
70258842
2014-03-10T15:59:54+00:00
611949
EC
cmde-test
12500
978
2014-03-12T15:59:54+00:00
1
4970100000000009
VISA
12
2021
111
VISA
Y
Y
05
VXJjeXY0VXZWUjRsWWJaOUo4b3A=
Q2F2dkNhdnZDYXZ2Q2F2dkNhdnY=
2
TEST
fb1c4815471154737d10179cb33b6794e55db905
Systempay – Implementation Guide – webservices V4
@Lyra Network- 21/ 797.5. Update a transaction
The following fields are required:
• siteId
• transmissionDate
• transactionId
• sequenceNumber
• ctxMode
• amount
• currency
• presentationDate
• validate
• comment
• wsSignature
SOAP Code
70258842
2013-05-16T08:09:22+00:00
965805
1
TEST
15800
978
2013-05-16T08:09:22+00:00
true
532bfc85fac7b4af69323e9026806b5392019c62
Signature computation
wsSignature = SHA1(siteId+transactionId+sequenceNumber+ctxMode
+amount+currency+validate+comment+certificate)
Systempay – Implementation Guide – webservices V4
@Lyra Network- 22/ 797.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
70258842
2014-03-07T14:15:19+00:00
549195
1
TEST
c67470864c0dc0f2dfbfdd28e45c5e4e3b4c6e84
SOAP Example Response
1394204107971
37aac278bf5e6f305708aebf7873742a620c2771
0
9
Systempay – Implementation Guide – webservices V4
@Lyra Network- 23/ 797.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
70258842
2014-03-07T15:21:02+00:00
594750
1
TEST
570152
90
978
2014-03-10T14:50:15+00:00
1
Remboursement partiel
c6e8cf8b4445e9a8c263d8702861261fb0ef59b0
Systempay – Implementation Guide – webservices V4
@Lyra Network- 24/ 797.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
70258842
2014-03-07T14:15:19+00:00
549195
1
TEST
cmde-test
34000
978
625424
2014-03-07T16:22:22+00:00
1
da962cd70b7121dbedfd6b7a44ac580e66f17614
Systempay – Implementation Guide – webservices V4
@Lyra Network- 25/ 797.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
70258842
2014-03-07T14:15:19+00:00
549195
1
TEST
e0823f7326d94d09878495bccc2e9e1472ff5ad9
Systempay – Implementation Guide – webservices V4
@Lyra Network- 26/ 797.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
70258842
2014-03-07T16:31:15+01:00
594750
1
TEST
2b2a2775b8ddf9525d034ba32dd2313ad9801bd1
SOAP Example Response
1394206294707
05d9f8a28a740df9f55b9b4996997c962a6169ae
0
4
Systempay – Implementation Guide – webservices V4
@Lyra Network- 27/ 798. 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
Mandatory
Name Data Type Description
Field
createInfo createPaymentInfo Payment request message
wsSignature String 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/ 79finalyzeWithThreeDS()
Use finalyzeWithThreeDS() to:
return the response from 3D-Secure server, back to the payment gateway
complete the transaction
Arguments
Data Mandatory
Name Description
Type Field
This is the threeDSRequestId (extracted from the
threeDSRequestId String
MD parameter returned from ACS Server)
pares String Returned parameter from ACS Server
wsSignature String Signature (see below)
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/ 79create()
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
Mandatory
Name Data Type Description
Field
createInfo paymentCreationInfo Payment request message
wsSignature String 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/ 79modify()
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
Mandatory
Name Data type Description
Field
siteId String / n8 Shop ID
Date and time of creation of the transaction to be
dateTime /
transmissionDate modified, according to the W3C guidelines.
ans..40
E.g. 2012-06-08T08:16:43+00:00
transactionId String / an6 Unique ID of the transaction to modify
Sequence number of the transaction to be
modified.
Values:
sequenceNumber Int / n..3
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
ctxMode String
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
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
currency Int / n3
(e.g « 978 » for EURO)
Defines the day of automatic capture of an
dateTime /
presentationDate authorized payment, according to the W3C
ans..40
guidelines (e.g. 2012-06-08T08:16:43+00:00
Indicates if you want to validate the transaction.
validate bool
0 = NO, 1 = YES
Use this field to record comments about the
comment String
payment.
wsSignature String Signature (see below)
Systempay – Implementation Guide – webservices V4
@Lyra Network- 31/ 79Signature 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/ 79cancel()
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
Mandatory
Name Data Type Description
Field
siteId String / n8 Shop ID
Date and time of creation of the transaction to
dateTime / be cancelled, according to the W3C
transmissionDate
ans..40 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:
sequenceNumber Int / n..3
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
ctxMode String live mode
(Expected value: “TEST” or “PRODUCTION”)
Use this field to record comments about the
comment String
payment.
wsSignature String 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/ 79refund()
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
Mandatory
Name Data Type Description
Field
siteId String / n8 Shop ID
Date and time of creation of the transaction to
dateTime /
transmissionDate be refunded, according to the W3C guidelines.
ans..40
E.g. 2012-06-08T08:16:43+00:00
Unique ID of the transaction to refund (Initial
transactionId String / an6
transaction)
Sequence number of the transaction to be
refunded.
Values:
sequenceNumber Int / n..3
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
ctxMode String live mode
(Expected value: “TEST” or “PRODUCTION”)
Unique ID of the transaction generated by the
newTransactionId String / an6
merchant.
amount Long / n..12 Amount of the refund.
Currency code according to the ISO 4217
currency Int / n3 standard
(e.g « 978 » for EURO)
Defines the day of automatic capture of an
dateTime /
presentationDate authorized payment, according to the W3C
ans..40
guidelines (e.g. 2012-06-08T08:16:43+00:00
Payment validation mode
validationMode Int / n..1
0= Automatic ; 1= Manual
Use this field to record comments about the
comment String
payment.
wsSignature String Signature (see below)
Signature computation
Systempay – Implementation Guide – webservices V4
@Lyra Network- 34/ 79You can also read
