Common Payment Page

Payments made via the Common Payment page take place in two steps: initiation and completion. The initiation request will return a token from the Craftgate API and the pageUrl containing the URL of the payment page. Then the user completes the payment by visiting this URL. The status of the completed payment is transmitted to the address given in the callbackUrl parameter in the initiation request and ensures the end-to-end completion of the process. In addition to the callbackUrl parameter, if the merchantWebhookUrl parameter is sent, the server sends token information in json format to this address by HTTP POST method.

Initiating Payment with the Common Payment Page

URL

The endpoint and http method information to initiate payment with common payment page are stated below.

HTTP Method URL
POST /payment/v1/checkout-payments/init

Payment Initiation Request Parameters

Unlike other payments, the callbackUrl parameter must be sent for payments to be made via the common payment page and card information is not expected. The cardUserKey parameter can be filled in so that the relevant user can use the stored cards. In this context, the parameters required to initiate a payment with the common payment page are as follows.

Parameter Name Type Required Description
conversationId string No "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.
externalId string No 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.
bankOrderId string No 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.
price decimal Yes Total basket price. The sum of the item prices in the basket must be equal to total basket price.
paidPrice decimal Yes 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.
buyerMemberId number No ID of the buyer that is returned from member creation.
currency Currency Yes See: Currencies
paymentGroup PaymentGroup No See: Payment Groups
paymentPhase PaymentPhase No See: Payment Phases - For Post Auth See: Post Auth
paymentChannel string No 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.
callbackUrl string Yes The URL to be used to send the result returned from the bank to the merchant
cardUserKey string No Card user key that represents the card holder.
enabledInstallments number[] No Indicates the installments to be shown in the payment step. If these installment options are not active on the pos, the installment options will not be displayed. If not sent, all installment options are returned.
allowOnlyCreditCard boolean No If true, payment form only allows credit card for the payment.
allowOnlyStoredCards boolean No If true, the user can only pay using their stored card. cardUserKey parameter is required, if this parameter is true.
alwaysStoreCardAfterPayment boolean No If true, card number that the user is used for the payment will be stored. If this parameter is true, allowOnlyStoredCards should not be sent.
allowInstallmentOnlyCommercialCards boolean No If true, installment options are only valid for the commercial cards.
forceAuthForNonCreditCards boolean No If true, authorization payment is forced for non credit cards.
forceThreeDS boolean No Information on whether 3DSecure payment is required.
items PaymentItem[] Yes (See: Payment Item Information) 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.
masterpassGsmNumber string No (See: Masterpass) If the user is required to pay with Masterpass, the phone number associated with the user's Masterpass must be entered starting with 90. If you do not enter it or if the phone number you entered has not been linked with Masterpass before, the Masterpass tab will not be opened in the payment form.
masterpassUserId string No (See: Masterpass) If the user is required to be able to pay with Masterpass, and the user's Masterpass account has been previously linked with the merchant through an environment other than the Craftgate integration, the userId value used in the link phase.
apmUserIdentity string Hayır (See. Payoneer) If the user is required to be able to pay with Payoneer, the unique value associated with the user.
enabledPaymentMethods PaymentMethod[] No You can manage the payment methods to be displayed on the Payment Form with this parameter. If this parameter is [CARD], payment form accepts only card payment. See all available payment methods (see. Payment methods) . All available payment methods are shown when the parameter never sent.

Response Parameters

The parameters returned as a result of the payment transaction with the common payment page are 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:

Parameter Name Type Always Exist Description
token string Yes Token of the payment form generated by the payment form initiation
pageUrl string Yes URL of the payment page

Optional parameters for the checkout page

In addition to the URL returned in the pageUrl field, the following parameters can be added.

Parameter Name Description
iframe If true payment page will be displayed as iframe.
animatedCard If true card animation will be displayed in the payment page.

Parameters Forwarded to Callback URL

The following parameters are forwarded as form variables using the HTTP POST method. The parameters included in the request to callbackUrl by Craftgate after validation are as follows:

Parameter Name Type Always Exist Description
token string Yes Token of the payment form generated by the payment form initiation

Parameters Forwarded to Merchant Webhook URL

The following parameters are forwarded as json using the HTTP POST method. The parameters in the request to merchantWebhookUrl by Craftgate after verification are as follows:

Parameter Name Type Always Exist Description
token string Yes Token of the payment form generated by the payment form initiation

Common Payment Page Payment Inquiry

With the token forwarded to the callback URL, the result of a payment made using the common payment page can be queried.

URL

The endpoint and http method information to inquiry payments that are made via common payment page are stated below.

HTTP Method URL
GET /payment/v1/checkout-payments/:token

Common Checkout Page Checkout Inquiry Response Parameters

The response to inquiry requests for payments made via the Common Payment Page is equivalent to a standard payment and includes details about the payment. For the format of this answer and the parameters it contains, see Create Payment - Response Parameters

Sample Codes

You can review the sample codes in the open source Craftgate API clients.

Initiating Payment with the Common Payment Page

Common Payment Page Payment Inquiry