Skip to main content

Payment with GarantiPay (v1)

To get paid with GarantiPay, the first step is to initiate a payment on Craftgate. Afterwards, the payment process is completed by the user through BonusFlaş mobile application. Later, the merchant is triggered with the payment status information who has been given callback URL address in the payment initiation request.

Payment initiation with GarantiPay ​

URL​

The endpoint and http method information to make a payment with GarantiPay are stated below.

POST/payment/v1/garanti-pay-payments

Payment initiation request parameters​

conversationId
string

"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

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.

price
decimal
required

Total basket price. The sum of the item prices in the basket must be equal to total basket price.

paidPrice
decimal
required

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.

installments
GarantiPayInstallment[]

See: GarantiPay Installment Information Installment options that is shown to the user. If not sent, payment processed as cash.

buyerMemberId
number

ID of the buyer that is returned from member creation.

currency
Currency
required

See: Currencies

Values:
TRY
USD
EUR
GBP
CNY
ARS
BRL
AED
IQD
AZN
KZT
KWD
SAR
BHD
RUB
JPY
EGP
paymentGroup
PaymentGroup

See: Payment Groups

Values:
PRODUCT
LISTING_OR_SUBSCRIPTION
paymentChannel
string

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
required

The URL to be used to send the result returned from the bank to the merchant

bankOrderId
string

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.

clientIp
string

IP of the buyer.

posAlias
string

Represents the POS that payment will be collected.

items
PaymentItem[]
required

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.

GarantiPay Installment Information ​

ValueDescription
numberInstallment number
totalPriceTotal amount to be collected

Response Parameters​

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

htmlContent
string

GarantiPay HTML that will be shown to user. Return value must be base64-decoded.

paymentId
number

ID of payment

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:

status
string

Represents GarantiPay verification status. Returns SUCCESS or FAILURE.

conversationId
string

Value of theconversationId parameter sent in the 3DSecure payment initiation

paymentId
number

ID of the payment which is sent when the verification is successful.

callbackStatus
string

Sent as a parameter, n case the bank or end user triggers the 3DS verification step again and the payment has been verified before. Status parameter will be FAILURE and callbackStatus parameter will be ALREADY_RETURNED. In case this field comes with the value of ALREADY_RETURNED, the status of the payment should be checked in your system and no action should be taken if it is completed.

conversationData
string

Returns this security parameter when response status success. Need to send this value in complete step.

hash
string

Response parameters hash value with Sha-256 Hex algorithm. You can find details below on "Creating Hash Value".

Creating Hash Value​

You can make hash validation response with your hash value. You need to use Sha-256 Hex Algorithm to create hash value.

  • You can reach 32 characters key value from following: Merchant Panel -> Yönetim -> Üye İşyeri Ayarları -> "Üye İşyeri Callback Key"
  • You need to prepare input value as in order. Also you need to put "###" as delimiter between parameters.
  • For null values please put empty string ("").

threedSecureCallbackKey###status###completeStatus###paymentId###conversationData###conversationId###callbackStatus

Example of hashing procedure for following response is below. Assume that Üye İşyeri Callback Key value as "merchantCallbackKeySandbox".

{
    "status": "SUCCESS",
    "conversationId": "456d1297-908e-4bd6-a13b-4be31a6e47d5",
    "paymentId": 1,
    "callbackStatus": null,
    "conversationData": null
    "hash": "3a3f520be02eaca2e689d1db855af3925cbdd8db5f850b2b9e61f7ccb9d997b4"
}

Input value for hashing should be like:

merchantCallbackKeySandbox###SUCCESS###1######456d1297-908e-4bd6-a13b-4be31a6e47d5###

You can hash this value via Sha-256 Hex algorithm with Üye İşyeri Callback Key value. Result must be equal with hash value which contains in response.

Sample Codes​

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

Payment initiation with GarantiPay​

Java.NETPHPNode.jsGo