{"_id":"5779ea9699b40b0e005abb63","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"},"parentDoc":null,"__v":17,"category":{"_id":"56d942ac337fd11300d6a251","__v":2,"pages":["56d942c607ae190b000044af","56d942da6fcdd00b0002cad4"],"project":"544fc17e698ab40800b4f891","version":"56326e9cdf556c0d00cd08ca","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-03-04T08:09:16.560Z","from_sync":false,"order":7,"slug":"payment-requests","title":"Payment Requests"},"project":"544fc17e698ab40800b4f891","user":"544fc065698ab40800b4f888","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-07-04T04:48:22.304Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"Payment requests use invoices to track whether the request is already paid or not. These invoices emit events that may be useful to update the status of an item attached to a payment request. Once the customer sends payment for the payment request, an event will be triggered to the merchant's specified callback URL. The merchant's system can then react accordingly based on the triggered event.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"How Payment Requests use Invoices\"\n}\n[/block]\nA particular payment request is related to an invoice as denoted by `invoice` in the payment request's properties. For example, here's a response payload after creating a payment request:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n    \\\"payment-request\\\": {\\n        \\\"id\\\": \\\"5edc263fac7f4f61b87632cb5710050f\\\",\\n        \\\"invoice\\\": \\\"5713e3ab76e74e6b85194deaf0f14cel\\\",\\n        \\\"payer_contact_info\\\": \\\"example:::at:::example.com\\\",\\n        \\\"payer_contact_info_type\\\": \\\"email\\\",\\n        \\\"payer_email\\\": \\\"example@example.com\\\",\\n        \\\"amount\\\": \\\"20.00000000\\\",\\n        \\\"currency\\\": \\\"PHP\\\",\\n        \\\"message\\\": \\\"Thanks for all the fish!\\\",\\n        \\\"message_scope\\\": \\\"private\\\",\\n        \\\"status\\\": \\\"pending\\\",\\n        \\\"receiving_account\\\": \\\"5411c4604c9b45b8b74837c84daa0f4c\\\",\\n        \\\"payment_url\\\": \\\"https://coins.ph/payment/request/5edc263fac7f4f61b87632cb5710050f\\\",\\n        \\\"created_at\\\": \\\"2016-03-04T07:12:00.352338Z\\\",\\n        \\\"updated_at\\\": \\\"2016-03-04T07:12:00.474500Z\\\",\\n        \\\"expires_at\\\":\\\"2017-03-04T07:11:59.942484Z\\\"\\n    }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nThis payment request uses the invoice `5713e3ab76e74e6b85194deaf0f14cel` to track payment events. This means that when you receive an event callback, you should be checking for the `invoice` id instead of the payment request id in the request payload that will be sent to your endpoint.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Defining a callback URL\"\n}\n[/block]\nA callback URL is an endpoint that accepts a POST request with `Content-Type: application/json`. Here's an example of a callback URL:\n\n[block:api-header]\n{\n  \"type\": \"post\",\n  \"title\": \"https://example.com/api/payment-request/callback\"\n}\n[/block]\nMerchants are free to decide how they would name or nest their callback URL. To assign a designated URL to your application, please see the [Merchant Getting Started Guide](doc:merchant-getting-started). A payload delivered to this URL follows 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]\n## Payload Description\n\n* `name`: The name of the invoice event that occurred. Events are further described in the table that follows after this section.\n* `data`: Contains properties that are specific to the particular event that triggered.\n* `id`: Unique invoice identifier. This is the `invoice` related to the payment request.\n* `currency`: The currency of the `amount`.\n* `amount`: The amount of the transaction.\n* `amount_received`: The amount already received as payment for the transaction.\n* `external_transaction_id`: An identifier provided by the merchant during the creation of the transaction. This identifier usually represents an item in the merchant's system.\n\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\": \"Event Description\",\n    \"0-1\": \"The invoice has been created.\",\n    \"0-0\": \"`invoice.created`\",\n    \"1-0\": \"`invoice.updated`\",\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    \"2-0\": \"`invoice.fully_paid`\"\n  },\n  \"cols\": 2,\n  \"rows\": 3\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Authorization\"\n}\n[/block]\nCallbacks strictly require an HTTPS endpoint with a valid SSL certificate. This simplifies the authentication mechanism used by the callback, which is a shared secret contained in the request header sent to your endpoint: `Authorization: Token MERCHANT_API_TOKEN`. You should check if the `MERCHANT_API_TOKEN` is the same as the one defined in your dashboard. If it differs, it means that the request is not from an authorized source. This also means that you should not share your `MERCHANT_API_TOKEN` to prevent unauthorized sources from sending fake callback events.","excerpt":"Describes callbacks from payment request events","slug":"payment-request-callbacks","type":"basic","title":"Payment Request Callbacks"}

Payment Request Callbacks

Describes callbacks from payment request events

Payment requests use invoices to track whether the request is already paid or not. These invoices emit events that may be useful to update the status of an item attached to a payment request. Once the customer sends payment for the payment request, an event will be triggered to the merchant's specified callback URL. The merchant's system can then react accordingly based on the triggered event. [block:api-header] { "type": "basic", "title": "How Payment Requests use Invoices" } [/block] A particular payment request is related to an invoice as denoted by `invoice` in the payment request's properties. For example, here's a response payload after creating a payment request: [block:code] { "codes": [ { "code": "{\n \"payment-request\": {\n \"id\": \"5edc263fac7f4f61b87632cb5710050f\",\n \"invoice\": \"5713e3ab76e74e6b85194deaf0f14cel\",\n \"payer_contact_info\": \"example@example.com\",\n \"payer_contact_info_type\": \"email\",\n \"payer_email\": \"example@example.com\",\n \"amount\": \"20.00000000\",\n \"currency\": \"PHP\",\n \"message\": \"Thanks for all the fish!\",\n \"message_scope\": \"private\",\n \"status\": \"pending\",\n \"receiving_account\": \"5411c4604c9b45b8b74837c84daa0f4c\",\n \"payment_url\": \"https://coins.ph/payment/request/5edc263fac7f4f61b87632cb5710050f\",\n \"created_at\": \"2016-03-04T07:12:00.352338Z\",\n \"updated_at\": \"2016-03-04T07:12:00.474500Z\",\n \"expires_at\":\"2017-03-04T07:11:59.942484Z\"\n }\n}", "language": "json" } ] } [/block] This payment request uses the invoice `5713e3ab76e74e6b85194deaf0f14cel` to track payment events. This means that when you receive an event callback, you should be checking for the `invoice` id instead of the payment request id in the request payload that will be sent to your endpoint. [block:api-header] { "type": "basic", "title": "Defining a callback URL" } [/block] A callback URL is an endpoint that accepts a POST request with `Content-Type: application/json`. Here's an example of a callback URL: [block:api-header] { "type": "post", "title": "https://example.com/api/payment-request/callback" } [/block] Merchants are free to decide how they would name or nest their callback URL. To assign a designated URL to your application, please see the [Merchant Getting Started Guide](doc:merchant-getting-started). A payload delivered to this URL follows 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] ## Payload Description * `name`: The name of the invoice event that occurred. Events are further described in the table that follows after this section. * `data`: Contains properties that are specific to the particular event that triggered. * `id`: Unique invoice identifier. This is the `invoice` related to the payment request. * `currency`: The currency of the `amount`. * `amount`: The amount of the transaction. * `amount_received`: The amount already received as payment for the transaction. * `external_transaction_id`: An identifier provided by the merchant during the creation of the transaction. This identifier usually represents an item in the merchant's system. Events which may be consumed by callbacks are described at the following table: [block:parameters] { "data": { "h-0": "Event Name", "h-1": "Event Description", "0-1": "The invoice has been created.", "0-0": "`invoice.created`", "1-0": "`invoice.updated`", "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.", "2-0": "`invoice.fully_paid`" }, "cols": 2, "rows": 3 } [/block] [block:api-header] { "type": "basic", "title": "Authorization" } [/block] Callbacks strictly require an HTTPS endpoint with a valid SSL certificate. This simplifies the authentication mechanism used by the callback, which is a shared secret contained in the request header sent to your endpoint: `Authorization: Token MERCHANT_API_TOKEN`. You should check if the `MERCHANT_API_TOKEN` is the same as the one defined in your dashboard. If it differs, it means that the request is not from an authorized source. This also means that you should not share your `MERCHANT_API_TOKEN` to prevent unauthorized sources from sending fake callback events.