API ReferenceSign In

Credit Card Promotions

Last updated 05/13/2020

A great way to attract more customers is to offer discounts based on the type of card that they use. Issuing banks often collaborate with merchants to provide discounts to users if they choose to use their cards. An important feature in the payment flow is the ability to check if the card number entered by a user is issued by a specific bank.

Xendit's Promotion APIs fully support such promotions. They allow you to create a Promotion and select a range of credit card Bank Identification Numbers (BINs) to whitelist (BINs are the first 6 digits of a card, e.g. 480012). During the card payment process, send us a request to GET a Promotion Calculation. If an applicable Promotion for the type of card exists, Xendit automatically applies the promotion discount rate and returns you the information so you can charge the discounted amount.

User Journey

1. You partner with an issuing bank (for example, BCA in Indonesia) to offer discounts to your customers, on transactions using BCA credit/debit cards.

2. The Promotion has these details:

  • BCA-issued credit / debit cards. Usually, issuers will provide you with a list of BINs eligible for the Promotion. Let's say BCA gives you 400001, 400002, 400003.
  • 20% discount on all transactions
  • Runs from 1 December 2020 to 31 December 2020

3. You want Xendit to help with:

  • setting up a Promotion
  • detecting when a BCA card is used for a transaction
  • informing you that there is an active Promotion for this transaction
  • calculating the discount, and returning the final (discounted) amount

You create a Promotion in Xendit

3. This sets up the Promotion in our system so that for every card transaction you process with us, we will check if it qualifies for the Promotion and apply the discount if so.

4. Send a Create Promotion API request to Xendit, with the following request body:

      "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"

See our Promotions API reference for details.

You can also use promo codes to create Promotions, but for this sample User Journey we'll use BINs.

5. You will receive a response that the Promotion has been successfully created, with details of the Promotion.

Your end user starts the payment process on Xendit

6. On your merchant user interface, your end user hits the checkout page. The transaction amount to be charged is generated, and your end user is asked to enter credit card details into your form.

7. Your end user enters their card number into your checkout page, and you send the transaction amount and card BIN to the Xendit Get Promotions Calculation API. Integrate with our xendit.js Javascript library to seamlessly enable this process.

8. Xendit looks up the BIN and checks if it is whitelisted in any active Promotions.

9. If it is not, we return you a null response. You can proceed to charge the card at the original amount.

10. If the BIN is whitelisted in an active Promotion, we return a response with the details of the Promotion including the final_amount, which is the original transaction amount less the discount.

11. You can handle this final_amount on your UI (as well as the description you configured) to inform the end user of the Promotion and the discount.

Your end user completes credit card payment

12. Your end user confirms payment on your UI (e.g. by clicking a Pay button).

13. If you are integrated with xendit.js, this should tokenize the card and initiate 3DS authentication.

14. After 3DS authentication is verified, you send Xendit a Create Charge API request using the token_id, which contains details of the Promotion, and the final_amount.

15. Once the Charge is successful, we return our standard Charge API response with additional details under the promotion object: the reference_id and the original_amount. This is to enable you to reconcile which transactions have had a Promotion applied to them.

Available Channel Codes for use with Promotions

When you enter any one of these Channel Codes into the channel_code field in the Create Promotion API request, we will automatically whitelist all the BINs in our database corresponding to that channel for that created Promotion.

ChannelChannel Code
Bank Central AsiaBCA
Bank Rakyat IndonesiaBRI
Bank Negara IndonesiaBNI
Bank MandiriMANDIRI
Bank Tabungan NegaraBTN
Panin BankPANIN
Bank Maybank IndonesiaMAYBANKID
Bank PermataPERMATA
Standard Chartered BankSCB

How to use Promotions with Xendit

If you're clear on how Promotions work from the user journey above, check out our Integration and Testing - Promotions page to see how you can get started!