Promotions API
How do I integrate Promotions into my online checkout?
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
Parameter | Required | Remarks |
---|---|---|
amount | required | |
card_number | optional | This parameter is optional, you can use this to filter the promotions based on the card number |
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
}
}
]
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
}
}
Updated 27 days ago