Skip to main content

Using Rewards and Points

While making payments through Craftgate, you can query the points offered by banks to their customers, additional installments, skipping installments, and use these rewards during payment.

During the integration phase, you can use the cards on the Reward and Point Featured Test Cards page while testing various scenarios regarding award inquiry and use.

Note: Rewards or points cannot be used for payments that are fully collected from the wallet.

Reward Inquiry​

Before the payment process, you can query the rewards and points offered by the bank to the customer by using the open or stored card information as follows.

It is sufficient to send one of the open or stored card information for the reward/point inquiry process.

URL​

The endpoint and http method information to retrieve card loyalties are stated below.

POST/payment/v1/card-loyalties/retrieve

Request Parameters ​

It is enough to send one of the open or stored card information for the card loyalty inquiry process.

Inquiry with Open Card Information ​

cardNumber
string
required

Card number

expireYear
string
required

Expire year of the card number

expireMonth
string
required

Expire month of the card number

cvc
string

CVV of the card number. Required when the POS that is used to inquire reward information doesn't support payment without CVC

clientIp
string

IP of the buyer.

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.
Special characters that may cause security problems should not be used in the data. Data cannot start with the + or - character, but it can be used in it.

fraudParams
FraudCheckParameters

Parameters that can be sent for Fraud check. (See. Fraud Check Parameters)

Inquiry with Stored Card Information ​

cardUserKey
string
required

Card user key that represents the card holder.

cardToken
string
required

Card token that represents the card.

Response Parameters ​

The parameters returned as a result of the query process 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:

cardBrand
string

Card brand

cardIssuerBankName
string

Name of card issuer bank

cardIssuerBankId
number

Id of card issuer bank

force3ds
boolean

Information on whether 3DSecure payment is required. If the card used is debit and 3DSecure requirement is checked for the pos from the merchant panel, it returns true. If true is returned, the payment must be made through 3DSecure.

pos
MerchantPos

POS info that reward is inquired (See: Merchant POS Information)

fraudResult
FraudResult

The result of fraud checks applied as a result of the inquiry

loyalties
Loyalty[]

List of points and rewards after reward inquiry from bank (See: Loyalty Detail)

Loyalty Detail ​

It contains detailed information for a reward defined to the customer. The areas it hosts differ according to the type of loyalty.

type
string

Reward type (See: Reward Types)

reward
Reward

Available only for point type rewards. It includes the items of points available to the customer. (See: Point Information)

message
string

Available for types other than points. It contains the reward detail provided by the bank of the relevant type.

Point Information ​

It contains the point information defined for the customer. You can show the sum of these figures on the payment screen and send their breakdown while making the payment.

cardRewardMoney
decimal

Amount of points for general use defined on the customer's card. This field is not included if there is no score information defined.

firmRewardMoney
decimal

The amount of points defined specifically for the merchant of the customer. This field is not included if there is no score information defined.

Reward Usage ​

Only one reward can be used during the payment process. General and special points can be used at the same time for point type reward usage.

In order to use the reward, it is sufficient to transmit the award information to a loyalty field in the card information, along with other payment information during the payment process ( see: Create Payment).

Reward Information to be Used​

It contains the details of the reward to be used. Fields required to be submitted differ depending on the type of reward.

type
string

Reward type (See: Reward Types)

reward
Reward

It should only be sent for points-type rewards.

Point Usage Parameters​

cardRewardMoney
decimal

Amount of points for general use defined on the customer's card. This field is not included if there is no score information defined.

firmRewardMoney
decimal

The amount of points defined specifically for the merchant of the customer. This field is not included if there is no score information defined.

Response Parameters​

The award information used in the payment is returned in the loyalty field in addition to other information returned as a result of the payment transaction. The information returned includes the parameters specified in the Loyalty Detail section.

Sample Codes​

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

Retrieve Loyalties​

Java.NETPHPNode.jsGoPython

Loyalty Usage in Payment​

Java.NETPHPNode.jsGoPython