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.

HTTP Method URL
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

Parameter Name Type Required Description
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 No CVV of the card number. Required when the POS that is used to inquire reward information doesn't support payment without CVC

Inquiry with 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.

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:

Parameter Name Type Description
cardBrand string Card brand
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)
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.

Parameter Name Type Always Exist Description
type string Yes Reward type (See: Reward Types)
reward Reward No Available only for point type rewards. It includes the items of points available to the customer. (See: Point Information)
message string No 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.

Parameter Name Type Always Exist Description
cardRewardMoney decimal No 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 No 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.

Parameter Name Type Always Exist Description
type string Yes Reward type (See: Reward Types)
reward Reward No It should only be sent for points-type rewards.

Point Usage Parameters

Parameter Name Type Required Description
cardRewardMoney decimal No 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 No 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

Loyalty Usage in Payment