Implementation guide Web Services V4

Transcription

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

Implementation guide Web Services V4

Transcription

Documents pareils

ABB string inverters PRO-33.0-TL-OUTD 33 kW

Easypay COP interface manual

Budget Workbench - Wolcott Consulting

MR0104 - Implementation of Suspicious Transaction

Writing Exploits III

CP Best Buy - The Phone House

taxing transactions in financial derivatives: problems and solutions

the role of transaction costs for financial volatility

annex generated errors

press release Randstad-SFN 48KB

Application Programming Using the GNOME Libraries

BBDB User Manual - Les pages perso du Crans