MXPlus API Technical

Specification V1
 MXPlus API Technicalspecification

COPYRIGHT

MX PaymentMXPlus is a package of module software dedicated to the secure management and processing of electronic transactions and
their related business activities.

MX Payment version MXPlus manages the issuing and acquiring business activities related to the electronic transactions.

In the following chapters, we will present the MXPlusAPI for e-commerce payment technical specification.

ABOUT

Created / Modified By Last Modification Date Version Comment

Lahcen Naoui 1.0 Initial Version

Validated By Validation Date Version Comment

Kamaleddine ATIFI 1.0 Validated version

2
 MXPlus API Technicalspecification

Contents

1. Introduction .......................................................................................................................................................... 4
2. Architecture.......................................................................................................................................................... 5
2.1 The payment page managed by the NAPS GATEWAY ................................................................................. 5
2.2 The payment page managed by the custumer .............................................................................................. 6
3. API Header Call format ........................................................................................................................................ 7
4. Token 24 generation ............................................................................................................................................ 8
5. Get card token ...................................................................................................................................................... 9
6. Delete card token ............................................................................................................................................... 10
7. Authorization for payment page managed by the custumer ........................................................................... 11
8. Authorization for payment page managed by the NAPS GATEWAY .............................................................. 14
9. Reversal .............................................................................................................................................................. 17
10. Pre-autorisation confirmation....................................................................................................................... 19
11. Capture........................................................................................................................................................... 21
12. Refund ............................................................................................................................................................ 23
13. Status ............................................................................................................................................................. 25
14. Exception handling ....................................................................................................................................... 27
15. Switch response code ................................................................................................................................... 28
The following table present different switch response code and theirinterpretation: ........................................................... 28

3
 MXPlus API Technicalspecification

1. Introduction
MXPluspayment API is exposed as a rest Web Services supporting standard resthttps protocol. This would facilitate the payment
transactions via the MXPlus API and integrate with external platforms.

Calls to the API exposed functionalities are standard rest post-https call.Data exchanged on the httpspost body and header are standard flat
json format.

list of functions:

1- linkpayment : generates the payment link

2- CreatTocken24: generate secure key token for 24H

3- Cardtoken : generate a Token for a card holder

4- authorization : this function allows to make the payment and preauthorization

5- reversal : cancel a transaction

6- capture : remote collection

7- cpauthorization : pre-authorization

8- refound : refund transaction

9- status : retrieve the status and details of a previous payment

4
 MXPlus API Technicalspecification

2. Architecture
2.1 The payment page managed by the NAPS GATEWAY

5
 MXPlus API Technicalspecification

2.2 The payment page managed by the custumer

6
 MXPlus API Technicalspecification

3. API Header Call format

Each call to the API must contain the following header format:

HTTPS Header
Field Type Description Size Mandatory/Optional
X-API-Key String API KEY : ea026d587af74420903d42c365e2d0db 32 Mandatory
X-Product String MXPLUS 6 Mandatory
Content-Type String application/json 25 Mandatory
X-Version String 1.0 3 Mandatory
User-Agent String DLOCAL 15 Mandatory

Table 1: Header format

7
 MXPlus API Technicalspecification

4. Token 24 generation

The createtocken24call to API permit to Request 24 Hourtoken between the Banks BEand MXPAYMENT

The following table present the incoming API call <createtocken24> specification:

Incoming to MXPlus Endpoint https://gwapi.naps.ma:8085/napspayment/createtocken24

URL

WEB SITE -->MXPLus API

Request
Field Type Size Mandatory/Optional Description
Institution ID assigned by MXPAYMENT (Default:
institution_id string 5 Mandatory
11010)
USER ID: Given by MXPAYMENT to the Institution
cx_user string 16 Mandatory
Administrator ()
PASSWORD HASH: Provided by MXPAYMENT to the
cx_password string 32 Mandatory
Institution Administrator
cx_reason string 2 Mandatory Reason for request of connection 00 : Default
Value checksum M2m to confirm –
mac_value string 8 Mandatory
(institution_id+cx_user)

Response
Mandatory/Option
Field Type Size Description
al
institution_id string 5 Mandatory Institution ID assigned by MXPAYMENT (DC : 11010)
USER ID: Given by MXPAYMENT to the Institution
cx_user string 16 Returned
Administrator
"MXPAYMENT API" token1. Must beprovided in all
cx_securtoken_24 string 172 Mandatory
requests from the institution's server
error_msg String 30 Mandatory Error message
error_code String 3 Mandatory Error code according to error codes list
mac_value string 8 Optional Check sum Value M2m confirmation

8
 MXPlus API Technicalspecification

5. Get card token

The Cardtoken call to API permit to get the token relaed to the card following table present the.

The following table present the incoming API call < Cardtoken > specification:

Incoming to MXPlus Endpoint https://gwapi.naps.ma:8085/napspayment/cardtoken

URL

WEB SITE -->MXPLus API

HTTPS BODY
Field Type Description Size Mandatory/Optional
securtoken24 String MXPAYMENT TOKEN 24H 16 Mandatory
Transaction info
mac_value String Checksumvalue(orderid+amount) 16 Mandatory
merchantid String Example : 2200000 10 Mandatory
merchantname String Example : WEB SITE 55 Mandatory
Merchant info
websitename String Web site name 50 Optional
websiteid String Web site id for naps identification 22 Optional
cardnumber String Cardnumber 13-19 19 max Mandatory
Card info expirydate String Card expiration date YYMM 6 Mandatory
holdername String Holdername 77 Mandatory
fname String First name 77 Mandatory
Client info lname String Last name 77 Mandatory
email String Email 25 Optional

The following table present the specification of the post response of the API call < cardtoken >:

Outgoing from MXPlus Endpoint https://gwapi.naps.ma:8085/napspayment/cardtoken

URL
MXPLus API -->WEB SITE

HTTPS BODY
Field Type Description Size Mandatory/Optional
statuscode String Response code 2 Mandatory
Transaction info
status String Response code message 27 Mandatory
Card info token String Cardtokennumber 16 max Mandatory

Table 3: cardtoken outgoing specification

9
 MXPlus API Technicalspecification

6. Delete card token

The deleteCardtoken call to API permit to delete the token relaed to the card following table present the.

The following table present the incoming API call < deleteCardtoken > specification:

Incoming to MXPlus Endpoint https://gwapi.naps.ma:8085/napspayment/deleteCardtoken

URL

WEB SITE -->MXPLus API

HTTPS BODY
Field Type Description Size Mandatory/Optional
Merchant info merchantid String Example : 2200000 10 Mandatory
cardnumber String Cardnumber 13-19 19 max Mandatory
Card info
token String token 16 Mandatory

The following table present the specification of the post response of the API call < deletecardtoken >:

Outgoing from MXPlus Endpoint https://gwapi.naps.ma:8085/napspayment/deleteCardtoken

URL
MXPLus API -->WEB SITE

HTTPS BODY
Field Type Description Size Mandatory/Optional
statuscode String Response code (00) 2 Mandatory
Transaction info
status String Response code message 27 Mandatory
Card info token String Cardtokennumber 16 Mandatory

Table 3: deleteCardtoken outgoing specification

10
 MXPlus API Technicalspecification

7. Authorization for payment page managed by the custumer

The Autorization call to API permit to make a regular payment with automatic capture or without.

The following table present the incoming API call <authorization> specification:

Incoming to MXPlus Endpoint https://gwapi.naps.ma:8085/napspayment/authorization

URL

WEB SITE -->MXPLus API

HTTPS BODY
Field Type Description Size Mandatory/Optional
capture String Y : Automatic capture , N : delayed capture 1 Mandatory
transactiontype String 0 : payment, P : Pre-authorization 1 Mandatory
currency String Currency code, ex MAD : 504 3 Optional
orderid String Generated by merchant 27 Mandatory
recurring String Recurring transaction flag Y/N 1 Mandatory
Transaction info
amount String Amount 12 Mandatory
promocode String Promotion code 12 Optional
transactionid String WEB SITE Transaction id 9 Optional
securtoken24 String MXPAYMENT TOKEN 24H 16 Mandatory
mac_value String Checksumvalue(orderid+amount) 16 Mandatory
merchantid String Example : 1702777 10 Mandatory
merchantname String Example : WEB SITE 55 Mandatory
websitename String Web site name 50 Optional
Merchant info websiteid String Web site id for naps identification 22 Optional
callbackurl String Optional callback url (future use) 77 Optional
successURL String The success url 50 Mandatory
failURL String The fail url 50 Mandatory
cardnumber String Cardnumber 13-19 19 max Mandatory
token String Cardtokennumber 16 Optional
Card info expirydate String Card expiration date YYMM 6 Mandatory
holdername String Holdername 77 Mandatory
cvv String CVV number 3 Optional
fname String First name 77 Mandatory
lname String Last name 77 Mandatory
email String Email 25 Optional
country String Country code , Example (Morocco) : 504 3 Optional
Client info phone String Phone number 19 Mandatory
city String City 25 Optional
state String Regionname 25 Optional
zipcode String Postal code 25 Optional
address String Address 120 Optional

11
 MXPlus API Technicalspecification

Table 2: Authorization incomingspecification

The following table present the specification of the post response of the API call <authorization>:

Outgoing from MXPlus Endpoint https://gwapi.naps.ma:8085/napspayment/authorization

URL
MXPLus API -->WEB SITE

HTTPS BODY
Field Type Description Size Mandatory/Optional
statuscode String Response code 2 Mandatory
status String Response code message 27 Mandatory
orderid String Generated by merchant 27 Mandatory
amount String Amount 12 Mandatory
transactiondate String Transaction date yyyy-MM-dd 8 Mandatory
transactiontime String Transaction time : HH:mm:ss 8 Mandatory
Transaction info authnumber String Authorizationnumber 8 Mandatory
paymentid String Payment id 22 Mandatory
transactionid String WEB SITE Transaction id 9 Optional
etataut String C : chalange, Y : frictionless 1 Mandatory
treedsid String Id transaction 3DS 36 Mandatory
Link API redirection ACS : if etataut = C
linkacs String then redirection vers API 50 Conditional
merchantid String Example : 2200000 10 Mandatory
merchantname String Example : WEB SITE 55 Mandatory
Merchant info websitename String Web site name 50 Optional
websiteid String Web site id for naps identification 22 Optional
callbackurl String Optional callback url (future use) 77 Optional
Card info cardnumber String Cardnumber 13-19 19 max Mandatory
fname String First name 77 Mandatory
Client info lname String Last name 77 Mandatory
email String Email 25 Optional

Table 3: Authorization outgoing specification

if the etataut ="C" in the response you must redirect in the "linkacs" link in order to authenticate, if the etataut ="Y" then the
transaction will pass frictionless without authentication.

In case challenge, and after switch authorization, the response will be sent to the successURL if the transaction is successful
otherwise
will be sent in the failURL.

12
 MXPlus API Technicalspecification

Sending the payment response to successURL:

After completing the online payment, the NAPS e-Commerce platform sends the e-Commerce platform, via the HTTPOST method,
an encrypted response frame to the link mentioned in the "succesURL" field of the data2 frame. For the recovery of the payment
response, the e-merchant platform uses the aforementioned private key to decrypt the response frame received.

Decryption of the response by the private key:

Sample response frame:

https://epay.naps.ma/wp-content/plugins/ecommerce_naps/config/confirmation /confirmpaie.php?data=fzy9MIx2
OpipwY/hrQGc+OJGQg/rOGMRV3hkb0UrOIb5J6guOs0QZCbqMho4OvwrqdUb7xjPMktlTA9nWOrRxKva/+ExOfEI0o
Ufvwl1owA4XrwxZ3jDXqiftC7aORpvWjHjobhVHXiqt8okwBUNBiBmKef3AL0QaJokcc78ClRak6zmTicYuWhYUzT8/8
6iZqE4FcaHi4zizJKCo0xZURGVR8eywP6bIB9qxI1C1DdWlmF0b7DqwYLxfAx74harULaEUHmq73+7EVhkbRXVU08+
HQncWfxrdvTa2v3F7q87qfgk7zqI/Qg/qho3wEetsK/D6lsiWmq0RWXt/ZzroA====&codecmr=1180092

In our case : succesURL=https://epay.naps.ma/wp-content/plugins/ecommerce_naps/config/confirmation /confirmpaie.php

The frame to decrypt is in the data parameter, in our case:

data=fzy9MIx2OpipwY/hrQGc+OJGQg/rOGMRV3hkb0UrOIb5J6guOs0QZCbqMho4OvwrqdUb7xjPMktlTA9nWOrRx
Kva/+ExOfEI0oUfvwl1owA4XrwxZ3jDXqiftC7aORpvWjHjobhVHXiqt8okwBUNBiBmKef3AL0QaJokcc78ClRak6zmTi
cYuWhYUzT8/86iZqE4FcaHi4zizJKCo0xZURGVR8eywP6bIB9qxI1C1DdWlmF0b7DqwYLxfAx74harULaEUHmq73+7
EVhkbRXVU08+HQncWfxrdvTa2v3F7q87qfgk7zqI/Qg/qho3wEetsK/D6lsiWmq0RWXt/ZzroA====

The result of decryption of the above response frame is:

id_commande= 804220200614021427&nomprenom=Test testo&email=

[email protected]&montant=60.00&repauto=00&numAuto=141558&numCarte=523456xxxxxx3456&typecarte=Mastercar
d&numTrans=015815

Fields Descpition
id_commande orderid
nomprenom lname fname
email email
montant amount
repauto coderep
numAuto authnumber
numCarte cardnumber
typecarte typecarte
numTrans transactionid

13
 MXPlus API Technicalspecification

8. Authorization for payment page managed by the NAPS GATEWAY

The Autorization call to API permit to make a regular payment with automatic capture or without.

The following table present the incoming API call <authorization> specification:

Incoming to MXPlus Endpoint https://gwapi.naps.ma:8085/napspayment/linkpayment

URL

WEB SITE -->MXPLus API

HTTPS BODY
Field Type Description Size Mandatory/Optional
capture String Y : Automatic capture , N : delayed capture 1 Mandatory
Transactiontype String 0 : payment, P : Pre-authorization 1 Mandatory
currency String Currency code, ex MAD : 504 3 Optional
orderid String Generated by merchant 27 Mandatory
recurring String Recurring transaction flag Y/N 1 Mandatory
Transaction info
amount String Amount 12 Mandatory
promocode String Promotion code 12 Optional
transactionid String WEB SITE Transaction id 9 Optional
securtoken24 String MXPAYMENT TOKEN 24H 16 Mandatory
mac_value String Checksumvalue(orderid+amount) 16 Mandatory
merchantid String Example : 2200000 10 Mandatory
merchantname String Example : WEB SITE 55 Mandatory
websitename String Web site name 50 Optional
Merchant info websiteid String Web site id for naps identification 22 Optional
callbackurl String Optional callback url (future use) 77 Optional
successURL String The success url 50 Mandatory
failURL String The fail url 50 Mandatory
fname String First name 77 Mandatory
lname String Last name 77 Mandatory
email String Email 25 Optional
country String Country code , Example (Morocco) : 504 3 Optional
Client info phone String Phone number 19 Mandatory
city String City 25 Optional
state String Regionname 25 Optional
zipcode String Postal code 25 Optional
address String Address 120 Optional

Table 2: Authorization incomingspecification

14
 MXPlus API Technicalspecification

The following table present the specification of the post response of the API call <linkpayment >:

Outgoing from MXPlus Endpoint https://gwapi.naps.ma:8085/napspayment/linkpayment

URL
MXPLus API -->WEB SITE

HTTPS BODY
Field Type Description Size Mandatory/Optional
statuscode String Response code 2 Mandatory
status String Response code message 27 Mandatory
orderid String Generated by merchant 27 Mandatory
amount String Amount 12 Mandatory
Transaction info
transactiondate String Transaction date yyyy-MM-dd 8 Mandatory
transactiontime String Transaction time : HH:mm:ss 8 Mandatory
transactionid String WEB SITE Transaction id 9 Mandatory
url String Url page payment NAPS GATEWAY 50 Mandatory

Table 3: Authorization outgoing specification

Url : once the response its returned the web site , the gallery proceed to the redirection to the NAPS GATEWAY payment page.

after entering the credit card data and validating the response will be sent to the successURL if the transaction is successful otherwise
will be sent in the failURL.

Sending the payment response to successURL:

After completing the online payment, the NAPS e-Commerce platform sends the e-Commerce platform, via the HTTPOST method,
an encrypted response frame to the link mentioned in the "succesURL" field of the data2 frame. For the recovery of the payment
response, the e-merchant platform uses the aforementioned private key to decrypt the response frame received.

Decryption of the response by the private key:

Sample response frame:

https://epay.naps.ma/wp-content/plugins/ecommerce_naps/config/confirmation /confirmpaie.php?data=fzy9MIx2
OpipwY/hrQGc+OJGQg/rOGMRV3hkb0UrOIb5J6guOs0QZCbqMho4OvwrqdUb7xjPMktlTA9nWOrRxKva/+ExOfEI0o
Ufvwl1owA4XrwxZ3jDXqiftC7aORpvWjHjobhVHXiqt8okwBUNBiBmKef3AL0QaJokcc78ClRak6zmTicYuWhYUzT8/8
6iZqE4FcaHi4zizJKCo0xZURGVR8eywP6bIB9qxI1C1DdWlmF0b7DqwYLxfAx74harULaEUHmq73+7EVhkbRXVU08+
HQncWfxrdvTa2v3F7q87qfgk7zqI/Qg/qho3wEetsK/D6lsiWmq0RWXt/ZzroA====&codecmr=1180092

In our case : succesURL=https://epay.naps.ma/wp-content/plugins/ecommerce_naps/config/confirmation /confirmpaie.php

15
 MXPlus API Technicalspecification

The frame to decrypt is in the data parameter, in our case:

data=fzy9MIx2OpipwY/hrQGc+OJGQg/rOGMRV3hkb0UrOIb5J6guOs0QZCbqMho4OvwrqdUb7xjPMktlTA9nWOrRx
Kva/+ExOfEI0oUfvwl1owA4XrwxZ3jDXqiftC7aORpvWjHjobhVHXiqt8okwBUNBiBmKef3AL0QaJokcc78ClRak6zmTi
cYuWhYUzT8/86iZqE4FcaHi4zizJKCo0xZURGVR8eywP6bIB9qxI1C1DdWlmF0b7DqwYLxfAx74harULaEUHmq73+7
EVhkbRXVU08+HQncWfxrdvTa2v3F7q87qfgk7zqI/Qg/qho3wEetsK/D6lsiWmq0RWXt/ZzroA====

The result of decryption of the above response frame is:

id_commande= 804220200614021427&nomprenom=Test testo&email=

[email protected]&montant=60.00&repauto=00&numAuto=141558&numCarte=523456xxxxxx3456&typecarte=Mastercar
d&numTrans=015815

Fields Descpition
id_commande orderid
nomprenom lname fname
email email
montant amount
repauto coderep
numAuto authnumber
numCarte cardnumber
typecarte typecarte
numTrans transactionid

16
 MXPlus API Technicalspecification

9. Reversal
The Reversal call to API permit to make an online reversal of a previous payment.

The following table present the incoming API call <reversal> specification:

Incoming to MXPlus Endpoint https://gwapi.naps.ma:8085/napspayment/reversal

URL
WEB SITE -->MXPLus API

HTTPS BODY
Field Type Description Size Mandatory/Optional
orderid String Generated by merchant 27 Mandatory
authnumber String Authorizationnumber 8 Mandatory
paymentid String Payment id 22 Mandatory
Transaction info amount String Amount 12 Mandatory
transactionid String WEB SITE Transaction id 9 Optional
securtoken24 String MXPAYMENT TOKEN 24H 16 Mandatory
mac_value String Checksumvalue(orderid+amount) 16 Mandatory
merchantid String Example : 2200000 10 Mandatory
merchantname String Example : WEB SITE 55 Mandatory
Merchant info websitename String Web site name 50 Optional
websiteid String Web site id for naps identification 22 Optional
callbackurl String Optional callback url (future use) 77 Optional
Card info cardnumber String Cardnumber 13-19 19 max Mandatory
fname String First name 77 Mandatory
Client info lname String Last name 77 Mandatory
email String Email 25 Optional

Table 4: Reversal incoming specification

17
 MXPlus API Technicalspecification

The following table present the specification of the post response of the API call <reversal>:

Outgoing from MXPlus Endpoint https://gwapi.naps.ma:8085/napspayment/reversal

URL
MXPLus API -->WEB SITE

HTTPS BODY
Field Type Description Size Mandatory/Optional
statuscode String Response code 2 Mandatory
status String Response code message 27 Mandatory
orderid String Generated by merchant 27 Mandatory
amount String Amount 12 Mandatory
Transaction info reversaldate String Reversal Transaction date yyyy-MM-dd 8 Mandatory
transactiontime String Reversal Transaction HH:mm:ss 8 Mandatory
authnumber String Authorizationnumber 8 Mandatory
reversalid String Reversal id 22 Mandatory
transactionid String WEB SITE Transaction id 9 Optional
merchantid String Example : 2200000 10 Mandatory
merchantname String Example : WEB SITE 55 Mandatory
Merchant info websitename String Web site name 50 Optional
websiteid String Web site id for naps identification 22 Optional
callbackurl String Optional callback url (future use) 77 Optional
Card info cardnumber String Cardnumber 13-19 19 max Mandatory
fname String First name 77 Mandatory
Client info lname String Last name 77 Mandatory
email String Email 25 Optional

18
 MXPlus API Technicalspecification

10. Pre-autorisation confirmation

The pre-authorization confirmation call to API permit to make an online confirmation of a previous pre-autorization .

The following table present the incoming API call <cpautorisation> specification:

Incoming to MXPlus Endpoint https://gwapi.naps.ma:8085/napspayment/cpautorisation

URL
WEB SITE -->MXPLus API

HTTPS BODY
Field Type Description Size Mandatory/Optional
orderid String Generated by merchant 27 Mandatory
authnumber String Authorizationnumber 8 Mandatory
paymentid String Payment id 22 Mandatory
Transaction info amount String Amount 12 Mandatory
transactionid String WEB SITE Transaction id 9 Optional
securtoken24 String MXPAYMENT TOKEN 24H 16 Mandatory
mac_value String Checksumvalue(orderid+amount) 16 Mandatory
merchantid String Example : 2200000 10 Mandatory
merchantname String Example : WEB SITE 55 Mandatory
Merchant info websitename String Web site name 50 Optional
websiteid String Web site id for naps identification 22 Optional
callbackurl String Optional callback url (future use) 77 Optional
Card info cardnumber String Cardnumber 13-19 19 max Mandatory
fname String First name 77 Mandatory
Client info lname String Last name 77 Mandatory
email String Email 25 Optional

Table 4: Reversal incoming specification

19
 MXPlus API Technicalspecification

The following table present the specification of the post response of the API call <cpautorisation >:

Outgoing from MXPlus Endpoint https://gwapi.naps.ma:8085/napspayment/cpautorisation

URL
MXPLus API -->WEB SITE

HTTPS BODY
Field Type Description Size Mandatory/Optional
statuscode String Response code 2 Mandatory
status String Response code message 27 Mandatory
orderid String Generated by merchant 27 Mandatory
amount String Amount 12 Mandatory
Transaction info reversaldate String Reversal Transaction date yyyy-MM-dd 8 Mandatory
transactiontime String Reversal Transaction HH:mm:ss 8 Mandatory
authnumber String Authorizationnumber 8 Mandatory
reversalid String Reversal id 22 Mandatory
transactionid String WEB SITE Transaction id 9 Optional
merchantid String Example : 2200000 10 Mandatory
merchantname String Example : WEB SITE 55 Mandatory
Merchant info websitename String Web site name 50 Optional
websiteid String Web site id for naps identification 22 Optional
callbackurl String Optional callback url (future use) 77 Optional
Card info cardnumber String Cardnumber 13-19 19 max Mandatory
fname String First name 77 Mandatory
Client info lname String Last name 77 Mandatory
email String Email 25 Optional

Table 5: Reversal outgoing specification

20
 MXPlus API Technicalspecification

11. Capture
The Capture call to API permit to make a capture of a previous payment.

The following table present the incoming API call <capture> specification:

Incoming to MXPlus Endpoint https://gwapi.naps.ma:8085/napspayment/capture

URL
WEB SITE -->MXPLus API

HTTPS BODY
Field Type Description Size Mandatory/Optional
orderid String Generated by merchant 27 Mandatory
paymentid String Payment id 22 Mandatory
amount String Amount 12 Mandatory
Transaction info authnumber String Authorizationnumber 8 Mandatory
transactionid String WEB SITE Transaction id 9 Optional
securtoken24 String MXPAYMENT TOKEN 24H 16 Mandatory
mac_value String Checksumvalue(orderid+amount) 16 Mandatory
merchantid String Example : 2200000 10 Mandatory
merchantname String Example : WEB SITE 55 Mandatory
Merchant info websitename String Web site name 50 Optional
websiteid String Web site id for naps identification 22 Optional
callbackurl String Optional callback url (future use) 77 Optional
Card info cardnumber String Cardnumber 13-19 19 max Mandatory
fname String First name 77 Mandatory
Client info lname String Last name 77 Mandatory
email String Email 25 Optional

Table 6: Capture incoming specification

21
 MXPlus API Technicalspecification

The following table present the specification of the post response of the API call <capture>:

Outgoing from MXPlus Endpoint https://gwapi.naps.ma:8085/napspayment/capture

URL
MXPLus API -->WEB SITE

HTTPS BODY
Field Type Description Size Mandatory/Optional
orderid String Generated by merchant 27 Mandatory
amount String Amount 12 Mandatory
capturedate String Transaction date yyyy-MM-dd 8 Mandatory
capturetime String Transaction time HH:mm:ss 8 Mandatory
Transaction info
capture_id String Capture id 36 Mandatory
capture_state String Captured : Y or Rejected : N 1 Mandatory
capture_label String Rejection label if rejected capture 50 Mandatory
transactionid String WEB SITE Transaction id 9 Optional
merchantid String Example : 2200000 10 Mandatory
merchantname String Example : WEB SITE 55 Mandatory
Merchant info websitename String Web site name 50 Optional
websiteid String Web site id for naps identification 22 Optional
callbackurl String Optional callback url (future use) 77 Optional
Card info cardnumber String Cardnumber 13-19 19 max Mandatory
fname String First name 77 Mandatory
Client info lname String Last name 77 Mandatory
email String Email 25 Optional

Table 7: Capture outgoing specification

22
 MXPlus API Technicalspecification

12. Refund

The Refund call to API permit to make a capture of a previous payment.

The following table present the incoming API call <refund> specification:

Incoming to MXPlus Endpoint https://gwapi.naps.ma:8085/napspayment/refund

URL
WEB SITE -->MXPLus API

HTTPS BODY
Field Type Description Size Mandatory/Optional
orderid String Generated by merchant 27 Mandatory
authnumber String Authorizationnumber 8 Mandatory
paymentid String Payment id 22 Mandatory
Transaction info amount String Amount 12 Mandatory
transactionid String WEB SITE Transaction id 9 Optional
securtoken24 String MXPAYMENT TOKEN 24H 16 Mandatory
mac_value String Checksumvalue(orderid+amount) 16 Mandatory
merchantid String Example : 2200000 10 Mandatory
merchantname String Example : WEB SITE 55 Mandatory
Merchant info websitename String Web site name 50 Optional
websiteid String Web site id for naps identification 22 Optional
callbackurl String Optional callback url (future use) 77 Optional
Card info cardnumber String Cardnumber 13-19 19 max Mandatory
fname String First name 77 Mandatory
Client info lname String Last name 77 Mandatory
email String Email 25 Optional

Table 8: Refund incoming specification

23
 MXPlus API Technicalspecification

The following table present the specification of the post response of the API call <refund>:

Outgoing from MXPlus Endpoint https://gwapi.naps.ma:8085/napspayment/refund

URL
MXPLus API -->WEB SITE

HTTPS BODY
Field Type Description Size Mandatory/Optional
statuscode String Response code 2 Mandatory
status String Response code message 27 Mandatory
orderid String Generated by merchant 27 Mandatory
amount String Amount 12 Mandatory
Transaction info refunddate String Refund Transaction date yyyy-MM-dd 8 Mandatory
Refund Transaction hour-minutes-seconds
transactiontime String HH:mm:ss 8 Mandatory
authnumber String Authorizationnumber 8 Mandatory
refundid String Refund id 22 Mandatory
transactionid String WEB SITE Transaction id 9 Optional
merchantid String Example : 2200000 10 Mandatory
merchantname String Example : WEB SITE 55 Mandatory
Merchant info websitename String Web site name 50 Optional
websiteid String Web site id for naps identification 22 Optional
callbackurl String Optional callback url (future use) 77 Optional
Card info cardnumber String Cardnumber 13-19 19 max Mandatory
fname String First name 77 Mandatory
Client info lname String Last name 77 Mandatory
email String Email 25 Optional

Table 9: Refund outgoing specification

24
 MXPlus API Technicalspecification

13. Status

The Status call to API permit to retrieve status of a previous payment.

The following table present the incoming API call <status> specification:

Incoming to MXPlus Endpoint https://gwapi.naps.ma:8085/napspayment/status

URL
WEB SITE -->MXPLus API

HTTPS BODY
Field Type Description Size Mandatory/Optional
orderid String Generated by merchant 27 Mandatory
authnumber String Authorizationnumber 8 Mandatory
paymentid String payment id 22 Mandatory
Transaction info amount String Amount 12 Mandatory
transactionid String WEB SITE Transaction id 9 Mandatory
securtoken24 String MXPAYMENT TOKEN 24H 16 Mandatory
mac_value String Checksumvalue(orderid+ amount) 16 Mandatory
Merchant info merchantid String Example : 2200000 10 Mandatory

Table 9: Status incoming specification

25
 MXPlus API Technicalspecification

The following table present the specification of the post response of the API call <status>:

Outgoing from MXPlus Endpoint https://gwapi.naps.ma:8085/napspayment/status

URL
MXPLus API -->WEB SITE

HTTPS BODY
Field Type Description Size Mandatory/Optional
Transaction status Enum :
status String Paid,Declined,Captured,Settled Max 20 Mandatory
State code Paid = 00 , Declined = 01,
statuscode String Captured = 02, Settled = 03 2 Mandatory
authstatuscode String PreviousAuthorizationResponse code 2 Mandatory
authstatus String PreviousAuthorizationResponse message 27 Mandatory
transactiondate String Transaction date yyyy-MM-dd 8 Optional
transactiontime String Transaction time HH:mm:ss 8 Optional
Transaction info authdate String Authorization date yyyy-MM-dd 8 Optional
authtime String Authorization time HH:mm:ss 8 Optional
capturedate String Capture date yyyy-MM-dd 8 Optional
capturetime String Capture time HH:mm:ss 8 Optional
settlementdate String Settlement date yyyy-MM-dd 8 Optional
settlementtime String Settlement time HH:mm:ss 8 Optional
authnumber String Authorizationnumber 8 Mandatory
transactionid String WEB SITE Transaction id 9 Mandatory
Merchant info merchantid String Example : 2200000 10 Mandatory

Table 10: Status outgoing specification

26
 MXPlus API Technicalspecification

14. Exception handling

The following chapter present the specification of the post response of the API calls
<authorization>,<reversal>,<capture>,<refund>,<status> in case an exception occurred.

Exception may occur such as:Switch networking problems, DB down or DB inconsistence, controls over API data for each call…

Each time an exception, happen a standard json message is given as response using 5 fields:
api_call, error_code,error_label, error_detail,error_stack.

In case of a normal processing the standard response of the API call is given see chapter above for more information. In case of
exception, the following table present the JSON response given in such case.

HTTPS BODY
Field Type Description Size Mandatory/Optional
API call name : authorizationreversal
api_call String ,capture,refund,status 20 Mandatory
errorcode (furture use) now it’s one value
Error info error_code String : 500 3 Mandatory
error_label String Error label 2 Mandatory
error_detail String Details about the error 27 Mandatory
error_stack String Java (JVM) error for error diagnosis 512 Mandatory

Table 11: Errormessage specification

27
 MXPlus API Technicalspecification

15. Switch response code

The following table present different switch response code and theirinterpretation:

Switch response code Switch label/status

00 Approved
01 Refer to Cardissuer
02 Refer to Card issuer Special
07 Pick Up CardSpecial
13 InvalidAmount
21 No Action Taken
25 Unable to locate record
43 Pick Up StolenCard
51 Insufficient Funds
52 No chekingaccount
53 No savingaccount
54 Expiredcard
55 Incorrect Pin
57 Transaction not permitted
58 Transaction not allowed
61 Exeedswithdrawl
62 Restrictedcard
63 Security violation
65 Activity count limitexceeded
75 Allowablenumber of PIN
76 Unable to locate message
80 Invalid date
81 Pin Cryptographic
82 Incorrect CVV
83 Unable to Verify Pin
85 No Reason
91 Issuerunavailable
92 Detinationcannotbefound
93 Transaction cannot
96 System Malfunction
16 Order alrready used
15 Merchant not existe
17 Data invalid
Table 12: Switch status specification

28