English
API ReferenceSign In

Credit Card Promotions

Last updated 03/04/2021

Before you begin implementing our Credit Card Promotions feature, you will have to implement a solution for collecting and tokenizing your customers' cards, 3DS authentication, as well as creating charges.

Create Promotion

To set up a Promotion in Xendit, you'll need to write a function to send an API call to our Create Promotion API endpoint. See the API references for this here, and a sample API request below.

{
  "reference_id": "BCA_20_DEC",
  "description": "This card is eligible for a 20% discount!",
  "transaction_limit": 0,
  "type": "CARD_BIN",
  "bin_list": [
    "400001",
    "400002",
    "400003"
  ],
  "discount_percent": 20,
  "currency": "IDR",
  "start_time": "2020-12-01 00:00:00.000Z",
  "end_time": "2020-12-31 23:59:59.000Z"
}

Get Promotions Calculation

Once you've configured a Promotion, you will need to implement our Get Promotions Calculation API into your payment flow so that this endpoint can receive an end user's card BIN, or Promo Codes which they enter, from you. It will then check if the BIN or Promo Code is eligible for a Promotion, and return the Promotion details as well as the discounted transaction amount for you to create the Charge.

We recommend integrating with our Javascript library xendit.js for this process.

The relevant function in xendit.js is as follows:

Card.prototype.calculatePromotion = function (promoData, callback) {
   this._getPromotionCalculation(promoData, function (err, promotionResponse) {
       if (err) {
           return callback(err);
       }
       callback(null, promotionResponse);
   });
}

How this function works:

  1. Your end user enters the card BIN on the form in your UI

  2. You will need to implement logic to collect the BIN and original transaction amount data and store it in your UI form.

  3. The logic will need to retrieve this data from the form, and input it into the xendit.js function above.

  4. The promoData function should be populated with the BIN and original transaction amount in this way:

Method Signature: calculatePromotion(promoData, callback)

ArgumentsArgument Schema
promoData{ “bin”: “466160”, “amount”: 100000, “promo_code”: “TEST_PROMO” }
callback(err, promotionResponse)` Callback function will be called with the following parameters: err: { ‘error_code’: ‘BIN_INVALID’, ‘message’: ‘...’ } promotionResponse: [{ “reference_id”: “MARCH_JENIUS_20”, “final_amount”: 80000, “original_amount”: 100000, “discount_amount”: 20000, “currency”: “IDR”, “description”: “This card is eligible for a 20% discount!”}]
  1. The xendit.js function above will call the Xendit Get Promotions Calculation endpoint.

Note that you can do the above even while the end user is entering the BIN (1st 6 digits) into the form, before they complete entering the full card number. You simply have to write a logic that will listen for the BIN being entered, and collect that data immediately after it is entered.

Of course, you can also wait for the end user to finish entering the card number, and to take another action (such as clicking Pay). You can then send the BIN and original transaction amount to the Get Promotions Calculation API endpoint upon that action. How you wish to implement this depends on your preference.

  1. If there is an active Promotion which matches the BIN or Promo Code you have entered, a response will be returned with the final_amount, which is the original transaction amount less the discount.

  2. You should expose this amount to your UI and inform your end user that a discount has been applied, and that they must now pay the final_amount for the transaction.

  3. Once your end user confirms payment, you should use the final_amount to perform Tokenization, Authentication and create a Charge on the Xendit Credit Cards API.

Creating a discounted Charge for a transaction

If an end user's card is eligible for an active Promotion, and a final_amount has been returned for you to make the Charge, then after Tokenization and Authentication, you should send a Charge request with the final_amount value as the amount value in the Charge API. You will also need to include a new promotion object in the Charge API request, as follows:

promotion:
          reference_id: "MARCH_JENIUS_20",
          original_amount: 100000

Where original_amount is the original transaction amount (before the discount was applied).

We need these details so that we will return them to you in the Charge response. You can then use them for reconciliation, to check which of your card transactions have had a Promotion applied.

Promotions Testing Page

We've built a page for you to test sending Get Promotion Calculations requests before you integrate. Try it out here. You'll need your Public API key, which you can obtain from registering on our Dashboard and heading to the Settings page.