The endpoint and http method information to create payment are stated below.
HTTP Method | URL |
---|---|
POST |
/payment/v1/card-payments |
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 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.
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) |
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) |
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 |
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. |
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
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 |
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 |
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 |
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. |
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 |
You can review the sample codes in the open source Craftgate API clients.