Send Payment Request
Service Address
/PaymentUserPos/CreateUserPosPayment
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. |
PaymentUserPosRequest
| Parameter | Explanation | ||||||||
|---|---|---|---|---|---|---|---|---|---|
| OtherTrxCode (string) | You must submit your own Unique Transaction Code in this field to achieve reconciliation. Note: You can find out the payment status by using this code while getting the dealer payment detail list. | ||||||||
| DealerCustomerTypeId (integer) | ID of the Payment Request sending definition record created by Moka for your dealer. You must submit the payment request according to the rules in this definition. Otherwise you will get error messages. | ||||||||
| FullName (string) | Name and surname of your customer to whom the payment link will be sent - You can not enter this field if the link will not be sent to your customer, but will return to you with the service. | ||||||||
| GsmNumber (string) | Telephone number where the payment link will be sent - If the link will not be sent to your customer, but will return to you with the service, you can not enter this field. | ||||||||
| Email (string) | The e-mail address to which the payment link will be sent - You may not enter this field if the link will not be sent to your customer, but will return to you with the service. | ||||||||
| 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 in order to keep the card) 0 : The card will not be kept 1 : The card will be kept 2 : The paying customer will decide whether to keep the card or not. |
||||||||
| 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) | ||||||||
| CustomerGsmNumber (string) | If the customer is to be registered in the Moka system for the first time, the customer's mobile phone is entered. (optional) | ||||||||
| CustomerEmail (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) | ||||||||
| 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. | ||||||||
| SetInstallmentBy (tinyint) | In installment payments, it determines who will choose the number of installments. 0 : The customer will choose the number of installments 1 : The dealer who sent the number of installments has chosen and sent it |
||||||||
| CommissionByDealer (tinyint) | Will the commission be paid by the dealer or charged to the customer? 0 : The Customer will pay the commission for both cash and installment payments. The dealer does not interfere with the commission. 1 : Only the dealer pays the commission in advance payment, the customer pays the commission in installments. 2 : Both in cash and in 2 installments, the commission is paid by the dealer, in higher installments the commission is taken from the customer 3: Both in cash and in 2 installments, the commission is paid by the dealer, in higher installments the commission is taken from the customer. . . 12 : The dealer pays the commission both in cash and in all installments. |
||||||||
| IsCommissionDiffByDealer (tinyint) | According to the information above, how many installments the dealer will pay the commission, in
more installments, the entire commission or only the difference can be reflected to the customer.
0 : No (Reflect the Selected Installment Commission to the Customer) 1 : Yes (Selected Installment Commission – (minus) Fee equal to the Installment Commission Accepted by the Dealer (Differential Commission) Reflect to the Customer) |
||||||||
| IsThreeD (tinyint) | Will the payment be made using 3D? 0 : 3D is not mandatory (customer can make non-3D payment if they want, or they can tick 3D option) 1 : Payment using 3D is mandatory |
||||||||
| 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) | If the link from which the payment will be made will not be sent to the customer, the service will
return to you and you will open this link yourself, then you have to give the RedirectUrl field. If
the link will be sent to the customer by SMS or email, you do not need to provide this field as the
payment result will be directed to Moka's own page. 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 determine which transaction you have received. If you're sending the OtherTrxCode field, you can't even use the Get parameter when giving the URL. The OtherTrxCode field is already POSTing to this URL. 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 |
||||||||
| 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.
|
||||||||
| BasketProduct (Array)(optional) |
|
Sample Request (JSON)
{
"DealerAuthentication":{
"DealerCode":"XXX",
"Username":"XXX",
"Password":"XXX",
"CheckKey":"28ba1f316e661ee7a0477a13aa30613da548c94a8098829af9255b04d7e916e3"
},
"PaymentUserPosRequest":{
"OtherTrxCode":"78687676",
"DealerCustomerTypeId":"2",
"FullName":"Zeynep",
"GsmNumber":"",
"Email":"zeynep.hashan@moka.com",
"IsPoolPayment":"0",
"IsPreAuth":"0",
"IsTokenized":"0",
"DealerCustomerId":"",
"CustomerCode":"",
"FirstName":"",
"LastName":"",
"Gender":"0",
"BirthDate":"19901218",
"CustomerGsmNumber":"",
"CustomerEmail":"",
"Address":"",
"Amount":"0.01",
"Currency":"TL",
"InstallmentNumber":"0",
"SetInstallmentBy":"0",
"CommissionByDealer":"",
"IsCommissionDiffByDealer":"0",
"IsThreeD":"0",
"Description":"",
"ReturnHash":1,
"RedirectUrl":"https://service.TestMoka.com/PaymentDealerThreeD?MyTrxCode=78687676",
"BuyerInformation":{
"BuyerFullName":"",
"BuyerGsmNumber":"",
"BuyerEmail":"",
"BuyerAddress":"Tasdelen"
}
}
}
Successful Request Result
- If the sent request data has been processed successfully in Moka, "Success" information is written in the "ResultCode" field of the return object . In the "Data" field, there is the ID (UserPosPaymentId) of the sent payment request and, if there is a possibility to store the card, the ID ( DealerCustomerId ) of the newly created or already existing dealer customer and the URL link. If it failed, the Data field will be null. The reason for the error can be interpreted by checking the ResultCode and ResultMessage fields.
- If this link, which will open the payment screen, has not been sent to the cardholder via SMS or Email, the merchant's browser should be directed to this link.
- If the merchant opens the payment screen in the cardholder's browser, it will also receive the payment result with the RedirectUrl. And it will also do the following operations.
- 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 -
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
Successful Result Example
{
"Data":{
"UserPosPaymentId":3393,
"DealerCustomerId":0,
"Url":"https://pos.testmoka.com/CustomerPos/PaymentRequest?uppc=57681",
"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 |
|---|---|
| PaymentUserPos.DealerAuthentication.InvalidRequest | The CheckKey may be bad, or the object may be bad, or the JSON may be corrupt. |
| PaymentUserPos.DealerAuthentication.InvalidAccount | No such dealer was found |
| PaymentUserPos.CreateUserPosPayment.ChannelPermissionNotAvailable | The reseller is not authorized to send a payment request. |
| PaymentUserPos.CreateUserPosPayment.IpAddressNotAllowed | The IPs that the dealer can access are restricted. |
| PaymentUserPos.CreateUserPosPayment.EmailOrGsmNumberRequired | No e-mail or phone number to send the payment link. |
| PaymentUserPos.CreateUserPosPayment.GsmRequired | The phone to send the payment link is not given. |
| PaymentUserPos.CreateUserPosPayment.EmailRequired | The e-mail to send the payment link was not given. |
| PaymentUserPos.CreateUserPosPayment.InvalidGsmNumber | Phone number to send payment link is wrong |
| PaymentUserPos.CreateUserPosPayment.InvalidEmailFormat | Email format to send payment link is wrong |
| PaymentUserPos.CreateUserPosPayment.InvalidCustomerGsmNumber | For the card storage service, the phone information, which is the dealer customer information, is incorrect. |
| PaymentUserPos.CreateUserPosPayment.InvalidCustomerEmailFormat | For the card storage service, the email information, which is the dealer customer information, is incorrect. |
| PaymentUserPos.CreateUserPosPayment.InvalidCurrencyCode | Currency incorrect (must be TL, USD, EUR or GBP) |
| PaymentUserPos.CreateUserPosPayment.InstallmentNotAvailableForForeignCurrencyTransaction | Installments cannot be made for foreign currency. |
| PaymentUserPos.CreateUserPosPayment.DealerCustomerTypeNotFound | The definition of submitting such a payment request could not be found. |
| PaymentUserPos.CreateUserPosPayment.DealerCustomerTypeMismatchForDealer | This payment request submission definition does not belong to this reseller. |
| PaymentUserPos.CreateUserPosPayment.ForeignCurrencyUnavailable | The dealer does not have a foreign currency permit. |
| PaymentUserPos.CreateUserPosPayment.InvalidPaymentPermission | Error message about pre-authorization or sending direct payment |
| PaymentUserPos.CreateUserPosPayment.InvalidPoolPermission | Error message about sending a pooled payment |
| PaymentUserPos.CreateUserPosPayment.InvalidTokenizationPermissionValue | Error message regarding card storage |
| PaymentUserPos.CreateUserPosPayment.InvalidTokenizationPermission | Dealer does not have card storage permission |
| PaymentUserPos.CreateUserPosPayment.InvalidCommissionByDealerValue | How many installments commission from the dealer, the value is given incorrectly |
| PaymentUserPos.CreateUserPosPayment.InvalidCommissionDiffByDealerValue | From the commission difference in more installments, the value is given incorrectly |
| PaymentUserPos.CreateUserPosPayment.SetInstallmentByAndInstallmentNumberInconsistent | Who will choose the installment, the dealer or the customer? The value given with the description must match |
| PaymentUserPos.CreateUserPosPayment.InvalidInstallmentNumber | The number of installments was entered incorrectly. |
| PaymentUserPos.CreateUserPosPayment.SetInstallmentByInconsistent | Who will choose the installment, the dealer or the customer? The value given with the description must match |
| PaymentUserPos.CreateUserPosPayment.ThreeDRequired | 3D must be mandatory |
| PaymentUserPos.CreateUserPosPayment.InvalidBirthDateFormat | From the dealer customer's information, the date of birth was entered incorrectly. |
| PaymentUserPos.CreateUserPosPayment.DealerCustomerNotCreated | An attempt was made to create a new dealer customer, but an error was received |
| PaymentUserPos.CreateUserPosPayment.DealerCustomerNotFound | An existing reseller customer was submitted (with CustomerCode), but this customer was not found. |
| PaymentUserPos.CreateUserPosPayment.DealerCustomerInfoIsMissing | To create a Reseller customer, at least CustomerCode and FirstName must be given. |
| PaymentUserPos.CreateUserPosPayment.DealerCustomerIdAndCustomerCodeDontMatchForDealer | Both the DealerCustomerId in the Moka system and the dealer's own Customer code are given. But in Moka system this customer data is incompatible |
| PaymentUserPos.CreateUserPosPayment.InvalidBuyerGsmNumber | There is a problem in the areas belonging to the person receiving the service. |
| PaymentUserPos.CreateUserPosPayment.InvalidBuyerEmailFormat | There is a problem in the areas belonging to the person receiving the service. |
| PaymentUserPos.CreateUserPosPayment.DailyDealerLimitExceeded | Dealer's daily payment limit has been exceeded. |
| PaymentUserPos.CreateUserPosPayment.MonthlyDealerLimitExceeded | The dealer's monthly payment limit has been exceeded. |
| EX | An unexpected error has occurred |
Example of Failed Result
{
"Data": null,
"ResultCode": "PaymentUserPos.CreateUserPosPayment.GsmRequired",
"ResultMessage": "",
"Exception": null
}
Explanation
In Merchant, Customer type, the CommunicationType field can be determined in the following ways.
If;
0: If you want both SMS and Email to be open, the merchant can enter whatever or both,
1: If you want to send payment request only via SMS,
2: If you want to send payment request only via Email,
3: Only without sending SMS or Email If you want to send a payment request with the link (URL) where the payment
can be made
The specified values must be given.
For the CommunicationType field change, you can contact us by contacting your sales manager or by sending an
e-mail to operation@moka.com