Skip to main content

Safety Recommendations

Craftgate offers end-to-end solutions to provide you with a seamless and secure payment experience. In addition to the solutions offered by Craftgate, we also have suggestions for our merchants to consider. You can contact destek@craftgate.io for your questions and comments.

A. Basic Security Recommendations​

How should we store API Key / Secret Key information?​

These 2 values, which are required to use Craftgate APIs, should be stored securely (preferably encrypted) and should not be shared with unauthorized persons. In addition, if you wish, you can renew your existing keys periodically from Craftgate Merchant Panel. For more information, you can visit API Key / Secret Key Management.

B. Security Recommendations for 3DSecure Payment Flow​

In which cases should we choose 3D Secure payment?​

Although Non-3DS payments are much faster, in some cases they should not be preferred. It is recommended to pay with 3DS instead of Non-3DS for the following scenarios.

  • Prepaid and debit cards are recommended to be paid with 3DS. You can use Craftgate's Bin Query service to find out the type of card received with the payment request.
  • For a new member's first order, it is recommended to pay with 3DS regardless of the type of card used to verify the user.
  • For the first order of an existing member after an address change, it is recommended to take payment with 3DS regardless of the card type to be used.
  • If a payment error is received with LOST_CARD, STOLEN_CARD, PICKUP_CARD error groups as a result of payment, the user should be followed up and it is recommended to receive new payments with 3DS.
  • It is recommended to receive payments with 3DS for your user's transactions with a much higher amount than usual.

What should be the verification type for 3D Secure payments?​

User verification for 3D Secure payments can be done as full and half verification. Full verification takes place when the SMS is sent to the user's phone and the verification code is entered correctly. Half verification occurs in cases where the user cannot be fully included in the 3D Secure system, such as when the phone is not registered with the bank. Half-authenticated 3D Secure payments can be completed, but there are risks because the user cannot be fully authenticated.

As Craftgate, we support both solutions. If you wish, you can select this option in Merchant Panel -> General Settings.

How can you check the security of 3D Secure payments with hash verification?​

MAKE SURE TO APPLY THE SECURITY STEP WITH HASH VERIFICATION IN YOUR 3D SECURE PAYMENTS!

In 3D Secure payments, if the user successfully verifies himself/herself, the payment flow continues. While transmitting the verification result to the merchant, it must verify the verification in the Security Measures for Callback URL call step. If a hash mismatch occurs, payment should not be continued. For the hash calculation algorithm, you can visit 3D Secure Payment page. Merchant should compare the incoming parameters with the data on their side, basket control, user session information should be checked.

In 3D Secure payments, can changes be made to the cart before the payment is completed?​

3D Secure payments have a flow that takes place in the user's browser and can take an average of 50-60 seconds. During the time between the initiation, verification and completion of the 3D Secure payment, attention should be paid to the changes the user makes to the cart. When the cart changes, the user should be warned and the payment should not be continued. The 3D Secure payment should be restarted with the updated cart information.

C. Security Measures for Callback URL call​

In calls to the callback address, it is necessary to check that the call is made by the Craftgate system. In order to make this check, the hash value generated by Craftgate together with some parameters in the call to the callback address and the hashParams value for the parameters used while generating this value are transmitted. Hash Value Generation and Control should be provided for the incoming parameters.

Mandatory Security Step: Hash Value Generation and Check ​

caution

Malicious people can send requests to the merchant's Callback URL just like Craftgate did. For this reason, Do NOT TRUST ANY REQUEST COMING TO CALLBACK URL WITHOUT HASH CHECKING.

You can access the 32 digit key value required for the process from the "Merchant Callback Key " field in the Administration -> Member Workplace Settings interface on the Panel.

public boolean verifyHash(Map<String, String> callbackParams, String callbackKey) {
    String hashValues = Arrays.stream(callbackParams.get("hashParams").split(":"))
    .map(callbackParams::get)
    .collect(Collectors.joining());

    String calculatedHash = DigestUtils.sha256Hex(callbackKey + hashValues);
    return calculatedHash.equals(callbackParams.get("hash"));
  }

For example, suppose the following callback content is transmitted and the Merchant Callback Key value is merchantCallbackKeySandbox.

status=SUCCESS
callbackStatus=
paymentId=863
paymentStatus=SUCCESS
conversationId=d1811bb0-25a2-40c7-ba71-c8b605259611
mdStatus=1
hashParams=paymentId:status:callbackStatus:conversationId:mdStatus
hash=9f746eb6b0886636654243e04e4c69fd84c4ca78a6afcc442491d25663142a21

You should eliminate null values from hashParams parameters and combine them as String. Unlike 3D Secure Verification v1, this step does not include the ##### character in the hashString. In the example, the value to be put into the hashing algorithm should be formed as follows:

merchantCallbackKeySandbox863SUCCESSd1811bb0-25a2-40c7-ba71-c8b6052596111

The hash value that will be generated using the above algorithm will be as follows.

9f746eb6b0886636654243e04e4c69fd84c4ca78a6afcc442491d25663142a21

Validation should be ensured by comparing the generated value with the "hash" parameter in the request.

You can also create hashes from the Open Source Libraries we offer.

D. Security Measures for Webhook Streaming​

How to check if the request to your webhook address is coming from Craftgate?​

In order to confirm that the requests to your Webhook URL are sent from the Craftgate system, the x-cg-signature-v1 value sent between HTTP headers must be checked. You can find details on our Webhook page.

E. Security Measures for Payments Made via Common Payment Form​

How should security checks be performed for payments made via a common payment form?​

In payments made through the common payment form, as a result, token information associated with the payment is returned to the merchant's callback address. (See Payments via Common Payment Page) With this token information, withdraw the payment from Craftgate common payment page payment inquiry service. (See Common Payment Page Payment Inquiry) Compare the success status of the payment from the payment details returned to you, the values that have special meaning for you, such as the conversation id and external id you transmitted, and the order you checked. In this way, you can be sure that a reliable return is made about the order you checked.

F. Error Management in terms of Security​

How should we interpret error groups?​

If the payment transaction results in an error at the bank, Craftgate groups and categorizes the error according to the detail of the error and returns you with the most accurate error detail. You can find the error group in the error group field in the payment response and the cause of the error in the error description. If you wish, you can show this error message directly to your user or you can show your own error message according to the error group.

If a payment error is received with LOST_CARD, STOLEN_CARD, PICKUP_CARD error groups, the user should be followed up. For errors such as NOT_SUFFICIENT_FUNDS, RESTRICTED_BY_LAW, the user can be informed and the payment can be tried again.

You can find details on our Error Groups page.