Create Payment

URL

The endpoint and http method information to create payment are stated below.

HTTP Method URL
POST /payment/v1/card-payments

Request Parameters

The parameters expected to be sent in requests to create payment are listed under the table and subheadings below.

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.
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.
walletPrice decimal Yes The amount to be collected from the wallet of the buyer specified in the buyerMemberId parameter. It is required when wallet want to be used for the payment. (Default: 0)
installment number Yes Installment number. Should be 1 for cash price.
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
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.
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.
clientIp string No IP of the buyer.
card Card No (See: Card Information) Should not be sent when payments that will be collected entirely from the wallet (ie. payments where paid price is equal to wallet Price)
posAlias string No Represents the POS that payment will be collected.
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.
additionalParams map<string, map> No Additional parameters related to payment. See: Payment Additional Parameters

Card Information

Card information must be sent when payments are made by card in whole or in part. This information may be the information of a credit card, debit card or prepaid card, as well as identifying information about a previously stored card.

If the cardUserKey field in the card information is set, the fields in the Stored Card Information section are valid. For other cases, see: Credit Card, Debit Card or Prepaid Card Information.

If you are from the insurance sector, and you want to make a payment with the first 6 and last 4 digits of the card number and TCKN/VKN information, the fields are valid on the Card Information Required for Payment with First six, Last four and TCKN Exclusively for the Insurance Sector . In order to use this feature, your virtual POS must support this feature.

Credit Card, Debit Card or Prepaid Card Information

Parameter Name Type Required Description
cardAlias string No Name or description of the card
cardHolderName string Yes Card holder name
We do not allow the following characters: \<>"%;&+()|=! and numbers
cardNumber string Yes Card number
expireYear string Yes Expire year of the card number
expireMonth string Yes Expire month of the card number
cvc string Yes CVV of the card number
storeCardAfterSuccessPayment boolean No Set this parameter true if card wants to be stored after successful payment? (Default: false)
cardUserKey string No Card user key that represents the card holder.
loyalty Loyalty No Reward information requested to be used during payment. (See: Reward Usage)

Stored Card Information

Parameter Name Type Required Description
cardUserKey string Yes Card user key that represents the card holder.
cardToken string Yes Card token that represents the card.
loyalty Loyalty No Reward information requested to be used during payment. (See: Reward Usage)

Card Information Required for Payment with First six, Last four and TCKN Exclusively for the Insurance Sector

Parameter Name Type Required Description
binNumber string Yes First 6 digits of the card number
lastFourDigits string Yes Last 4 digits of the card number
cardHolderIdentityNumber string Yes Identity number of the card holder

Payment Item Information

It is mandatory to send 1 or more than 1 payment item in all payments. The sum of the price fields of the submitted items must equal the value in the price field of the payment.

Parameter Name Type Required Description
name string No Name of the payment item
price decimal Yes Basket price of the payment item
externalId string No It is generally used as an order number or basket number on the merchant side.
subMerchantMemberId number No Sub-merchant ID that returns in Create Member
subMerchantMemberPrice decimal No Sub-merchant payout amount for the payment item. Required when subMerchantMemberId field is sent.

Payment Additional Parameters

Parameter Name Type Required Description
paymentProvider map<string, map> No Required when it is desired to receive payment with a stored card number in another payment provider. It is expected to send cardUserKey and cardToken in it.

For example, when it is desired to make a payment with a card stored in İYZİ ÖDEME VE ELEKTRONIK PARA HIZMETLERI, the following JSON block should be sent instead of the card field in the payment request. The cardUserKey and cardToken here are sent to iyzico and payment is attempted with the card stored there.

{
    ...,
    "paymentProvider": {
        "cardUserKey": "aaf4e557-8bd0-47d6-86ae-7aa59c30c5a2",
        "cardToken"  : "82b413a5-605f-4389-83cf-bc933da9e5df"
    }
}

In case the payment is received, the following information belongs to the card will be blank in the response parameters.

  • binNumber
  • lastFourDigits
  • cardType
  • cardAssociation
  • cardBrand

Response Parameters

Parameters returned as a result of 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:

Parameter Name Type Description
id number ID of the payment.
createdDate date The date that payment is created
price decimal Basket price of the payment
paidPrice decimal Paid price of the payment
walletPrice decimal Wallet price of the payment
currency Currency See: Currencies
buyerMemberId number Buyer member ID of the payment
installment number Installment number
conversationId string Value of theconversationId parameter sent in the payment request
externalId string externalId value that sent in payment request by merchant
paymentType PaymentType See: Payment Types
paymentGroup PaymentGroup See: Payment Groups
paymentSource PaymentSource See: Payment Sources
paymentStatus PaymentStatus See: Payment Status
paymentPhase PaymentPhase See: Payment Phases
paymentChannel string paymentChannel value sent by the merchant in the payment request
isThreeDS boolean Indicates whether the payment is 3D Secure payment
merchantCommissionRate decimal Interest rate to calculate paid price that buyer will pay
merchantCommissionRateAmount decimal Interest amount. Equal to the difference between paidPrice and price values
bankCommissionRate decimal Bank commission rate
bankCommissionRateAmount decimal Bank commission rate amount
cardUserKey string Card user key that represents the card holder.
cardToken string Card token that represents the card.
paidWithStoredCard boolean Indicates whether the payment was made with a stored card
binNumber string Exist for the payments fully or partially collected from the card. First 8 digits of the card
lastFourDigits string Exist for the payments fully or partially collected from the card. Last 4 digits of the card
cardHolderName string Card holder name surname
bankCardHolderName string Card holder name surname retrieved from bank
authCode string authCode value retrieved from bank related to the payment
hostReference string hostReference value retrieved from bank related to the payment
transId string transId value retrieved from bank related to the payment
orderId string orderId value retrieved from bank related to the payment
cardType CardType (See: Card Types)
cardAssociation CardAssociation (See: Card Associations)
cardBrand string Brand of card. Exist for the payments fully or partially collected from the card
requestedPosAlias string Value of theposAlias parameter sent in the payment request
pos MerchantPos POS info that payment is received. See: Merchant POS Information
loyalty Loyalty Loyalty info that used in payment (See: Reward Usage)
fraudId number Fraud Check Id if fraud rule matches (See: Fraud Checks)
fraudAction FraudAction Fraud Check Action if fraud rule matches (See: Fraud Actions)
paymentTransactions PaymentTransaction[] See: Payment Transactions Response Information
additionalData map<string, map> See: Payment Result Additional Data

Payment Transactions Response Information

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.

Parameter Name Type Description
id number ID of the payment transaction
externalId string External ID of the payment item that is sent in the request
name string Name of the payment item that is sent in the request
price decimal Basket price of the payment item
paidPrice decimal Paid price of the payment item
walletPrice decimal Wallet price of the payment item
merchantCommissionRate decimal Merchant's interest rate of the payment transaction
merchantCommissionRateAmount decimal Merchant's interest rate amount of the payment transaction
merchantPayoutAmount decimal Merchant's payout amount of the payment transaction
subMerchantMemberId number ID of the sub-merchant
subMerchantMemberPrice decimal Sub-merchant requested payout amount for the payment item.
subMerchantMemberPayoutRate decimal Sub-merchant payout rate for the payment item.
subMerchantMemberPayoutAmount decimal Sub-merchant payout amount for the payment item.
transactionStatus TransactionStatus See: Payment Item Confirmation Status Status of payment transaction confirmation
blockageResolvedDate date Date that the blockage will be resolved
payout Payout (ee: Payment Transactions Distribution of Payout

Payment Transactions Distribution of Payout

It includes the distribution of the money transfer to be made in relation to the payment, in a transaction specific, between the merchant, the sub-merchant and Craftgate.

The currency of the money distribution is always TRY.

Parameter Name Type Description
paidPrice decimal Total paid price of the payment transaction
parity decimal Foreign currency rate, for TRY payment it would be 1.
currency Currency See: Currencies
merchantPayoutAmount decimal Payout amount of the merchant
subMerchantMemberPayoutAmount decimal Payout amount of the sub-merchant

Payment Result Additional Data

Parameter Name Type Description
campaignUrl string This parameter is valid for merchants that have an additional installment agreement with Garanti bank. It contains the URL to be shown to the buyer as a result of installment transactions to make additional installments.

Merchant POS Information

Parameter Name Type Description
id number ID of the POS
name string Name of the POS
alias string Alias of the POS
bankId number Bank of the POS

Sample Codes

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