Send Payment Request
Service Address
/PaymentUserPos/CreateUserPosPaymentMarketPlace
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 lis | ||||||||||||||||||
| DealerCustomerTypeId (integer) | ID of the Payment Request sending identification 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 | ||||||||||||||||||
| GsmNumber (string) | Phone number to send payment link | ||||||||||||||||||
| Email (string) | Email address to which payment link will be sent | ||||||||||||||||||
| 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 Mokaya, 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 |
||||||||||||||||||
| 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 choose 3D option) 1 : Payment using 3D is mandatory |
||||||||||||||||||
| 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 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 be able to determine the result of your transaction. 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. |
||||||||||||||||||
| CommissionScenario (integer)(zorunlu) | It is the commission option that is decided by the top dealer and tells how the commissions to be deducted from the sub-dealers that have participated in this sale will be calculated. After calculating the Moka commission to be deducted from the lower dealer, the difference between the upper dealer commission amount and the lower dealer commission amount is the upper dealer's own income. These calculations are made separately for each sub-dealer that has participated in this sale, and the total commission to be deducted from the upper dealer (Moka Revenue) arising from the sale, the total commission to be deducted from the lower dealers and the total income of the upper dealer will be found. The amount to be deposited by Moka to the sub-dealer is the amount after deducting the sub-dealer's commission. There are 6 different scenarios to report the sub-dealer commission: Alt bayi komisyonunu bildirmek için 6 farklı senaryo mevcuttur : 1 : MOKA SUB-RESELLER COMMISSION RATES (%) The top dealer uses this scenario when he wants to trade with the commission rate defined in the Moka system of the lower dealer. Therefore, it is sufficient to distribute the amount to the sub-dealers in the sale. How much commission will be deducted from each sub-dealer is calculated by looking at the commission rate defined for that sub-dealer in the Moka system. The Amount and DealerId parameters in the SubDealer block are mandatory fields. The formula is as follows : Sub-dealer commission amount = (Amount * MokaSub-DealerCommission Rate / 100) 2 : INSTANT SUB-RESELLER COMMISSION RATES (%) (%) The upstream dealer uses this scenario when he wants to instantly give the downstream dealer a new commission rate (%) for this payment. In this case, instead of the sub-dealer's commission rate in the Moka system, the calculation is made using the sub-dealer's commission rates (%) and the fixed commission amount sent in this request. Amount, DealerId and DealerCommissionRate parameters in the SubDealer block are required fields. For fixed commission amount, TL amount can be sent to DealerCommissionFixedAmount parameter when requested. (zero if not sent) The formula is as follows: Sub-dealer commission amount = (Amount * DealerCommissionRate / 100) + DealerCommissionFixedAmount 3 : INSTANT SUB-RESELLER COMMISSION AMOUNTS (TL) The top dealer uses this scenario when he wants to instantly give a new commission amount (TL) to the sub-dealer for this payment. In this case, instead of calculating the commission rate of the sub-dealer in the Moka system, the sub-dealer commission amount (TL) sent in this request is used. When the commission deducted from the lower dealer is subtracted from the commission deducted by Moka from the upper dealer, the income of the upper dealer appears. The DealerId, Amount and DealerCommissionAmount parameters in the SubDealer block are required fields. The formula is as follows : Sub-dealer commission amount = DealerCommissionAmount 4 : INSTANT TOP DEALER REVENUE RATIOS (%) If the top dealer does not want to follow the commission rate that Moka will deduct from itself or does not want to calculate according to this rate, it uses this scenario to specify how much rate (%) will be added directly to the commission rate to be deducted from itself and deducted from the lower dealer. The rate given in this scenario is the top dealer revenue rate. The DealerId, Amount, GroupRevenueRate and AmountToBeCommissioned parameters in the SubDealer block are required fields. The sum of the AmountToBeCommissioned fields given for sub-dealers must be equal to the sum of the whole sale. The commission to be deducted from the parent dealer can be loaded to different sub-dealers by numeric manipulation on the AmountToBeCommissioned field. For example, if no deductions are requested from a sub-reseller, GroupRevenueRate = 0 and AmountToBeCommissioned = 0 for that sub-reseller. The formula is as follows : Sub-dealer commission amount = (Amount * GroupRevenueRate / 100) + ( AmountToBeCommissioned * MokaTop-DealerCommission Rate / 100) + IsIncludedFixedAmount 5 : INSTANT DEALER REVENUE AMOUNT (TL) If the top dealer does not want to follow the commission rate that Moka will deduct from itself or does not want to calculate according to this rate, it uses this scenario to indicate how much amount (TL) will be added directly to the commission rate to be deducted from itself and deducted from the lower dealer. The DealerId, Amount, GroupRevenueAmount and AmountToBeCommissioned parameters in the SubDealer block are required fields. The formula is as follows : Sub-dealer commission amount = (GroupRevenueAmount) + ( AmountToBeCommissioned * MokaUp-DealerCommission Rate / 100) + IsIncludedFixedAmount 6 : AMOUNT TO BE DEPOSED TO THE SUB-REVENUE Amount (TL) The top dealer uses this scenario when he wants to tell the bottom dealer how much (TL) will be deposited instantly for this payment. In this case, neither the sub-dealer's commission rate in the Moka system is calculated, nor the sub-dealer's commission amounts or rates are given. The amount required to be deposited to the sub-dealers is given and Moka calculates the commission rates and amounts. Sub-dealer's total commission amount is found when the amount to be deposited to sub-dealers is subtracted from the Main Amount. When the commission amount to be deducted by Moka from the top dealer is subtracted, the income of the top dealer is revealed. DealerId and Amount parameter in SubDealer block are required fields. The sum of the Amounts in this block is not equal to the main Amount !!! The difference is the sum of sub-dealer commissions. The formula is as follows : Subdealer commission amount = Main Amount - SubDealer.Amount |
||||||||||||||||||
| SubDealer (Array-List)(zorunlu) |
|
||||||||||||||||||
| 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":"04c431a3248db2512c0a20d34828f460de9a65ab5573906a2975010cb6393e37"
},
"PaymentUserPosRequest":{
"OtherTrxCode":"fyyz",
"DealerCustomerTypeId":"248",
"FullName":"",
"GsmNumber":"5530270178",
"Email":"feyyaz.kayar@moka.com",
"IsPreAuth":"0",
"IsPoolPayment":"0",
"IsTokenized":"0",
"DealerCustomerId":"",
"CustomerCode":"",
"FirstName":"",
"LastName":"",
"Gender":"0",
"BirthDate":"19901218",
"CustomerGsmNumber":"5530270178",
"CustomerEmail":"feyyaz.kayar@moka.com",
"Address":"",
"Amount":"50",
"Currency":"TL",
"InstallmentNumber":"0",
"SetInstallmentBy":"0",
"IsThreeD":"0",
"Description":"",
"ReturnHash":1,
"RedirectUrl":"https://service.TestMoka.com/PaymentDealerThreeD?MyTrxCode=78687676",
"CommissionScenario":1,
"SubDealer":[
{
"DealerId":1820,
"Amount":"10",
"DealerCommissionRate":"",
"DealerCommissionAmount":"",
"GroupRevenueRate":"",
"GroupRevenueAmount":"",
"AmountToBeCommissioned":"",
"DealerCommissionFixedAmount":"",
"IsIncludedFixedAmount":""
},
{
"DealerId":1821,
"Amount":"40",
"DealerCommissionRate":"",
"DealerCommissionAmount":"",
"GroupRevenueRate":"",
"GroupRevenueAmount":"",
"AmountToBeCommissioned":"",
"DealerCommissionFixedAmount":"",
"IsIncludedFixedAmount":""
}
],
"BasketProduct":[
{
"DealerId":1820,
"ProductId":82,
"ProductCode":"",
"UnitPrice":"10",
"Quantity":"1"
},
{
"DealerId":1821,
"ProductId":83,
"ProductCode":"",
"UnitPrice":"40",
"Quantity":"1"
}
],
"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 -
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
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. | |
| The dealer's monthly payment limit has been exceeded. | ||
| EX | An unexpected error has occurred |
Example of Failed Result
{
"Data": null,
"ResultCode": "PaymentUserPos.CreateUserPosPaymentMarketPlace.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 they want 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.
Belirtilen değerler verilmelidir.
For the CommunicationType field change, you can contact us by contacting your sales manager or by sending an e-mail to operation@moka.com