Payment with Masterpass
This integration method is used to perform Masterpass client integration on the merchant's side and to receive Masterpass payments through Craftgate on the server side. This allows the merchant to benefit from the various value-added services offered by Craftgate.
Generating Masterpass Token
After the user completes card and installment selection, the token value to be used in the Masterpass payment process is obtained through this service. This token is used in the token field within the MFS.purchase method of the Masterpass client SDK.
Request Parameters
The parameters expected to be sent in the requests to generate a Masterpass token are listed under the table and subheadings below;
Phone number of the customer
Value used to associate the customer with the Masterpass account
The first 6 or 8 digits of the selected card. Can be accessed from the Value1 field of the object associated with the selected card in the response of the Masterpass MFS.listCards method
Should be set to true if 3D secure authentication is requested for the transaction.
"boomerang" value that can be sent with the request and received with the response. It can be used to associate different requests with each other. Usually, the order number is used that is stored in merchant own system.
Special characters that may cause security problems should not be used in the data. Data cannot start with the + or - character, but it can be used in it.
It is generally used as a payment order number or basket number on the merchant side. You can search with this value later by using reporting services.
Special characters that may cause security problems should not be used in the data. Data cannot start with the + or - character, but it can be used in it.
Total basket price. The sum of the item prices in the basket must be equal to total basket price.
The final amount to be paid from the card by calculating differences such as commissions and discounts. The amount to be collected from the wallet is also included in this amount. If there is an interest in the transaction, the amount with the interest added should be entered in this parameter.
Installment number. Should be 1 for cash price.
ID of the buyer that is returned from member creation.
It is generally used to keep information specific to the payment channel on the merchant side. You can search with this value later by using reporting services.
Order id parameter to be transmitted to the bank when receiving the payment. Since it is optional, it is recommended not to send it and the orderId value is generated by Craftgate.
IP of the buyer.
Represents the POS that payment will be collected.
Payment items related to payment. You must send at least one payment item and the sum of prices must be equal to the price field.
Additional parameters related to payment. See: Payment Additional Parameters
Reward information requested to be used during payment. See Using Rewards and Points
Response Parameters
The parameters returned as a result of generate token are also subject to the rules specified in
the Response Formats section of the API documentation home page. In the absence of a systematic
or fictional error, the sub-parameters of the object returned in the data parameter are as follows:
Value used to complete the Masterpass payment process
Token value to be used within the Masterpass client SDK
Value to be used in the MFS.purchase method. If request sent with the bankOrderId parameter, the sent value is returned. If the bankOrderId parameter is not sent, an automatically generated orderNo value is returned.
Non-3DS Masterpass Payment
If the responseCode value in the response that is return from MFS.purchase method is 5001, it indicates that the Masterpass payment process needs to be verified using the OTP method. After completing OTP verification on the client side through Masterpass integration, payment process can be completed by sending the obtained token value to Craftgate through the following service.
Request Parameters
The parameters expected to be sent in the requests to complete a Non-3DS Masterpass payment are listed under the table and subheadings below;
Value returned in the generate token response for the relevant transaction.
Token value returned by Masterpass, used to complete the payment
Response Parameters
The parameters returned as a result of completing a Masterpass Non-3DS payment are also subject to the rules specified in
the Response Formats section of the API documentation home page. In the absence of a systematic
or fictional error, the sub-parameters of the object returned in the data parameter are as follows:
ID of the payment.
The date that payment is created
Basket price of the payment
Paid price of the payment
Wallet price of the payment
Buyer member ID of the payment
Installment number
Value of theconversationId parameter sent in the payment request
externalId value that sent in payment request by merchant
See: Payment Types
See: Payment Status
paymentChannel value sent by the merchant in the payment request
Indicates whether the payment is 3D Secure payment
Interest rate to calculate paid price that buyer will pay
Interest amount. Equal to the difference between paidPrice and price values
Bank commission rate
Bank commission rate amount
Card user key that represents the card holder.
Card token that represents the card.
Indicates whether the payment was made with a stored card
Exist for the payments fully or partially collected from the card. First 8 digits of the card
Exist for the payments fully or partially collected from the card. Last 4 digits of the card
Card holder name surname
Card holder name surname retrieved from bank. The return value might be null for PF poses
authCode value retrieved from bank related to the payment. The return value might be null for PF poses
hostReference value retrieved from bank related to the payment
transId value retrieved from bank related to the payment. The return value might be null for PF poses
orderId value retrieved from bank related to the payment
Card Association
Brand of card. Exist for the payments fully or partially collected from the card
Value of theposAlias parameter sent in the payment request
POS info that payment is received
Loyalty info that used in payment (See: Reward Usage)
Fraud Check Id if fraud rule matches (See: Fraud Checks)
Fraud Check Action if fraud rule matches (See: Fraud Actions)
It includes the transaction information sent when making the payment request, and the pricing and money transfer information of the payment based on these transactions
Additional data related to the payment
3D Secure Masterpass Payment
If the responseCode value in the response that is returned from MFS.purchase method is 5010, it indicates that the Masterpass payment process needs to be verified using the 3D Secure. Below are the relevant steps for processing 3D Secure payment flow.
Init 3D Secure Payment
Request Parameters
The parameters expected to be sent in the requests to init Masterpass 3DS payment are listed under the table and subheadings below;
Value returned in the generate token response for the relevant transaction.
The URL to be used to send the result returned from the bank to the merchant
Response Parameters
The parameters returned as a result of initiating a Masterpass 3DS payment are also subject to the rules specified in
the Response Formats section of the API documentation home page. In the absence of a systematic
or fictional error, the sub-parameters of the object returned in the data parameter are as follows:
ID of payment. For mobile flow this value should be used in the 3DS complete step.
For web flow, URL to which the user will be redirected by appending the url3D field obtained from the MFS.purchase method response
For mobile flow, URL which should be given to the resultUrl3D field before calling validateTransaction3D.
window.location = `${purchaseResult.url3D}&returnUrl=${returnUrl}`;
MasterPassInfo.setResultUrl3D(returnUrl);;
Verify 3D Secure Payment
Once the user has verified themselves, they will be redirected to the callbackUrl address specified in the 3D Secure Payment Init request. For details, see 3D Secure Verification.
There will be no redirection for mobile flow, you should call the 3DS complete service after receiving the validateTransaction3D callback response.
Complete 3D Secure Payment
After completing the relevant checks in the previous step, the 3D Secure payment process can be completed using the following service.
Request Parameters
The parameters expected to be sent in the requests to complete Masterpass 3DS payment are listed under the table and subheadings below;
PaymentId value obtained from the 3D Secure Verification step.
Response Parameters
The parameters returned as a result of completing a Masterpass 3D Secure payment are also subject to the rules specified in
the Response Formats section of the API documentation home page. In the absence of a systematic
or fictional error, the sub-parameters of the object returned in the data parameter are as follows:
ID of the payment.
The date that payment is created
Basket price of the payment
Paid price of the payment
Wallet price of the payment
Buyer member ID of the payment
Installment number
Value of theconversationId parameter sent in the payment request
externalId value that sent in payment request by merchant
See: Payment Types
See: Payment Status
paymentChannel value sent by the merchant in the payment request
Indicates whether the payment is 3D Secure payment
Interest rate to calculate paid price that buyer will pay
Interest amount. Equal to the difference between paidPrice and price values
Bank commission rate
Bank commission rate amount
Card user key that represents the card holder.
Card token that represents the card.
Indicates whether the payment was made with a stored card
Exist for the payments fully or partially collected from the card. First 8 digits of the card
Exist for the payments fully or partially collected from the card. Last 4 digits of the card
Card holder name surname
Card holder name surname retrieved from bank. The return value might be null for PF poses
authCode value retrieved from bank related to the payment. The return value might be null for PF poses
hostReference value retrieved from bank related to the payment
transId value retrieved from bank related to the payment. The return value might be null for PF poses
orderId value retrieved from bank related to the payment
Card Association
Brand of card. Exist for the payments fully or partially collected from the card
Value of theposAlias parameter sent in the payment request
POS info that payment is received
Loyalty info that used in payment (See: Reward Usage)
Fraud Check Id if fraud rule matches (See: Fraud Checks)
Fraud Check Action if fraud rule matches (See: Fraud Actions)
It includes the transaction information sent when making the payment request, and the pricing and money transfer information of the payment based on these transactions
Additional data related to the payment