{"metadata":{"image":[],"title":"","description":""},"api":{"url":"","auth":"required","params":[],"results":{"codes":[]},"settings":""},"next":{"description":"","pages":[]},"title":"Accept Payments with the Merchant API","type":"basic","slug":"accepting-payments-with-the-merchant-api","excerpt":"This document explains how to accept payments using the Merchant API","body":"## Overview \n\nThe Coins Merchant API allows e-commerce merchants to accept payments for goods or services, through the integration of a payment gateway into their mobile or web application. Furthermore, it instantly settles payments to the Merchant's Coins.ph account.\n\nThrough the payment gateway, your customers are presented with a variety of options to conduct their payment to you. These payment outlet options are fully customizable to give you the capability to choose what will be enabled to your customers. For more information on the list of outlets that are available, please take a look [here](doc:getting-the-supported-payment-outlets) \n\n## A typical merchant's journey is as follows:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/0341f9b-8c79042-Capture.PNG\",\n        \"8c79042-Capture.PNG\",\n        1199,\n        599,\n        \"#3495d9\"\n      ]\n    }\n  ]\n}\n[/block]\n1. Customer confirms the checkout of his order\n2. Merchant consumes the [Invoices API](doc:invoices)\n2. Customer is redirected to the Coins.ph payment widget screen, as seen in the sample screens above.\n3. Customer selects and conducts the desired payment option. Note: Each option has their own set of instructions to assist the customer in performing the payment\n   <p> a. If he chooses to pay through his Coins.ph wallet, he will be asked to login their Coins.ph account and initiate the payment.\n   b. If he chooses to pay over-the-counter, he will be provided a barcode and a reference number that will be used by the available outlets. </p>\n4. After the customer has fully paid the particular invoice, he is redirected back to the merchant’s application via the [redirect URL](doc:merchant-getting-started) \n5. Merchant will receive a notification upon confirmation of payment via a secure [callback](doc:merchant-getting-started)\n\n## Building with the Merchant API\n[block:callout]\n{\n  \"type\": \"info\",\n  \"body\": \"Before starting to integrate with the payment gateway, you may want to follow the instructions for [setting up your merchant account](doc:merchant-getting-started) and retrieving your `merchant_api_token` first\"\n}\n[/block]\nFollowing the server-side integration flow will allow you to specify invoice details on the checkout page, as well as receive notifications via a callback when the payment has been successfully completed.\n\n# 1. Creating an invoice:\n\nThe following example should allow you to create a new [invoice](doc:invoices). When creating an invoice, you may specify amount, currency, and description. \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -H 'Authorization: Token YOUR_MERCHANT_API_TOKEN' \\\\\\n     -H 'Content-Type: application/json' \\\\\\n     -d '{\\\"amount\\\": 5, \\\"currency\\\": \\\"PHP\\\", \\\"external_transaction_id\\\": \\\"YOUR_TRANSACTION_ID\\\"}' \\\\\\n     -X POST \\\\\\n     https://api.coins.asia/v1/invoices/\",\n      \"language\": \"curl\"\n    },\n    {\n      \"code\": \"import json\\nimport requests\\n\\nurl = \\\"https://api.coins.asia/v3/invoices/\\\"\\n\\nTOKEN = 'YOUR TOKEN'\\nheaders = {\\n    'Authorization': 'Bearer {}'.format(TOKEN),\\n    'Content-Type': 'application/json;charset=UTF-8',\\n    'Accept': 'application/json'\\n}\\nbody = json.dumps({\\n     \\\"amount\\\": 120,\\n  \\t \\\"currency\\\": \\\"PHP\\\",\\n  \\t \\\"external_transaction_id\\\": \\\"89723952\\\"\\n})\\n\\nrequests.post(url, headers=headers, data=body)\\nprint(response.text)\",\n      \"language\": \"python\"\n    },\n    {\n      \"code\": \"require 'uri'\\nrequire 'json'\\nrequire 'net/http'\\n\\nurl = URI('https://collector.coins.ph/v1/invoices')\\n\\nhttp = Net::HTTP.new(url.host, url.port)\\nhttp.use_ssl = true\\n\\nrequest = Net::HTTP::Post.new(url.request_uri)\\nrequest[\\\"content-type\\\"] = 'application/json'\\nrequest[\\\"authorization\\\"] = 'Token YOUR_MERCHANT_API_TOKEN'\\nrequest.body = JSON.dump({\\n    amount: 5,\\n    currency: 'PHP',\\n    external_transaction_id: 'YOUR_TRANSACTION_ID'\\n})\\n\\nresponse = http.request(request)\\nputs response.read_body\",\n      \"language\": \"ruby\"\n    }\n  ]\n}\n[/block]\nHere is a sample response (some fields removed for brevity).\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"invoice\\\": {\\n    \\\"id\\\": \\\"voro5v750qyig7dayil9wkteokfc90kg\\\",\\n    \\\"status\\\": \\\"pending\\\",\\n    \\\"category\\\": \\\"merchant\\\",\\n    \\\"amount\\\": \\\"120.00000000\\\",\\n    \\\"currency\\\": \\\"PHP\\\",\\n    \\\"external_transaction_id\\\": \\\"89723969\\\",\\n    \\\"payment_url\\\": \\\"https://coins.ph/payment/invoice/voro5v750...\\\",\\n    \\\"supported_payment_collectors\\\": [\\\"cash_payment\\\"],\\n  }\\n}\\n\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n# 2. Redirecting to the payment gateway\n\nOnce you receive the response from our Invoice API, redirect your customer to the gateway using the information from the `payment_url` field as shown above.\n\nThis presents the customers with a summary of the invoice details, as well as the options on which he can complete his payment with (similar to the first image of the merchant's journey above). These options are specified with the help of  the `supported_payment_collectors` field. After the customer completes the payment flow, they will be redirected back to the URL that has been set in your merchant settings, and a callback will be made to your provided callback URL once payment has been confirmed.\n\n# 3. Receiving Payment Notifications\n\nOnce payment has been confirmed from the customer, a POST request is sent to the `callback_url` to inform you that payment has been completed. \n\nIf your `callback_url` uses SSL, we will include in the request's authorization header your merchant API token `Authorization: Token YOUR_MERCHANT_API_TOKEN` so that you can validate the callback. Otherwise, we recommend that you [retrieve the invoice](doc:invoices) through a GET request through API call instead.\n\nThe example below illustrates handling of the callback on the merchant's side:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"import json\\nfrom django.http import HttpResponse\\n\\nMERCHANT_API_TOKEN = 'YOUR_MERCHANT_API_TOKEN'\\n\\n# Using Django\\ndef my_callback_view(request):\\n    # Verify callback\\n    authorization_header = request.META.get('Authorization')\\n    auth_parts = authorization_header.split(' ')\\n    if (len(auth_parts) != 2 or auth_parts[1] != MERCHANT_API_TOKEN) :\\n        return HttpResponse(status=401)\\n  \\n    # Retrieve the request's body and parse it as JSON\\n    event_json = json.loads(request.body)\\n    message = 'Event {} for \\\"{}\\\" was received'.format(\\n        event['name'],\\n        event['data'].get('id', 'Unspecified')\\n    )\\n    \\n    print message\\n\\n    return HttpResponse(status=200)\",\n      \"language\": \"python\"\n    },\n    {\n      \"code\": \"MERCHANT_API_TOKEN = 'YOUR_MERCHANT_API_TOKEN'\\n\\nrequire 'json'\\n\\n# Using Sinatra\\npost \\\"/my/webhook/url\\\" do\\n  # Verify webhook\\n  authorization_header = request.headers['Authorization']\\n  _, api_key = authorization_header.split(' ')\\n  \\n  if api_key != MERCHANT_API_TOKEN:\\n    status 401\\n  \\n  # Retrieve the request's body and parse it as JSON\\n  event_json = JSON.parse(request.body.read)\\n\\n  puts \\\"Event #{event_json[\\\"event\\\"][\\\"name\\\"]} was received\\\"\\n\\n  status 200\\nend\",\n      \"language\": \"ruby\"\n    }\n  ]\n}\n[/block]\nHere is an example payload for a confirmed payment event:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"event\\\": {\\n    \\\"name\\\": \\\"invoice.fully_paid\\\",\\n    \\\"data\\\": {\\n      \\\"id\\\": \\\"13g32b103\\\",\\n      \\\"currency\\\": \\\"PHP\\\",\\n      \\\"amount\\\": \\\"5.00000000\\\",\\n      \\\"amount_received\\\": \\\"0.00000000\\\",\\n      \\\"external_transaction_id\\\": \\\"YOUR_TRANSACTION_ID\\\"\\n    }\\n  }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nIn addition to payment completion, there are several other invoice events that will trigger a callback and can be handled in a similar fashion. For more information, please have a look at our [Payment Callbacks](doc:invoice-callbacks)  document.","updates":["5a280814eaec590012c5516e","5a7dc7c66668630083becd38","5a7dcabcfcf323001227ba39","5c509e54ae4abe001ae650c5"],"order":1,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"_id":"563750380704070d00f06c4b","category":{"sync":{"isSync":false,"url":""},"pages":["56326e9edf556c0d00cd08da","56326e9edf556c0d00cd08db","56326e9edf556c0d00cd08dc","56326e9edf556c0d00cd08dd","56326e9edf556c0d00cd08de","56326e9edf556c0d00cd08df","5632e61862c48a0d00334ddc","5637210ec75f5d0d00ec5d4a","563750380704070d00f06c4b","56ecf98c7f94882900591955"],"title":"Tutorials","slug":"tutorials","order":2,"from_sync":false,"reference":false,"_id":"56326e9ddf556c0d00cd08cd","version":"56326e9cdf556c0d00cd08ca","__v":5,"createdAt":"2015-05-01T09:13:02.297Z","project":"544fc17e698ab40800b4f891"},"githubsync":"","version":{"version":"2.1","version_clean":"2.1.0","codename":"collector","is_stable":true,"is_beta":false,"is_hidden":false,"is_deprecated":false,"categories":["56326e9ddf556c0d00cd08cb","56326e9ddf556c0d00cd08cc","56326e9ddf556c0d00cd08cd","56326e9ddf556c0d00cd08ce","56326e9ddf556c0d00cd08cf","56326e9ddf556c0d00cd08d0","56326e9ddf556c0d00cd08d1","56326e9ddf556c0d00cd08d2","56326e9ddf556c0d00cd08d3","56326e9ddf556c0d00cd08d4","56d942ac337fd11300d6a251","5ab2fcf66a1d77001230b47e","5afc2943bd2ef4000330bca7","5d1d87419a969a00141c6b4c","5d1d8948ef26b2002c6468d1","5d1d8afe7b2b24005bec7de0","5d1d8b24f5cfcb00201490bb","5d1d8bb82d46d1004a02581f","5d1d8de1e4edb0019ed63acd","5d1d8f6b613fb90050d0d3e0","5d1d934ed377870191039d28","5d1d99810b2e4600500eb5ff","5d1da14e613fb90050d0d491","5d229a846cf323005a7fa998","5d229a8c8abf65001cc4768d","5d229a9494b856002e26b6e1","5d229a9bf77bb900507ccb04","5d229aa88abf65001cc4768e","5d24310a9ca8c80054786177","5d24359101cc3a00508e7482","5d24418fa791b20050733b32"],"_id":"56326e9cdf556c0d00cd08ca","project":"544fc17e698ab40800b4f891","releaseDate":"2015-10-29T19:08:12.724Z","__v":22,"createdAt":"2015-10-29T19:08:12.724Z"},"parentDoc":null,"project":"544fc17e698ab40800b4f891","user":"544fc065698ab40800b4f888","__v":169,"createdAt":"2015-11-02T11:59:52.810Z","updatedAt":"2019-07-04T07:56:23.199Z"}

Accept Payments with the Merchant API

This document explains how to accept payments using the Merchant API

## Overview The Coins Merchant API allows e-commerce merchants to accept payments for goods or services, through the integration of a payment gateway into their mobile or web application. Furthermore, it instantly settles payments to the Merchant's Coins.ph account. Through the payment gateway, your customers are presented with a variety of options to conduct their payment to you. These payment outlet options are fully customizable to give you the capability to choose what will be enabled to your customers. For more information on the list of outlets that are available, please take a look [here](doc:getting-the-supported-payment-outlets) ## A typical merchant's journey is as follows: [block:image] { "images": [ { "image": [ "https://files.readme.io/0341f9b-8c79042-Capture.PNG", "8c79042-Capture.PNG", 1199, 599, "#3495d9" ] } ] } [/block] 1. Customer confirms the checkout of his order 2. Merchant consumes the [Invoices API](doc:invoices) 2. Customer is redirected to the Coins.ph payment widget screen, as seen in the sample screens above. 3. Customer selects and conducts the desired payment option. Note: Each option has their own set of instructions to assist the customer in performing the payment <p> a. If he chooses to pay through his Coins.ph wallet, he will be asked to login their Coins.ph account and initiate the payment. b. If he chooses to pay over-the-counter, he will be provided a barcode and a reference number that will be used by the available outlets. </p> 4. After the customer has fully paid the particular invoice, he is redirected back to the merchant’s application via the [redirect URL](doc:merchant-getting-started) 5. Merchant will receive a notification upon confirmation of payment via a secure [callback](doc:merchant-getting-started) ## Building with the Merchant API [block:callout] { "type": "info", "body": "Before starting to integrate with the payment gateway, you may want to follow the instructions for [setting up your merchant account](doc:merchant-getting-started) and retrieving your `merchant_api_token` first" } [/block] Following the server-side integration flow will allow you to specify invoice details on the checkout page, as well as receive notifications via a callback when the payment has been successfully completed. # 1. Creating an invoice: The following example should allow you to create a new [invoice](doc:invoices). When creating an invoice, you may specify amount, currency, and description. [block:code] { "codes": [ { "code": "curl -H 'Authorization: Token YOUR_MERCHANT_API_TOKEN' \\\n -H 'Content-Type: application/json' \\\n -d '{\"amount\": 5, \"currency\": \"PHP\", \"external_transaction_id\": \"YOUR_TRANSACTION_ID\"}' \\\n -X POST \\\n https://api.coins.asia/v1/invoices/", "language": "curl" }, { "code": "import json\nimport requests\n\nurl = \"https://api.coins.asia/v3/invoices/\"\n\nTOKEN = 'YOUR TOKEN'\nheaders = {\n 'Authorization': 'Bearer {}'.format(TOKEN),\n 'Content-Type': 'application/json;charset=UTF-8',\n 'Accept': 'application/json'\n}\nbody = json.dumps({\n \"amount\": 120,\n \t \"currency\": \"PHP\",\n \t \"external_transaction_id\": \"89723952\"\n})\n\nrequests.post(url, headers=headers, data=body)\nprint(response.text)", "language": "python" }, { "code": "require 'uri'\nrequire 'json'\nrequire 'net/http'\n\nurl = URI('https://collector.coins.ph/v1/invoices')\n\nhttp = Net::HTTP.new(url.host, url.port)\nhttp.use_ssl = true\n\nrequest = Net::HTTP::Post.new(url.request_uri)\nrequest[\"content-type\"] = 'application/json'\nrequest[\"authorization\"] = 'Token YOUR_MERCHANT_API_TOKEN'\nrequest.body = JSON.dump({\n amount: 5,\n currency: 'PHP',\n external_transaction_id: 'YOUR_TRANSACTION_ID'\n})\n\nresponse = http.request(request)\nputs response.read_body", "language": "ruby" } ] } [/block] Here is a sample response (some fields removed for brevity). [block:code] { "codes": [ { "code": "{\n \"invoice\": {\n \"id\": \"voro5v750qyig7dayil9wkteokfc90kg\",\n \"status\": \"pending\",\n \"category\": \"merchant\",\n \"amount\": \"120.00000000\",\n \"currency\": \"PHP\",\n \"external_transaction_id\": \"89723969\",\n \"payment_url\": \"https://coins.ph/payment/invoice/voro5v750...\",\n \"supported_payment_collectors\": [\"cash_payment\"],\n }\n}\n", "language": "json" } ] } [/block] # 2. Redirecting to the payment gateway Once you receive the response from our Invoice API, redirect your customer to the gateway using the information from the `payment_url` field as shown above. This presents the customers with a summary of the invoice details, as well as the options on which he can complete his payment with (similar to the first image of the merchant's journey above). These options are specified with the help of the `supported_payment_collectors` field. After the customer completes the payment flow, they will be redirected back to the URL that has been set in your merchant settings, and a callback will be made to your provided callback URL once payment has been confirmed. # 3. Receiving Payment Notifications Once payment has been confirmed from the customer, a POST request is sent to the `callback_url` to inform you that payment has been completed. If your `callback_url` uses SSL, we will include in the request's authorization header your merchant API token `Authorization: Token YOUR_MERCHANT_API_TOKEN` so that you can validate the callback. Otherwise, we recommend that you [retrieve the invoice](doc:invoices) through a GET request through API call instead. The example below illustrates handling of the callback on the merchant's side: [block:code] { "codes": [ { "code": "import json\nfrom django.http import HttpResponse\n\nMERCHANT_API_TOKEN = 'YOUR_MERCHANT_API_TOKEN'\n\n# Using Django\ndef my_callback_view(request):\n # Verify callback\n authorization_header = request.META.get('Authorization')\n auth_parts = authorization_header.split(' ')\n if (len(auth_parts) != 2 or auth_parts[1] != MERCHANT_API_TOKEN) :\n return HttpResponse(status=401)\n \n # Retrieve the request's body and parse it as JSON\n event_json = json.loads(request.body)\n message = 'Event {} for \"{}\" was received'.format(\n event['name'],\n event['data'].get('id', 'Unspecified')\n )\n \n print message\n\n return HttpResponse(status=200)", "language": "python" }, { "code": "MERCHANT_API_TOKEN = 'YOUR_MERCHANT_API_TOKEN'\n\nrequire 'json'\n\n# Using Sinatra\npost \"/my/webhook/url\" do\n # Verify webhook\n authorization_header = request.headers['Authorization']\n _, api_key = authorization_header.split(' ')\n \n if api_key != MERCHANT_API_TOKEN:\n status 401\n \n # Retrieve the request's body and parse it as JSON\n event_json = JSON.parse(request.body.read)\n\n puts \"Event #{event_json[\"event\"][\"name\"]} was received\"\n\n status 200\nend", "language": "ruby" } ] } [/block] Here is an example payload for a confirmed payment event: [block:code] { "codes": [ { "code": "{\n \"event\": {\n \"name\": \"invoice.fully_paid\",\n \"data\": {\n \"id\": \"13g32b103\",\n \"currency\": \"PHP\",\n \"amount\": \"5.00000000\",\n \"amount_received\": \"0.00000000\",\n \"external_transaction_id\": \"YOUR_TRANSACTION_ID\"\n }\n }\n}", "language": "json" } ] } [/block] In addition to payment completion, there are several other invoice events that will trigger a callback and can be handled in a similar fashion. For more information, please have a look at our [Payment Callbacks](doc:invoice-callbacks) document.