{"_id":"563746db4dbdd919001b26d7","parentDoc":null,"user":"544fc065698ab40800b4f888","category":{"_id":"56326e9ddf556c0d00cd08d4","pages":["56326ea0df556c0d00cd08ee","5633004538f8aa0d00d30ff8","5633005a62c48a0d00334def","563746db4dbdd919001b26d7","564038826d1ccf0d006ed778","5640470bd4b2e00d00bb3c22"],"version":"56326e9cdf556c0d00cd08ca","__v":6,"project":"544fc17e698ab40800b4f891","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-05-12T04:49:53.071Z","from_sync":false,"order":10,"slug":"merchants","title":"Merchants"},"version":{"_id":"56326e9cdf556c0d00cd08ca","project":"544fc17e698ab40800b4f891","__v":2,"createdAt":"2015-10-29T19:08:12.724Z","releaseDate":"2015-10-29T19:08:12.724Z","categories":["56326e9ddf556c0d00cd08cb","56326e9ddf556c0d00cd08cc","56326e9ddf556c0d00cd08cd","56326e9ddf556c0d00cd08ce","56326e9ddf556c0d00cd08cf","56326e9ddf556c0d00cd08d0","56326e9ddf556c0d00cd08d1","56326e9ddf556c0d00cd08d2","56326e9ddf556c0d00cd08d3","56326e9ddf556c0d00cd08d4","56d942ac337fd11300d6a251"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"collector","version_clean":"2.1.0","version":"2.1"},"__v":7,"project":"544fc17e698ab40800b4f891","updates":["593b837b67293f001940819a"],"next":{"pages":[],"description":""},"createdAt":"2015-11-02T11:19:55.084Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":3,"body":"Certain events may happen during a lifespan of an invoice. For example, when an invoice gets fully paid, an event `invoice.fully_paid` is triggered. Merchants may choose to consume these events by providing a [callback_url](doc:merchant-getting-started), so that they can act on the events if needed.\n\nEvents are delivered to callbacks via a POST request, with the authorization header of `Authorization: Token MERCHANT_API_TOKEN`\n\nEvent payloads follow this convention:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"event\\\": {\\n    \\\"name\\\": \\\"invoice.name\\\",\\n    \\\"data\\\": {\\n  \\t\\t\\\"id\\\": \\\"invoice_id\\\",\\n  \\t\\t\\\"currency\\\": \\\"PHP\\\",\\n  \\t\\t\\\"amount\\\": \\\"100\\\",\\n  \\t\\t\\\"amount_received\\\": \\\"0\\\",\\n  \\t\\t\\\"external_transaction_id\\\": \\\"1\\\"\\n\\t\\t}\\n\\t}\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nEvents which may be consumed by callbacks are described at the following table:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Event Name\",\n    \"h-1\": \"Description\",\n    \"h-2\": \"Fired By\",\n    \"0-0\": \"`invoice.created`\",\n    \"1-0\": \"`invoice.updated`\",\n    \"2-0\": \"`invoice.fully_paid`\",\n    \"0-1\": \"The invoice has been created.\",\n    \"1-1\": \"The invoice has been updated. This can happen due to the invoice receiving payment or due to expiration of guaranteed rate for Bitcoin payments.\",\n    \"2-1\": \"The invoice is has been complete.\"\n  },\n  \"cols\": 2,\n  \"rows\": 3\n}\n[/block]\n## Example Callback URL Implementation in Flask\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"# https://example.com/callbacks/invoice\\n:::at:::app.route('/callbacks/invoice', methods=['POST'])\\ndef invoice_callback():\\n    body = request.get_json()\\n    event = data['event']\\n    event_name = event['name']\\n    data = event['data']\\n    \\n    # Do something based on the event name\\n    if event_name == 'invoice.fully_paid':\\n        # Process paid transaction\\n    elif event_name == 'invoice.created':\\n        # Update invoice status\\n    elif event_name == 'invoice.updated':\\n        # Update invoice status\\n\\n    return 'OK'\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]","excerpt":"Describes callbacks from invoice events","slug":"invoice-callbacks","type":"basic","title":"Invoice Callbacks"}

Invoice Callbacks

Describes callbacks from invoice events

Certain events may happen during a lifespan of an invoice. For example, when an invoice gets fully paid, an event `invoice.fully_paid` is triggered. Merchants may choose to consume these events by providing a [callback_url](doc:merchant-getting-started), so that they can act on the events if needed. Events are delivered to callbacks via a POST request, with the authorization header of `Authorization: Token MERCHANT_API_TOKEN` Event payloads follow this convention: [block:code] { "codes": [ { "code": "{\n \"event\": {\n \"name\": \"invoice.name\",\n \"data\": {\n \t\t\"id\": \"invoice_id\",\n \t\t\"currency\": \"PHP\",\n \t\t\"amount\": \"100\",\n \t\t\"amount_received\": \"0\",\n \t\t\"external_transaction_id\": \"1\"\n\t\t}\n\t}\n}", "language": "json" } ] } [/block] Events which may be consumed by callbacks are described at the following table: [block:parameters] { "data": { "h-0": "Event Name", "h-1": "Description", "h-2": "Fired By", "0-0": "`invoice.created`", "1-0": "`invoice.updated`", "2-0": "`invoice.fully_paid`", "0-1": "The invoice has been created.", "1-1": "The invoice has been updated. This can happen due to the invoice receiving payment or due to expiration of guaranteed rate for Bitcoin payments.", "2-1": "The invoice is has been complete." }, "cols": 2, "rows": 3 } [/block] ## Example Callback URL Implementation in Flask [block:code] { "codes": [ { "code": "# https://example.com/callbacks/invoice\n@app.route('/callbacks/invoice', methods=['POST'])\ndef invoice_callback():\n body = request.get_json()\n event = data['event']\n event_name = event['name']\n data = event['data']\n \n # Do something based on the event name\n if event_name == 'invoice.fully_paid':\n # Process paid transaction\n elif event_name == 'invoice.created':\n # Update invoice status\n elif event_name == 'invoice.updated':\n # Update invoice status\n\n return 'OK'", "language": "python" } ] } [/block]