99minds Gift Card APIs are for developers who want to integrate their application with 99minds Gift Card platform. In this guide you'll learn about basic steps for getting started with 99minds Gift Card APIs, including:
\nSign up and create account on 99minds Gift Card platform.
\nGenerating the required API credentials for API access
\nAPI tutorials for making API calls to 99minds Gift Card platform
\nBecause the REST API is based on open standards, you can use any web development language to access our APIs.
\n99minds Gift Card platform uses Bearer Token authentication. Bearer authentication (also called token authentication) is an HTTP authentication scheme that involves security tokens called bearer tokens. The client must send this token in the Authorization header when making requests to protected resources:
Authorization: Bearer <token>\n\nAPI keys can be obtained by creating an API application in the 99minds platform. Visit Settings > API and click on New Application. Once you create a new application, you will be presented with the Key ID and Key Secret.
In addition to API keys, every POST/PUT method in 99minds requires either a store_ref or client_store_id in the request body.
Stores on 99minds serve as a representation of each of your physical retail locations on the 99minds platform. For instance, if you have 10 retail stores and wish to track where gift card sales, redemptions, and other transactions occur, you should create 10 corresponding stores on 99minds (found under the Configure > Stores menu) and obtain the associated store_ref or client_store_id. Each gift card transaction will then be linked to its respective store. However, this is not mandatory. You can opt to use a single store and consistently pass the same store_ref/client_store_id for all transactions, and that would work as well.
All responses HTTP status code will always be 200 OK
The status key inside the response will state the actual status of the response.
The code key inside the response will state the actual error code of the response.
Pagination is provided on all collection APIs.
\nWhen large data sets are returned, the results are paginated. In such cases, a pagination section is included in the response, along with the first page of data.returned in the result set. The first page of data will be returned in the response also.
\n{\n \"data\": {\n \"total_records\": 137,\n \"total_pages\": 2,\n \"current_page\": 2,\n \"next_page\": null,\n \"prev_page\": 1,\n \"giftcards\": [\n { ... },\n { ... }\n ... and 98 other giftcards\n ]\n },\n \"status\": \"OK\",\n \"code\": 200,\n \"message\": null,\n \"errors\": []\n}\n\nYou can request a different page by passing a different page parameter like:
/api/v1/giftcards?page=23\n\nIt is not possible to change the number of objects returned in the response. The default page_size is 100
Requesting subsequent pages is based on a resource specific cursor - an attribute called version which can be found on all collection resources. Here’s an example based on the giftcard resource:
{\n \"version\": 13560,\n \"card_id\": \"card_f4e0071f9c3c67a811\",\n \"batch_id\": null,\n \"active\": true,\n \"giftcard_number\": \"SK2670657708\",\n \"original_value\": \"100.0\",\n \"remaining_value\": \"100.0\",\n \"expiration_date\": null,\n \"campaign_name\": \"doboz\",\n \"campaign_id\": \"campaign_93fb1d07453f5843d8\",\n \"currency\": \"USD\",\n \"created_at\": \"2021-10-11T11:36:21.000Z\"\n}\n\n\n\nNOTE: The
\n_version_attribute is simply a monotonically increasing integer. It is being incremented every time a resource is changed. This is a global parameter and it shouldn’t be assumed that subsequent versions of the same resource will be incremented by 1.
By default, the value of the min_id parameter will be assumed as equal 0 so it’s not necessary to use it on the first page. For a request with no min_id parameter or min_id=0, the first page of products will be returned, even if a resource with version = 0 may not exist in the given collection. The body of the response will contain version with the lowest and highest version number of resources included in the response.
{\n \"data\": {\n \"total_records\": 2156,\n \"total_pages\": 22,\n \"current_page\": 1,\n \"next_page\": 2,\n \"prev_page\": null,\n \"version\": {\n \"min\": 13427,\n \"max\": 13560\n },\n \"giftcards\": [\n { ... },\n { ... }\n ... and 98 other giftcards\n ]\n },\n \"status\": \"OK\",\n \"code\": 200,\n \"message\": null,\n \"errors\": []\n}\n\nThe response to that request should include a collection of 0 to n resources. The upper limit will probably be different depending on the endpoint. The highest version number x from this collection (the max attribute above) should be used to request the next page like:
/api/v1/giftcards?min_id=x\n\nThis should be repeated until an empty collection is returned. This will mean that all items of the collection have been returned.
\nObjects in returned collections will be sorted by the sort parameter which can be either asc or desc. Defaults to desc
99minds rate limits all API requests in a 60-second window. The rate limits are same for all plans.
\nIt allows 150 requests per minute (rpm) per IP address. The API returns an HTTP status code of 429 when rate limited and HTTP status code of 503 when an IP is banned.
\n\n\nNote : Other than artificially rate-limits on the basis of API-requests-per-unit-of-time, there are physical limits to the infrastructure which may limit the maximum throughput of requests on any given API endpoint. 99minds also reserves the right to limit unreasonable or abusive API activity in the interest of platform stability and may even block such requests.
\n
99minds exposes rate limit positioning to applications using the following response headers:
\nWhen 99minds receives a request to an API endpoint, a number of different HTTP status codes can be returned in the response depending on the original request.
\n","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","toc":[{"content":"Authorization","slug":"authorization"},{"content":"Response Format","slug":"response-format"},{"content":"Pagination","slug":"pagination"},{"content":"Rate Limits","slug":"rate-limits"},{"content":"Status Codes","slug":"status-codes"}],"owner":"50030","collectionId":"4802a0e5-767b-428f-a28f-b41289d67163","publishedId":"UUxujq5V","public":true,"customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"FF6C37"},"publishDate":"2023-12-29T18:23:25.000Z"},"item":[{"name":"Gift Card","item":[{"name":"Get Gift cards","id":"051ed7f1-9fea-42eb-a91c-5efd1ae51921","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[{"key":"Content-Type","value":"application/json"}],"body":{"mode":"raw","raw":""},"url":"https://api.giftcard.99minds.io/api/v1/giftcards?page_no=1","description":"This endpoint retrieves a list of all existing gift cards.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"This endpoint retrieves a list of transactions associated with a specific gift card.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"This endpoint retrieves detailed information about a specific gift card, including its balance, expiration date, and status.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"This is used to check if a specific gift card can be purchased.
\nIn systems where transactions are done in 2 or more steps, this endpoint helps you to check whether a gift card can be sold and/or reloaded.
\nIf allow_to_sold is true that means the gift card can be sold.
If amount_load_required is true that means it's a zero value card and amount is loaded at the time of purchase. Remember to pass card_denomination in the Sell API payload. If amount_load_required is false that means the card already has preloaded value and value of card_denomination will be ignored in the Sell API payload.
If reloadable is true that means the gift card can be reloaded.
This endpoint allows you to check the current balance of a specific gift card.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"This endpoint allows you to check the current balance of a specific gift card.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"Allows creation of gift card.
\n\n\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"Please note that when creating a gift card, gift cards are synced to eCommerce platforms and POS if
\nallow_to_soldisfalse.
Allows selling a physical or digital cards with multiple quantities and denominations.
\n\n\nNote: A total of 10 cards can be sold in a single order. This includes the combination of quantity as well as line_items.
\n
Allows selling a physical gift card.
\n\n\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"Please note that when a
\n_receiver_email_is provided, the order will be considered as a Gift
Allows selling a digital gift card.
\n\n\nPlease note that when a
\n_receiver_email_is provided, the order will be considered as a Gift
\n\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"The API doesn't currently support sending scheduled gift orders.
\n
\n\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"Note: Do not use Bulk Redeem API when external gift card processors are connected.
\n
This endpoint allows you to add more value to an existing gift card.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"\n\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"Note: Do not use Bulk Reload API when external gift card processors are connected.
\n
\n\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"Note: Do not use Bulk Refund API when external gift card processors are connected.
\n
This endpoint allows you to extend the expiration date of a gift card.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"This endpoint allow users to redeem all the remaining balance of a gift card.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"This endpoint used to reverse a previous transaction associated with a gift card.
Only REDEMPTION, REFUND, RELOAD, CASHOUT transactions can be reversed.
This endpoint activates a newly created gift card, making it available for use.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"This endpoint deactivates a gift card, preventing it from being used for further transactions.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"This endpoint blocks a gift card, potentially due to fraud or security concerns.
\nBlocking a card does not change the balance on the card.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"This endpoint voids a gift card, rendering it unusable and invalid.
Voiding a card also changes the balance of the card to 0.
This endpoint allows you to add more value to an existing gift card.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"These endpoints return details about Gift cards.
\n","event":[{"listen":"prerequest","script":{"type":"text/javascript","exec":[""],"id":"9dffe9db-3efb-4542-b540-3f42bb440de9"}},{"listen":"test","script":{"type":"text/javascript","exec":[""],"id":"09669b3c-35fa-4cc8-ae3d-77ac8640e917"}}],"_postman_id":"ad749dc2-9ea6-4205-99aa-299f035f114b","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"This endpoint retrieves a list of gift card campaigns.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"Fulfills a line item and assigns a gift card to it.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"Fulfills a line item and assigns a gift card to it.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"Updates greeting message for a line item.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"Updates greeting message for a line item.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"These endpoints return details about Gift cards orders.
\n","_postman_id":"1f2dba3e-1acf-46e4-b2ed-b2f9ce3dbb0a","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"This API endpoint allows you to toggle the status of a store credit card.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"This API endpoint allows you to toggle the status of a loyalty card.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"Retrieve particular coupon by its code
This endpoint retrieves a list of coupon rules.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"Returns customer metrics like total_spend and order_count.
This endpoint triggers and executes all active workflows that are eligible for the specified event or trigger.
\nThe Execute Workflow only respond with an API status code.
Additional attributes are provided on a per-integration basis wherever supported. Please reach out to support for more details.
\nrefund_amount represents the net financial impact of a refund or exchange transaction. It can be positive or negative, depending on the nature of the transaction.
Positive Value: Indicates a net refund to the customer.
\nNegative Value: Indicates a net payment from the customer (typically in an exchange where the new items cost more)
\nRefund: Customer returns an item worth $50 - refund_amount: 50
Exchange (customer pays more): Customer exchanges a $100 item for a $150 item - refund_amount: -50
refund_quantity represents the net change in the number of items resulting from a refund or exchange transaction. Like refund_amount, it can be positive or negative.
Positive Value: Indicates a net decrease in items (typical for refunds).
\nNegative Value: Indicates a net increase in items (possible in some exchanges).
\nRefund: Customer returns 2 items - refund_quantity: 2
Exchange (customer gets more items): Customer exchanges 1 large item for 3 smaller items - refund_quantity: -2
This endpoint triggers and executes a single workflow.
\nRest of the documentation is same as Execute Workflow Request
This endpoint performs a proportional reversal of rewards based on the refund amount relative to the original order amount. It is useful in scenarios such as partial refunds, where only a portion of the originally issued rewards should be revoked.
\nThe reversal behavior is as follows:
\nCoupons: Deactivated
\nGift Cards: Proportionally debited
\nLoyalty Points: Proportionally debited
\nStore Credit: Proportionally debited
\nLet me know if you'd like it rendered or included inline in some docs!
This ensures that rewards are reversed fairly in line with the refunded value, maintaining consistency across reward types.
For refunds, quantity and total in refunded_line_items are negative.
For exchanges, these values would be positive, representing the new items added to the order.
\nThe refund_amount and refund_quantity does not necessarily need to match the sum of the respective values in refunded_line_items.
This structure allows for handling both simple refunds and complex scenarios involving partial refunds or exchanges within the same transaction.
\nNegative quantities and totals in refunded_line_items represent items being returned, while positive values represent items being added (in case of an exchange).
This endpoint fully voids or reverses all rewards issued by a specific workflow. It ensures that no issued reward remains active. The reversal actions taken are:
\nUse this to revoke all reward types associated with a workflow in a single operation.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"This endpoint retrieves a list of VIP tiers.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"This endpoint retrieves a list of transactions associated with a specific VIP tier.
\n","auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":"We retry failed webhook deliveries up to 5 times using exponential backoff with jitter.
\ndelay_seconds = (retry_count ** 6) + rand(30..600)
where retry_count starts at 1 on the first retry, and rand(30..600) adds 30s–10m of jitter to spread out bursts.
Schedule (per attempt after the initial failure):
\n31s – 10m 01s
\n1m 34s – 11m 04s
\n12m 39s – 22m 09s
\n1h 08m 46s – 1h 18m 16s
\n4h 20m 55s – 4h 30m 25s
\nMaximum retry horizon: ~4.5 hours after the first failure.
\nNetwork errors
\nTimeouts
\nHTTP non 2xx responses
\nYour endpoint must be idempotent. We may deliver the same event more than once; use the event id to de-duplicate.
\nReturn 2xx once you’ve persisted the event. If you need to perform long-running work, acknowledge first and process asynchronously.
\norder.fulfilled
{\n \"event\": \"order.fulfilled\",\n \"payload\": {\n \"orderid\": \"order_631a1b0c6b5ecdd6c6\",\n \"order_source\": \"BIGCOMMERCE\",\n \"order_status\": \"FULFILLED\",\n \"client_order_id\": \"2537\",\n \"order_total\": \"50.0\",\n \"currency\": \"USD\",\n \"created_at\": \"2021-08-09T10:07:18.000Z\",\n \"customer\": {\n \"name\": \"Test2 Test\",\n \"email\": \"test40@gmail.com\",\n \"customer_id\": \"user_10afb6532b2ebf44c6\"\n },\n \"items\": [\n {\n \"status\": \"FULFILLED\",\n \"quantity\": 1,\n \"giftcard_value\": \"50.00\",\n \"sender_email\": \"test40@gmail.com\",\n \"receiver_email\": \"jhon@example.com\",\n \"is_gift\": false,\n \"promo_code\": null,\n \"discounted_value\": null,\n \"giftcards\": [\n {\n \"card_id\": \"card_61b859cbc20118f945\",\n \"active\": true,\n \"giftcard_number\": \"1206931451125465\",\n \"original_value\": \"50.00\",\n \"balance\": \"50.00\",\n \"expiration_date\": null,\n \"currency\": \"USD\",\n \"created_at\": \"2021-08-09T10:07:18.000Z\"\n }\n ]\n }\n ]\n }\n}\n\ngiftcard.deactivated
{\n \"event\": \"giftcard.deactivated\",\n \"payload\": {\n \"transaction_amount\": null,\n \"transaction_type\": \"DEACTIVATION\",\n \"transaction_id\": \"transaction_e5bd8049ef9978223f\",\n \"client_order_id\": null,\n \"transaction_date\": \"2021-08-11T15:14:02.000Z\",\n \"giftcard\": {\n \"card_id\": \"card_17660a5ee6c80c8a01\",\n \"batch_id\": \"batch_1c5498d9a3eddeb847\",\n \"active\": false,\n \"giftcard_number\": \"2901706836129251\",\n \"original_value\": \"0.00\",\n \"balance\": \"0.00\",\n \"expiration_date\": null,\n \"campaign_name\": \"HIKE-USD-PHYSICAL\",\n \"campaign_id\": null,\n \"currency\": \"USD\",\n \"created_at\": \"2021-08-02T17:10:02.000Z\"\n },\n \"customer\": {\n \"name\": null,\n \"email\": null,\n \"customer_id\": null\n }\n }\n}\n\ngiftcard.activated
{\n \"event\": \"giftcard.activated\",\n \"payload\": {\n \"transaction_amount\": null,\n \"transaction_type\": \"ACTIVATION\",\n \"transaction_id\": \"transaction_66a9777e8824dcf0c1\",\n \"client_order_id\": null,\n \"transaction_date\": \"2021-08-11T15:25:47.000Z\",\n \"note\": \"Test webhook activated\",\n \"giftcard\": {\n \"card_id\": \"card_17660a5ee6c80c8a01\",\n \"batch_id\": \"batch_1c5498d9a3eddeb847\",\n \"active\": true,\n \"giftcard_number\": \"2901706836129251\",\n \"original_value\": \"0.00\",\n \"balance\": \"0.00\",\n \"expiration_date\": null,\n \"campaign_name\": \"HIKE-USD-PHYSICAL\",\n \"campaign_id\": null,\n \"currency\": \"USD\",\n \"created_at\": \"2021-08-02T17:10:02.000Z\"\n },\n \"customer\": {\n \"name\": null,\n \"email\": null,\n \"customer_id\": null\n }\n }\n}\n\ngiftcard.blocked
{\n \"event\": \"giftcard.blocked\",\n \"payload\": {\n \"transaction_amount\": null,\n \"transaction_type\": \"BLOCK\",\n \"transaction_id\": \"transaction_66a9777e8824dcf0c1\",\n \"client_order_id\": null,\n \"transaction_date\": \"2021-08-11T15:25:47.000Z\",\n \"note\": \"Test webhook blocked\",\n \"giftcard\": {\n \"card_id\": \"card_17660a5ee6c80c8a01\",\n \"batch_id\": \"batch_1c5498d9a3eddeb847\",\n \"active\": true,\n \"giftcard_number\": \"2901706836129251\",\n \"original_value\": \"0.00\",\n \"balance\": \"0.00\",\n \"expiration_date\": null,\n \"campaign_name\": \"HIKE-USD-PHYSICAL\",\n \"campaign_id\": null,\n \"currency\": \"USD\",\n \"created_at\": \"2021-08-02T17:10:02.000Z\"\n },\n \"customer\": {\n \"name\": null,\n \"email\": null,\n \"customer_id\": null\n }\n }\n}\n\ngiftcard.voided
{\n \"event\": \"giftcard.voided\",\n \"payload\": {\n \"transaction_amount\": null,\n \"transaction_type\": \"VOID\",\n \"transaction_id\": \"transaction_66a9777e8824dcf0c1\",\n \"client_order_id\": null,\n \"transaction_date\": \"2021-08-11T15:25:47.000Z\",\n \"note\": \"Test webhook voided\",\n \"giftcard\": {\n \"card_id\": \"card_17660a5ee6c80c8a01\",\n \"batch_id\": \"batch_1c5498d9a3eddeb847\",\n \"active\": true,\n \"giftcard_number\": \"2901706836129251\",\n \"original_value\": \"0.00\",\n \"balance\": \"0.00\",\n \"expiration_date\": null,\n \"campaign_name\": \"HIKE-USD-PHYSICAL\",\n \"campaign_id\": null,\n \"currency\": \"USD\",\n \"created_at\": \"2021-08-02T17:10:02.000Z\"\n },\n \"customer\": {\n \"name\": null,\n \"email\": null,\n \"customer_id\": null\n }\n }\n}\n\ngiftcard.extend_expiry
{\n \"event\": \"giftcard.extend_expiry\",\n \"payload\": {\n \"transaction_amount\": null,\n \"transaction_type\": \"EXTEND_EXPIRY\",\n \"transaction_id\": \"transaction_54f93db91738227a28\",\n \"client_order_id\": null,\n \"transaction_date\": \"2021-08-11T15:31:33.000Z\",\n \"note\": null,\n \"giftcard\": {\n \"card_id\": \"card_a1485b7ed8c5faa697\",\n \"batch_id\": null,\n \"active\": true,\n \"giftcard_number\": \"CHRIS18020212481\",\n \"original_value\": \"18.00\",\n \"balance\": \"18.00\",\n \"expiration_date\": \"2021-12-17\",\n \"campaign_name\": \"Christmas\",\n \"campaign_id\": null,\n \"currency\": \"USD\",\n \"created_at\": \"2021-05-19T10:49:53.000Z\"\n },\n \"customer\": {\n \"name\": \"Gaurav D\",\n \"email\": \"jhon@example.com\",\n \"customer_id\": \"customer_id32cfffa96ba4e22e91\"\n }\n }\n}\n\ngiftcard.reloaded
{\n \"event\": \"giftcard.reloaded\",\n \"payload\": {\n \"transaction_amount\": \"12.0\",\n \"transaction_type\": \"RELOAD\",\n \"transaction_id\": \"transaction_46412ea140f6872029\",\n \"client_order_id\": null,\n \"transaction_date\": \"2021-08-11T15:32:51.000Z\",\n \"note\": \"Test webhook reload\",\n \"giftcard\": {\n \"card_id\": \"card_310d1461d38cddaa5c\",\n \"batch_id\": null,\n \"active\": true,\n \"giftcard_number\": \"3609677699610877\",\n \"original_value\": \"62.00\",\n \"balance\": \"62.00\",\n \"expiration_date\": null,\n \"campaign_name\": \"HIKE-USD-PHYSICAL\",\n \"campaign_id\": null,\n \"currency\": \"USD\",\n \"created_at\": \"2021-08-11T14:52:34.000Z\"\n },\n \"customer\": {\n \"name\": \"John Wick\",\n \"email\": \"jhon@example.com\",\n \"customer_id\": \"customer_idde7038b95037f52de2\"\n }\n }\n}\n\ngiftcard.redeemed
{\n \"event\": \"giftcard.redeemed\",\n \"payload\": {\n \"transaction_amount\": \"25.0\",\n \"transaction_type\": \"REDEMPTION\",\n \"transaction_id\": \"transaction_dc84fd6b2ff21367ef\",\n \"client_order_id\": null,\n \"transaction_date\": \"2021-08-11T15:34:37.000Z\",\n \"note\": null,\n \"giftcard\": {\n \"card_id\": \"card_310d1461d38cddaa5c\",\n \"batch_id\": null,\n \"active\": true,\n \"giftcard_number\": \"3609677699610877\",\n \"original_value\": \"62.00\",\n \"balance\": \"37.00\",\n \"expiration_date\": null,\n \"campaign_name\": \"HIKE-USD-PHYSICAL\",\n \"campaign_id\": null,\n \"currency\": \"USD\",\n \"created_at\": \"2021-08-11T14:52:34.000Z\"\n },\n \"customer\": {\n \"name\": \"John Wick\",\n \"email\": \"jhon@example.com\",\n \"customer_id\": \"customer_idde7038b95037f52de2\"\n }\n }\n}\n\ngiftcard.amount_loaded
{\n \"event\": \"giftcard.amount_loaded\",\n \"payload\": {\n \"transaction_amount\": \"30.0\",\n \"transaction_type\": \"AMOUNT_LOADED\",\n \"transaction_id\": \"transaction_416c3f718c53b12589\",\n \"client_order_id\": null,\n \"transaction_date\": \"2021-08-11T15:41:38.000Z\",\n \"note\": \"Test webhook Loaded\",\n \"giftcard\": {\n \"card_id\": \"card_f707e4ee2c38b7889f\",\n \"batch_id\": \"batch_1c5498d9a3eddeb847\",\n \"active\": true,\n \"giftcard_number\": \"2184071578415366\",\n \"original_value\": \"30.00\",\n \"balance\": \"30.00\",\n \"expiration_date\": null,\n \"campaign_name\": \"HIKE-USD-PHYSICAL\",\n \"campaign_id\": null,\n \"currency\": \"USD\",\n \"created_at\": \"2021-08-02T17:10:02.000Z\"\n },\n \"customer\": {\n \"name\": null,\n \"email\": null,\n \"customer_id\": null\n }\n }\n}\n\ngiftcard.refunded
{\n \"event\": \"giftcard.refunded\",\n \"payload\": {\n \"transaction_amount\": \"13.0\",\n \"transaction_type\": \"REFUND\",\n \"transaction_id\": \"transaction_7eb2f6889a6f8f4418\",\n \"client_order_id\": null,\n \"transaction_date\": \"2021-08-11T15:42:52.000Z\",\n \"note\": \"Test webhook refund\",\n \"giftcard\": {\n \"card_id\": \"card_310d1461d38cddaa5c\",\n \"batch_id\": null,\n \"active\": true,\n \"giftcard_number\": \"3609677699610877\",\n \"original_value\": \"62.00\",\n \"balance\": \"50.00\",\n \"expiration_date\": null,\n \"campaign_name\": \"HIKE-USD-PHYSICAL\",\n \"campaign_id\": null,\n \"currency\": \"USD\",\n \"created_at\": \"2021-08-11T14:52:34.000Z\"\n },\n \"customer\": {\n \"name\": \"John Wick\",\n \"email\": \"jhon@example.com\",\n \"customer_id\": \"customer_idde7038b95037f52de2\"\n }\n }\n}\n\nstorecredit.created
{\n \"event\": \"storecredit.created\",\n \"payload\": {\n \"store_credit\": {\n \"customer_name\": \"MI\",\n \"customer_email\": \"mi@gmail.com\",\n \"customer_id\": \"customer_e09d0e65c9612b26c7\",\n \"card_number\": \"HNV1NK-MFZF\",\n \"balance\": \"0.00\",\n \"card_id\": \"card_2fb7ffcecb3d4f7153\",\n \"last_transaction\": \"CREATION\",\n \"created_at\": \"2021-12-24T09:44:02.000Z\",\n \"transaction\": {\n \"transaction_id\": \"transaction_5b417021e8af3255dd\",\n \"transaction_amount\": \"0.0\",\n \"transaction_type\": \"CREATION\",\n \"transaction_date\": \"2021-12-24T09:44:03.000Z\",\n \"client_order_id\": null,\n \"note\": null\n }\n }\n }\n}\n\nstorecredit.credited
{\n \"event\": \"storecredit.credited\",\n \"payload\": {\n \"store_credit\": {\n \"customer_name\": \"MI\",\n \"customer_email\": \"mi@gmail.com\",\n \"customer_id\": \"customer_e09d0e65c9612b26c7\",\n \"card_number\": \"HNV1NK-MFZF\",\n \"balance\": \"20.00\",\n \"card_id\": \"card_a0d21058dc4ca25fd2\",\n \"last_transaction\": \"RELOAD\",\n \"created_at\": \"2021-12-24T06:40:28.000Z\",\n \"transaction\": {\n \"transaction_id\": \"transaction_7c54945f2b06aa9b02\",\n \"transaction_amount\": \"20.0\",\n \"transaction_type\": \"RELOAD\",\n \"transaction_date\": \"2021-12-24T06:40:32.000Z\",\n \"client_order_id\": null,\n \"note\": null\n }\n }\n }\n}\n\nstorecredit.debited
{\n \"event\": \"storecredit.debited\",\n \"payload\": {\n \"store_credit\": {\n \"customer_name\": \"MI\",\n \"customer_email\": \"mi@gmail.com\",\n \"customer_id\": \"customer_e09d0e65c9612b26c7\",\n \"card_number\": \"HNV1NK-MFZF\",\n \"balance\": \"10.00\",\n \"card_id\": \"card_a0d21058dc4ca25fd2\",\n \"last_transaction\": \"REDEMPTION\",\n \"created_at\": \"2021-12-24T06:40:28.000Z\",\n \"transaction\": {\n \"transaction_id\": \"transaction_92d72f3ca51a2917e1\",\n \"transaction_amount\": \"10.0\",\n \"transaction_type\": \"REDEMPTION\",\n \"transaction_date\": \"2021-12-24T06:44:23.000Z\",\n \"client_order_id\": null,\n \"note\": null\n }\n }\n }\n}\n\nloyalty_point.created
{\n \"event\": \"loyalty_point.created\",\n \"payload\": {\n \"loyalty_card\": {\n \"customer_name\": \"\",\n \"customer_email\": \"mi@gmail.com\",\n \"customer_id\": \"customer_e09d0e65c9612b26c7\",\n \"card_number\": \"DBZ6E-ILDSE-MYVQY-M\",\n \"currency\": \"$\",\n \"balance\": 0,\n \"card_id\": \"card_7d1333f1c87b01e84c\",\n \"last_transaction\": \"CREATION\",\n \"created_at\": \"2021-12-24T09:51:00.000Z\",\n \"transaction\": {\n \"transaction_id\": \"transaction_cb7619a9fa27f0e7aa\",\n \"transaction_amount\": \"0.0\",\n \"transaction_type\": \"CREATION\",\n \"transaction_date\": \"2021-12-24T09:51:01.000Z\",\n \"client_order_id\": null,\n \"note\": null\n }\n }\n }\n}\n\nloyalty_point.credited
{\n \"event\": \"loyalty_point.credited\",\n \"payload\": {\n \"loyalty_card\": {\n \"customer_name\": \"MI\",\n \"customer_email\": \"mi@gmail.com\",\n \"customer_id\": \"customer_e09d0e65c9612b26c7\",\n \"card_number\": \"DBZ6E-ILDSE-MYVQY-M\",\n \"currency\": \"$\",\n \"balance\": \"20.0\",\n \"card_id\": \"card_7d1333f1c87b01e84c\",\n \"last_transaction\": \"RELOAD\",\n \"created_at\": \"2021-12-24T06:14:13.000Z\",\n \"transaction\": {\n \"transaction_id\": \"transaction_25d36ee10b6e45befe\",\n \"transaction_amount\": \"20.0\",\n \"transaction_type\": \"RELOAD\",\n \"transaction_date\": \"2021-12-24T06:14:18.000Z\",\n \"client_order_id\": null,\n \"note\": null\n }\n }\n }\n}\n\nloyalty_point.debited
{\n \"event\": \"loyalty_point.debited\",\n \"payload\": {\n \"loyalty_card\": {\n \"customer_name\": \"MI\",\n \"customer_email\": \"mi@gmail.com\",\n \"customer_id\": \"customer_e09d0e65c9612b26c7\",\n \"card_number\": \"DBZ6E-ILDSE-MYVQY-M\",\n \"currency\": \"$\",\n \"balance\": \"10.0\",\n \"card_id\": \"card_7d1333f1c87b01e84c\",\n \"last_transaction\": \"REDEMPTION\",\n \"created_at\": \"2021-12-24T06:14:13.000Z\",\n \"transaction\": {\n \"transaction_id\": \"transaction_6f333f6dd3700c09e6\",\n \"transaction_amount\": \"10.0\",\n \"transaction_type\": \"REDEMPTION\",\n \"transaction_date\": \"2021-12-24T06:22:25.000Z\",\n \"client_order_id\": null,\n \"note\": null\n }\n }\n }\n}\n\ncoupon.created
{\n \"event\": \"coupon.created\",\n \"payload\": {\n \"coupon\":{\n \"code\":\"HB42VQLEBQ\",\n \"coupon_id\":\"coupon_afb9ebaaf7c4a0dff8\",\n \"active\":true,\n \"batch_id\":\"batch_5aa0553d3d789851c6\",\n \"redemption_count\":0,\n \"expiration_date\":nil,\n \"created_at\":Thu, 23 Sep 2021 09:06:17.000000000 UTC +00:00\n },\n \"customer\":{\n \"name\":\"John\", \n \"email\":\"test@doboz.in\", \n \"customer_id\":\"user_2213f13d718a06f2b5\"\n },\n \"transaction\":{\n \"reference_no\":\"coupon_transaction_8da87703285633ba10\", \n \"transaction_source\":nil, \n \"client_order_id\":nil, \n \"transaction_type\":\"CREATED\"\n },\n \"coupon_rule\":{\n \"title\":\"Coupon1\",\n \"coupon_rule_id\":nil,\n \"coupon_type\":\"FIXED\",\n \"value\":40,\n \"active\":true,\n \"coupon_length\":10,\n \"disallowed_characters\":nil,\n \"prefix\":nil,\n \"suffix\":nil,\n \"end_date\":\"2022-01-22T00:00:00.000Z\",\n \"start_date\":\"2021-09-23T18:30:00.000Z\",\n \"coupon_expiration_period\":nil,\n \"product_ids\":nil,\n \"category_ids\":nil,\n \"min_subtotal\":nil,\n \"min_quantity\":nil,\n \"max_usage\":10,\n \"max_usage_per_customer\":10,\n \"created_at\":Thu, 23 Sep 2021 09:06:17.000000000 UTC +00:00,\n \"excluded_product_ids\":nil,\n \"individual_use\":0,\n \"limit_usage_to_per_item\":nil,\n \"excluded_product_categories\":nil,\n \"exclude_sale_items\":0,\n \"max_subtotal\":0\n }\n }\n}\n\ncoupon.updated
{\n \"event\": \"coupon.updated\",\n \"payload\": {\n \"coupon\":{\n \"code\":\"HB42VQLEBQ\",\n \"coupon_id\":\"coupon_afb9ebaaf7c4a0dff8\",\n \"active\":true,\n \"batch_id\":\"batch_5aa0553d3d789851c6\",\n \"redemption_count\":0,\n \"expiration_date\":nil,\n \"created_at\":Thu, 23 Sep 2021 09:06:17.000000000 UTC +00:00\n },\n \"customer\":{\n \"name\":\"John\", \n \"email\":\"test@doboz.in\", \n \"customer_id\":\"user_2213f13d718a06f2b5\"\n },\n \"transaction\":{\n \"reference_no\":\"coupon_transaction_8da87703285633ba10\", \n \"transaction_source\":nil, \n \"client_order_id\":nil, \n \"transaction_type\":\"CREATED\"\n },\n \"coupon_rule\":{\n \"title\":\"Coupon1\",\n \"coupon_rule_id\":nil,\n \"coupon_type\":\"FIXED\",\n \"value\":40,\n \"active\":true,\n \"coupon_length\":10,\n \"disallowed_characters\":nil,\n \"prefix\":nil,\n \"suffix\":nil,\n \"end_date\":\"2022-01-22T00:00:00.000Z\",\n \"start_date\":\"2021-09-23T18:30:00.000Z\",\n \"coupon_expiration_period\":nil,\n \"product_ids\":nil,\n \"category_ids\":nil,\n \"min_subtotal\":nil,\n \"min_quantity\":nil,\n \"max_usage\":10,\n \"max_usage_per_customer\":10,\n \"created_at\":Thu, 23 Sep 2021 09:06:17.000000000 UTC +00:00,\n \"excluded_product_ids\":nil,\n \"individual_use\":0,\n \"limit_usage_to_per_item\":nil,\n \"excluded_product_categories\":nil,\n \"exclude_sale_items\":0,\n \"max_subtotal\":0\n }\n }\n}\n\ncoupon.redeemed
{\n \"event\": \"coupon.redeemed\", \n \"payload\":{\n \"coupon\":{\n \"code\":\"HB42VQLEBQ\",\n \"coupon_id\":\"coupon_afb9ebaaf7c4a0dff8\",\n \"active\":true,\n \"batch_id\":\"batch_5aa0553d3d789851c6\",\n \"redemption_count\":1,\n \"expiration_date\":nil,\n \"created_at\":Thu, 23 Sep 2021 09:06:17.000000000 UTC +00:00\n },\n \"customer\":{\n \"name\":\"John\", \n \"email\":\"gaurav@doboz.in\", \n \"customer_id\":\"user_2213f13d718a06f2b5\"\n },\n \"transaction\":{\n \"reference_no\":\"coupon_transaction_f1f99c42b9c7932620\",\n \"transaction_source\":\"API\",\n \"client_order_id\":nil,\n \"transaction_type\":\"REDEEMED\"\n },\n \"coupon_rule\":{\n \"title\":\"Coupon1\",\n \"coupon_rule_id\":nil,\n \"coupon_type\":\"FIXED\",\n \"value\":40,\n \"active\":true,\n \"coupon_length\":10,\n \"disallowed_characters\":nil,\n \"prefix\":nil,\n \"suffix\":nil,\n \"end_date\":\"2022-01-22T00:00:00.000Z\",\n \"start_date\":\"2021-09-23T18:30:00.000Z\",\n \"coupon_expiration_period\":nil,\n \"product_ids\":nil,\n \"category_ids\":nil,\n \"min_subtotal\":nil,\n \"min_quantity\":nil,\n \"max_usage\":10,\n \"max_usage_per_customer\":10,\n \"created_at\":Thu, 23 Sep 2021 09:06:17.000000000 UTC +00:00,\n \"excluded_product_ids\":nil,\n \"individual_use\":0,\n \"limit_usage_to_per_item\":nil,\n \"excluded_product_categories\":nil,\n \"exclude_sale_items\":0,\n \"max_subtotal\":0\n }\n }\n}\n\nWebhooks can be verified by calculating a digital signature. Each webhook request includes a X-99minds-Signature header, which is generated using the webhook's signing secret along with the data sent in the request.
To verify that the request came from 99minds, compute the signature according to the following algorithm and compare it to the value in the X-99minds-Signature header. If they match, then you can be sure that the webhook was sent from 99minds. As a best practice, the signature should be verified before the app responds to the webhook.
HMAC digest with SHA256 algorithm.
\nUse webhook's signing secret as a key to HMAC.
\nBase64 strict encoding.
\nUse raw body as the message/data.
\nHere are few examples in various languages:
\nrequire 'rubygems'\nrequire 'base64'\nrequire 'openssl'\nrequire 'sinatra'\nrequire 'active_support/security_utils'\nSIGNING_SECRET = 'my_shared_secret'\nhelpers do\n def verify_webhook(data, hmac_header)\n digest = OpenSSL::Digest.new(\"sha256\")\n calculated_hmac = Base64.strict_encode64(OpenSSL::HMAC.digest(digest, SIGNING_SECRET, data))\n ActiveSupport::SecurityUtils.secure_compare(calculated_hmac, hmac_header)\n end\nend\npost '/' do\n data = request.body.read\n verified = verify_webhook(data, env[\"HTTP_X_99MINDS_SIGNATURE\"])\n puts \"Webhook verified: #{verified}\"\nend\n\ndefine('SIGNING_SECRET', 'my_shared_secret');\nfunction verify_webhook($data, $hmac_header)\n{\n $calculated_hmac = base64_encode(hash_hmac('sha256', $data, SIGNING_SECRET, true));\n return hash_equals($hmac_header, $calculated_hmac);\n}\n$hmac_header = $_SERVER['HTTP_X_99MINDS_SIGNATURE'];\n$data = file_get_contents('php://input');\n$verified = verify_webhook($data, $hmac_header);\nerror_log('Webhook verified: '.var_export($verified, true)); //check error.log to see the result\n?>\n\nfrom flask import Flask, request, abort\nimport hmac\nimport hashlib\nimport base64\napp = Flask(__name__)\nSIGNING_SECRET = 'hush'\ndef verify_webhook(data, hmac_header):\n digest = hmac.new(SIGNING_SECRET, data.encode('utf-8'), hashlib.sha256).digest()\n computed_hmac = base64.b64encode(digest)\n return hmac.compare_digest(computed_hmac, hmac_header.encode('utf-8'))\n@app.route('/webhook', methods=['POST'])\ndef handle_webhook():\n data = request.get_data()\n verified = verify_webhook(data, request.headers.get('X-99minds-Signature'))\n if not verified:\n abort(401)\n # process webhook payload\n # ...\n return ('Webhook verified', 200)\n\n