Fetch Promotion (GoPay Tokenization)

Fetch promotion is triggered to fetch available GoPay promotions based on user account and transaction amount. Merchants can then show the available promotion on the merchant's page and have customers pre-select the promo and apply it when charging.

This feature is only available for GoPay Tokenization.


📘

Fetch Promotion currently is only available in Production.

To enable Fetch Promotion, please contact your Midtrans Sales PIC or Midtrans Support.

📘

Fetch Promotion API can also be used alongside with BI-SNAP account linking flow

Merchant can also calls the Fetch Promotion API using BI-SNAP account linking flow with the adjustment as follows:

  1. Merchant don't need to pass Midtrans account ID in the query paramater. Merchant will only need to call this endpoint with these query parameters: BASE_URL/v2/gopay/promo/?gross_amount={gross_amount}&currency={currency}
  2. Merchant to pass Authorization-Customer token acquired from BI-SNAP account linking in the request header: Authorization-Customer: Bearer <BI-SNAP authorization-customer token>

Fetch Promotion Request

HTTP MethodEndpointDefinition
GETBASE_URL/v2/gopay/promo/{account_id}?gross_amount={gross_amount}&currency={currency}Fetch available promotions

JSON AttributeDescriptionTypeRequired
account_idCustomer account id to be used for paymentStringRequired
gross_amountTransaction gross amountStringRequired
currencyTransaction currency. Default: IDRStringOptional



Fetch Promotion Response

{
    "account_id": "00000269-7836-49e5-bc65-e592afafec14",
    "status_code": "200",
    "recommended_promotion_id": "CASHBACK|acbec7d4-b30b-44ac-9c42-f5d767419a72|8bb3c041-c71e-40f3-892b-688fda2ec979||2021-02-22|2021-02-23",
    "promotions": [
        {
            "id": "CASHBACK|acbec7d4-b30b-44ac-9c42-f5d767419a72|8bb3c041-c71e-40f3-892b-688fda2ec979||2021-02-22|2021-02-23",
            "code": "100PCCASHBACK",
            "type": "CASHBACK",
            "actual_payable_amount": "100.00",
            "promotion_amount": "100.00",
            "minimum_applicable_amount": "100.00",
            "currency": "IDR/SGD/VND/THB",
            "description": "100 percent cashback",
            "short_description": "short-desc",
            "title": "100PCCASHBACK",
            "valid_from": "2021-02-22 17:00:00",
            "valid_till": "2021-02-23 17:00:00",
            "tnc_url": "",
            "limit_per_user": 15,
            "source": "GOPAY_PROMO",
            "promotion_value": {
                "money": {
                    "type": "PERCENTAGE",
                    "value": "100"
                }
            }
        }
    ]
}

{
   "account_id": "00000269-7836-49e5-bc65-e592afafec14",
   "status_code":"200",
   "promotions":[]
}
{
  "id": "00000269-7836-49e5-bc65-e592afafec14",
  "status_code": "400",
  "status_message": "Account doesn’t exist"
}
{
  "id": "00000269-7836-49e5-bc65-e592afafec1",
  "status_code": "400",
  "status_message": "One or more parameters in the payload is invalid.",
  "validation_messages": [“gross_amount is required”]
}
JSON AttributeDescriptionType
account_idCustomer account id to be used for paymentString
status_codeStatus code of the API resultString
recommended_promotion_idRecommended promotion id based on order detailsString
promotionsList of applicable GoPay promotion informationArray
   idPromotion id. Will be used in Charge API to apply promotion.String
   codePromotion codeString
   typePromotion typeString
   actual_payable_amountTransaction gross amountString
   promotion_amountPromotion/cashback amountString
   minimum_applicable_amountMinimum transaction amount for promotionString
   currencyCurrencyString
   descriptionPromotion descriptionString
   titlePromotion titleString
   valid_fromStart of promotion periodString
   valid_tillEnd of promotion periodString
   tnc_urlTerms & condition urlString
   limit_per_userMaximum usage per user within promotion periodString
   sourcePromotion sourceString
   promotion_valuePromotion valueObject