Promotions API

Overview

Boost your sales, increase customer loyalty, and reach audiences of the largest banks in the Philippines through PayMongo Promotions.

• Set up promos that apply to all cardholders, giving you full flexibility to launch discounts whenever you need.
• Partner with top banks in the Philippines to offer BIN-specific promos, giving you access to their customer base and driving more transactions from their cardholders.

Learn more about PayMongo Promotions here!

Applying Promotions through the Payment Intent Workflow

The payment intent workflow is the main workflow used to make payments via PayMongo. To enable Promotions, a few additional steps just need to be added to the existing workflow.

The payment intent workflow is the main workflow used to make payments via PayMongo. Applying promotion just needs extra steps.

1. Get Available Promos
First, you need to make a GET request (/v1/promotions/available?amount={amount}) to get all available promotions.

URL Parameters

Sample GET Response

{
    "has_more": false,
    "data": [
        {
            "id": "promo_xxx",
            "type": "promotion",
            "attributes": {
                "bank_name": "Bank",
                "budget_limit": 10000,
                "card_limit": 2,
                "description": "Sample  Fixed Amount Promotion",
                "discount_type": "fixed_amount",
                "discount": 10,
                "livemode": true,
                "max_percentage_discount": null,
                "min_transaction_amount": 2000,
                "name": "Fixed promo",
                "organization_id": "org_xxx",
                "payment_method": "card",
                "promo_type": "automatic",
                "status": "live",
                "usage_limit": 100,
                "discounted_amount": 10000,
                "promotion_bins": [],
                "start_at": 1727436300,
                "end_at": 1730033940,
                "terminated_at": null,
                "created_at": 1727436241,
                "updated_at": 1727436241
            }
        }
  ]

2. Create Payment Intent

3. Create Payment Method

4. Attach the payment method to the created payment intent, to apply promotion you need pass promotion_id (you can get this from Get Available Promos API) as additional payload attribute.

Sample Payload

{
    "data": {
        "attributes": {
            "payment_method": "pm_xxx",
        "promotion_id" : "promo_xxx" // Optional 
        }
    }
}

5. Once the customer has successfully paid, the payment intent status will transition tosucceeded

To determine if the payment has already been paid, a webhook call will be made to the nominated and registered webhook endpoint subscribed to the payment.paid event. You may refer to our Webhook API to learn more. You may also check the status of the payment intent through the Retrieve a Payment Intent API.

Payments with promotion returns promotion attribute to display all necessary promo details.
Retrieve a Payment

Sample GET response

{
   "id":"pay_xxx",
   "type":"payment",
   "attributes":{
      "amount":5000,
      "billing":{
         "address":{
            "city":"Furview",
            "country":"PH",
            "line1":"111",
            "line2":"Wanchan St",
            "postal_code":"11111",
            "state":"Metro Manila"
         },
         "email":"[email protected]",
         "name":"Zooey Doge",
         "phone":"111-111-1111"
      },
      "currency":"PHP",
      "description":"Payment 1",
      "fee":1850,
      "livemode":false,
      "net_amount":8150,
      "payout":null,
      "promotion": {
                 "id": "promo_xxx",
                 "description": "Sample  Fixed Amount Promotion",
                 "transaction_amount": 10000,
                 "discount": 5000
  }
      "source":{
         "id":"tok_X925Gje9FzRxfZCiBzNaSCbE",
         "type":"token"
      },
      "statement_descriptor":null,
      "status":"paid",
      "created_at":1586093053,
      "paid_at":1586093053,
      "updated_at":1586093053
   }
}