3D Secure Payment

Service Address

/PaymentDealer/DoDirectPaymentThreeD

Request Parameters

PaymentDealerAuthentication

Parameter	Explanation
DealerCode(string)	Dealer code issued by the Moka system
Username (string)	Api username given by Moka system
Password (string)	Api password given by Moka system
CheckKey (string)	The control key (DealerCode + "MK" + Username + "PD" + Password) is created by passing this information, combined as a String, through the SHA-256 hash algorithm. Click here to go to the trial screen.

PaymentDealerRequest

Parameter

Explanation

CardHolderFullName (string)

Card holder's name

CardNumber (string)

Card number

ExpMonth (string)

Expiry date month information (MM)

ExpYear (string)

Expiry date year information (YYYY)

CvcNumber (string)

Card security number

CardToken (string)

If the Card storage feature is used on the Moka, withdrawals can be made by giving the Token of the Card. If a token has been issued, it is not necessary to provide the card number and other card information (expiry date, cvc)..

Note: If a NonSecure (Non-3D) transaction is desired while making a payment with tokens, this parametric authorization can be requested from Moka, and Non3D payment service can also be used.

Amount (decimal)

Payment amount (The Kurus part is written with a dot. For example: 27.50)

Currency (string)

Currency unit. Optional field, if not sent at all or empty, default is TL, Other values: USD, EUR, GBP

InstallmentNumber (integer)

Number of Installments. It is an optional field, if it is not sent at all, if it is sent blank, if 0 or 1 is sent, it means Advance sale. A value between 2 and 12 must be sent for Installment.

ClientIP (string)

IP information of the computer running the application (desktop/web) from which the card number is obtained

OtherTrxCode (string)

You can submit your own Unique Transaction Code in this field for reconciliation. (Can also be sent blank).
Note: You can find out the payment status by using this code while getting the dealer payment detail list.

SubMerchantName (string) (optional)

Name you want to appear on statement – Moka must be notified in advance

IsPoolPayment (tinyint)

Pool payment?
0 : No - The amount withdrawn from the card is credited to the dealer's account the next day or later, according to the agreement between Moka and the dealer.
1 : Yes - The money will be withdrawn from the credit card but kept in the pool. The dealer will approve the payment after the customer receives the service or product, and the payment for this transaction will be reflected on the dealer's statement after approval. Until the dealer approves the pool payment, this payment is not included in the statement. Set this field to 1 to send a payment in the pool system.

IsPreAuth (tinyint)

Pre-authorization process?
0 : No - Direct Capture Process
1 : Yes - Pre-authorization Process (Must be converted to payment with DoCapture service after a while)

IsTokenized (tinyint)

Will the card entered for payment be stored in the Moka system? (The dealer must be receiving card storage service to be able to store cards)
0 : Card will not be stored
1 : Card will be kept

IntegratorId (tinyint) (optional)

ID of the System Integrator Company that integrates Moka into ready-made eCommerce packages – (If you are not an integrator company, do not send this field!)

Software (string)

The name of the E-commerce package or software that you call this service integrated with the Moka payment system. (Max 30 characters)

Description (string)(optional)

Description field. If you want to write a description about the payment, it can be written in this field. (Up to 200 characters can be written.)

ReturnHash (tinyint)

Its value must be given as 1. When the 3D Payment flow is completed, your RedirectURL will be notified whether the transaction was successful or not by adding the letter T or F to the end of the CodeForHash code returned in the response of this service.

RedirectUrl (string)

As a result of the 3D transaction, the dealer web page where the successful or unsuccessful transaction result is returned and the user is directed. While giving this URL, if you write your own transaction ID as a parameter at the end, you will be able to determine the result of your transaction.
Example: https://www.mysite.com/PayResult?MyTrxId=1A2B3C4DF5R
Important Note: For your security, prefer your own transaction code that you write at the end of the URL to be an unpredictable code.

RedirectType (integer)

It is an optional field. Its default value is 0 (zero). The result of the payment process redirects to the home page on the website that calls the service. If this service is called from the IFrame and the result is to be redirected to the IFrame, 1 must be entered in this field.

BuyerInformation (Array)(optional)

These are the fields related to the customer who buys a product/service from our dealer. Although it is not mandatory to send these fields, sharing them with Moka is in the interests of both our dealer and Moka in case of future payment related problems.

BuyerFullName (string)	Optional field. Name and surname of the recipient.
BuyerEmail (string)	Optional field. Recipient's e-mail address.
BuyerGsmNumber (string)	Optional field. It is the mobile phone number of the recipient. It must be entered as 10 digits, without spaces.
BuyerAddress (string)	Optional field. It is the address of the recipient.

BasketProduct (Array)(optional)

ProductId (integer)	It is the product ID.
ProductCode (string)	It is the special code of the product on the dealer side.
UnitPrice (integer)	It is the unit price.
Quantity (integer)	The quantity of the product.

CustomerInformation (Array)(optional)

If card information is also desired to be stored during payment and the dealer's card storage service is activated by Moka, then this information block can be sent to create a customer and add the card number used for payment to this customer.

DealerCustomerId (integer)	The Unique ID of this customer in the Moka system, if this customer has been registered in the Moka system before.
CustomerCode (string)	The Unique ID of this customer in your system. If this code has already been registered in Moka, you can also send a payment request with this code and if the card is to be stored, it will be stored under the customer. If this client is to be registered for the first time, it is registered with this code
FirstName (string)	If the customer is to be registered in the Moka system for the first time, the customer's name is entered.
LastName (string)	If the customer is to be registered in the Moka system for the first time, the customer's surname is entered. (optional)
Gender (tinyint)	If the customer is to be registered in the Moka system for the first time, the gender of the customer is entered. (optional) 1: male 2: female
BirthDate (string)	If the customer is to be registered in the Moka system for the first time, the date of birth of the customer is entered. (optional)
GsmNumber (string)	If the customer is to be registered in the Moka system for the first time, the customer's mobile phone is entered. (optional)
Email (string)	If the customer is to be registered in the Moka system for the first time, the customer's email address is entered. (optional)
Address (string)	If the customer is to be registered in the Moka system for the first time, the customer's residential address is entered. (optional)
CardName (string)	Name given to the card (Ex: “Maximum card”) (Max 50 characters) (optional)

Sample Request (JSON)


{
   "PaymentDealerAuthentication":{
      "DealerCode":"xxx",
      "Username":"xxx",
      "Password":"xxx",
      "CheckKey":"28ba1f316e661ee7a0477a13aa30613da548c94a8098829af9255b04d7e916e3"
   },
   "PaymentDealerRequest":{
      "CardHolderFullName":"Ali Yılmaz",
      "CardNumber":"5555666677778888",
      "ExpMonth":"09",
      "ExpYear":"2024",
      "CvcNumber":"123",
      "CardToken":"",
      "Amount":0.01,
      "Currency":"TL",
      "InstallmentNumber":1,
      "ClientIP":"192.168.1.116",
      "OtherTrxCode":"20210114172139",
      "SubMerchantName":"",
      "IsPoolPayment":0,
      "IsPreAuth":0,
      "IsTokenized":0,
      "IntegratorId":0,
      "Software":"Possimulation",
      "Description":"",
      "ReturnHash":1,
      "RedirectUrl":"https://service.TestMoka.com/PaymentDealerThreeD?MyTrxCode=20210114172139",
      "RedirectType":0,
      "BuyerInformation":{
         "BuyerFullName":"Ali Yılmaz",
         "BuyerGsmNumber":"5551110022",
         "BuyerEmail":"aliyilmaz@xyz.com",
         "BuyerAddress":"Tasdelen / Çekmeköy"
      },
      "CustomerInformation":{
         "DealerCustomerId":"",
         "CustomerCode":"1234",
         "FirstName":"Ali",
         "LastName":"Yılmaz",
         "Gender":"1",
         "BirthDate":"",
         "GsmNumber":"",
         "Email":"aliyilmaz@xyz.com",
         "Address":"",
         "CardName":"Maximum kartım"
      }
   }
}

Successful Request Result

If the sent request data has been processed successfully in Moka, "Success" information is written in the "ResultCode" field of the object of the return object, and there is a link in the "Data" field.

The user should be directed to this link in order to request a password from the bank and verify the credit card by entering the password received via SMS.

Moka will use the CodeForHash data in the data block to report the payment result. Store this value in your database and associate it with this payment request.

After the user completes the card verification process, they are automatically redirected back to the "RedirectUrl" link sent when calling the service. In other words, the post is sent to the URL you provided.

During this redirection, "hashValue", "resultCode", "resultMessage", "trxCode" and "OtherTrxCode" form fields can be read and necessary actions can be taken according to the result of the operation.

In case of a successful transaction from the bank, the returned OrderId should be stored in the trxCode field. Cancellation, refund or pool payment confirmation transactions will be carried out using this code.

If the payment fails, the reason for the failure can be found out by using the "resultCode" and "resultMessage" fields.

How to calculate and check hashValue?

Returned values by TEXT POSTing to your RedirectURL as a result of 3D Validation:

Key : hashValue         Value : cdb7869505bdaaac2f4c891fc9ed889885fd7a0c880127ab5d508883efa3ee83
Key : resultCode         Value :
Key : resultMessage Value :
Key : trxCode               Value : ORDER-17131QQFG04026575
Key : OtherTrxCode     Value : Your-Transaction-Code

If you want us to TEXT POST the payment result to another URL, you can report this to the Moka operation team. If the text answer is "OK" from the URL we posted, it is understood that the payment result can be sent to the merchant, otherwise the Post transaction is tried 2 more times. The following information is POSTed to a URL that you provide at the completion of each payment :

Key : hashValue         Value : cdb7869505bdaaac2f4c891fc9ed889885fd7a0c880127ab5d508883efa3ee83
Key : resultCode         Value :
Key : resultMessage Value :
Key : trxCode               Value : ORDER-17131QQFG04026575
Key : OtherTrxCode     Value : Your-Transaction-Code

IMPORTANT NOTE

When paying with 3D Secure, you can also use our Get services to check the payment status.

Successful Result Example


{
	"Data":{
      "Url":"https://service.testmoka.com/PaymentDealerThreeDProcess?threeDTrxCode=0cc02f5fac4f-47fb-aa94-167582552caa",
      "CodeForHash":"9FDFBDFC-42C5-417E-AA93-E4D9D5312AAC"
	},
	"ResultCode": "Success",
	"ResultMessage": "",
	"Exception": null
}

Failed Request Result

If the sent request data could not be processed in Moka streams, the "ResultCode" field of the return object contains one of the error codes in the table below.
When an unexpected software error occurs, EX is written in the "ResultCode" field and the error message (Exception) is displayed in the "ResultMessage" field
In both cases, the "Data" object arrives as null.

ResultCode	Explanation
PaymentDealer.CheckPaymentDealerAuthentication.InvalidRequest	The CheckKey may be bad, or the object may be bad, or the JSON may be corrupt.
PaymentDealer.CheckPaymentDealerAuthentication.InvalidAccount	No such dealer was found.
PaymentDealer.CheckPaymentDealerAuthentication.VirtualPosNotFound	There is no virtual pos definition for this dealer.
PaymentDealer.CheckDealerPaymentLimits.DailyDealerLimitExceeded	Any of the daily limits defined for the dealer have been exceeded.
PaymentDealer.CheckDealerPaymentLimits.DailyCardLimitExceeded	No more transactions can be made using this card during the day.
PaymentDealer.CheckCardInfo.InvalidCardInfo	There is an error in the card information.
PaymentDealer.DoDirectPayment3dRequest.InvalidRequest	The JSON object was created incorrectly.
PaymentDealer.DoDirectPayment3dRequest.RedirectUrlRequired	RedirectURL to return 3D payment result is not given.
PaymentDealer.DoDirectPayment3dRequest.InvalidCurrencyCode	The currency is incorrect. (Must be in the form of TL, USD, EUR)
PaymentDealer.DoDirectPayment3dRequest.InvalidInstallmentNumber	Invalid installment number must be between 1 and 12.
PaymentDealer.DoDirectPayment3dRequest.InstallmentNotAvailableForForeignCurrencyTransaction	Installments cannot be made in foreign currency.
PaymentDealer.DoDirectPayment3dRequest.ForeignCurrencyNotAvailableForThisDealer	The dealer is not allowed to pay in foreign currency.
PaymentDealer.DoDirectPayment3dRequest.PaymentMustBeAuthorization	Payment must be sent in pre-authorization type.
PaymentDealer.DoDirectPayment3dRequest.AuthorizationForbiddenForThisDealer	The reseller is not allowed to send payments in pre-authorization type.
PaymentDealer.DoDirectPayment3dRequest.PoolPaymentNotAvailableForDealer	The reseller is not allowed to send pooled payments.
PaymentDealer.DoDirectPayment3dRequest.PoolPaymentRequiredForDealer	The dealer can only send pooled payments.
PaymentDealer.DoDirectPayment3dRequest.TokenizationNotAvailableForDealer	The dealer is not allowed to keep the card.
PaymentDealer.DoDirectPayment3dRequest.CardTokenCannotUseWithSaveCard	Token cannot be sent if the card is to be stored.
PaymentDealer.DoDirectPayment3dRequest.CardTokenNotFound	The sent token was not found.
PaymentDealer.DoDirectPayment3dRequest.OnlyCardTokenOrCardNumber	Both the card number and the Token cannot be issued at the same time.
PaymentDealer.DoDirectPayment3dRequest.ChannelPermissionNotAvailable	The dealer is not allowed to send payments through this channel.
PaymentDealer.DoDirectPayment3dRequest.IpAddressNotAllowed	Reseller has IP restriction, can only send payment from pre-specified IP.
PaymentDealer.DoDirectPayment3dRequest.VirtualPosNotAvailable	No suitable virtual pos was found for the entered card.
PaymentDealer.DoDirectPayment3dRequest.ThisInstallmentNumberNotAvailableForVirtualPos	Virtual Pos does not allow this number of installments.
PaymentDealer.DoDirectPayment3dRequest.ThisInstallmentNumberNotAvailableForDealer	This number of installments cannot be made for this dealer.
PaymentDealer.DoDirectPayment3dRequest.DealerCommissionRateNotFound	This number of installments cannot be made for this dealer.
PaymentDealer.DoDirectPayment3dRequest.DealerGroupCommissionRateNotFound	No commission rate has been entered to the top dealer for this virtual pos and installment.
PaymentDealer.DoDirectPayment3dRequest.InvalidSubMerchantName	The sent dealer name has not been saved to the Moka system before.
PaymentDealer.DoDirectPayment3dRequest.InvalidUnitPrice	If the products sold have been added to the cart, the current unit price must be entered.
PaymentDealer.DoDirectPayment3dRequest.InvalidQuantityValue	If the products sold have been added to the cart, the valid quantity must be entered.
PaymentDealer.DoDirectPayment3dRequest.BasketAmountIsNotEqualPaymentAmount	If the products sold are added to the cart, the cart amount and the payment amount must match.
PaymentDealer.DoDirectPayment3dRequest.BasketProductNotFoundInYourProductList	If the products sold have been added to the cart, the current product must be selected.
PaymentDealer.DoDirectPayment3dRequest.MustBeOneOfDealerProductIdOrProductCode	If the products sold are added to the cart, the product code or moka product ID must be entered.
EX	An unexpected error has occurred

Example of Failed Result


{
	"Data": null,
	"ResultCode": "PaymentDealer.CheckPaymentDealerAuthentication.VirtualPosNotFound ",
	"ResultMessage": "",
	"Exception": null
}

3D Secure İşlem Akışı

Ödeme İşlemi Hata Kodları (Bankadan Alınan Hatalar)

resultCode	resultMessage
000	General Error
001	Cardholder Confirmation Failed
002	Insufficient Limit
003	Credit Card Number Not in Valid Format
004	General Disclaimer
005	Transaction Not Open to Card Holder
006	Card Expiry Date Incorrect
007	Invalid Transaction
008	Unable to Connect to Bank
009	Undefined Error Code
010	Bank SSL Error
011	Call the Bank for Manual Approval
012	Card Information Incorrect - Card Number or CVV2
013	Cards Except Visa MC Do Not Support 3D Secure
014	Invalid Account Number
015	Invalid CVV
016	No Approval Mechanism Available
017	System failure
018	Stolen Card
019	Lost Card
020	Restricted Card
021	Time out
022	Invalid Workplace
023	Fake Confirmation
024	3D Approval Received But Money Couldn't Be Withdrawn From Card
025	3D Confirmation Error
026	Card Holder is Not a Bank or Card 3D-Secure Member
027	The User Is Not Authorized To Take This Action
028	Fraud Probability
029	Your card is closed to e-commerce transactions