{"_id":"563750380704070d00f06c4b","category":{"_id":"56326e9ddf556c0d00cd08cd","pages":["56326e9edf556c0d00cd08da","56326e9edf556c0d00cd08db","56326e9edf556c0d00cd08dc","56326e9edf556c0d00cd08dd","56326e9edf556c0d00cd08de","56326e9edf556c0d00cd08df","5632e61862c48a0d00334ddc","5637210ec75f5d0d00ec5d4a","563750380704070d00f06c4b","56ecf98c7f94882900591955"],"version":"56326e9cdf556c0d00cd08ca","__v":5,"project":"544fc17e698ab40800b4f891","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-05-01T09:13:02.297Z","from_sync":false,"order":2,"slug":"tutorials","title":"Tutorials"},"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,"project":"544fc17e698ab40800b4f891","user":"544fc065698ab40800b4f888","__v":165,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-11-02T11:59:52.810Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":8,"body":"## Overview \n\nThe Coins Merchant API allows e-commerce merchants to accept payments for goods or services. It instantly settles payments to the Merchant's account in local currency (eg: Philippines Peso).\n\nCustomers may pay via their Coins wallet, or from any other wallet that supports the Blockchain network protocol for value exchange.\n\n### A typical checkout flow will look like this:\n\n1. The merchant creates an [invoice](doc:invoices) via API\n2. Customer is redirected to the payment screen\n3. Customer submits the payment\n4. Customer is redirected back to merchant's assigned [redirect_url](doc:merchant-getting-started) \n5. Merchant is notified of payment confirmation via a secure [callback](doc:merchant-getting-started)\n\n## Using the Merchant API\n\n*Before proceeding, you may want to follow the the instructions for [setting up your merchant account](doc:merchant-getting-started) and retrieving your `merchant_api_token`*\n\nUsing server-side integration allows 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 requests\\n\\nURL = 'https://collector.coins.ph/v1/invoices'\\nMERCHANT_API_TOKEN = 'YOUR_MERCHANT_API_TOKEN'\\nheaders = {\\n    'Authorization': 'Token {}'.format(MERCHANT_API_TOKEN)\\n}\\nbody = {\\n    'amount': 5,\\n    'currency': 'PHP',\\n    'external_transaction_id': 'YOUR_TRANSACTION_ID'\\n}\\n\\nresponse = requests.post(URL, headers=headers, data=body)\\nprint response\",\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\\\":\\t{\\n    \\\"id\\\": \\\"13g32b103\\\",\\n    \\\"amount\\\": \\\"5.00000000\\\",\\n    \\\"currency\\\": \\\"PHP\\\",\\n    \\\"external_transaction_id\\\": \\\"YOUR_TRANSACTION_ID\\\",\\n    // ...\\n    \\\"payment_url\\\": \\\"https://coins.ph/payme/mypaymentpage/payment/13g32b103\\\"\\n  }\\n}\\n\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nYou should now redirect the  customer to `payment_url`, where they will able to complete their payment. \n\nOnce the customer completes the payment flow, they will be redirected back to the `redirect_url` as set in your [merchant settings](doc:merchant-getting-started), and a callback will be made to your provided `callback_url` once payment is confirmed. \n\n### 2. Receiving Payment Notifications\n\nOnce payment has been confirmed from the customer, a POST request is sent to the `callback_url` to inform the merchant application that payment is complete. \n\nIf your `callback_url` uses SSL, we will send the authorization header of `Authorization: Token YOUR_MERCHANT_API_TOKEN` so that you can validate the callback. otherwise, we recommend that you [retrieve the invoice](doc:invoices) via an API call instead.\n\nThe example below illustrates handling of the callback on the merchant 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](doc:invoice-callbacks) invoice events that will trigger a callback and can be handled in a similar fashion","excerpt":"This document explains how to accept payments using the Merchant API","slug":"accepting-payments-with-the-merchant-api","type":"basic","title":"Accept Payments with the Merchant API"}

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. It instantly settles payments to the Merchant's account in local currency (eg: Philippines Peso). Customers may pay via their Coins wallet, or from any other wallet that supports the Blockchain network protocol for value exchange. ### A typical checkout flow will look like this: 1. The merchant creates an [invoice](doc:invoices) via API 2. Customer is redirected to the payment screen 3. Customer submits the payment 4. Customer is redirected back to merchant's assigned [redirect_url](doc:merchant-getting-started) 5. Merchant is notified of payment confirmation via a secure [callback](doc:merchant-getting-started) ## Using the Merchant API *Before proceeding, you may want to follow the the instructions for [setting up your merchant account](doc:merchant-getting-started) and retrieving your `merchant_api_token`* Using server-side integration allows 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 requests\n\nURL = 'https://collector.coins.ph/v1/invoices'\nMERCHANT_API_TOKEN = 'YOUR_MERCHANT_API_TOKEN'\nheaders = {\n 'Authorization': 'Token {}'.format(MERCHANT_API_TOKEN)\n}\nbody = {\n 'amount': 5,\n 'currency': 'PHP',\n 'external_transaction_id': 'YOUR_TRANSACTION_ID'\n}\n\nresponse = requests.post(URL, headers=headers, data=body)\nprint response", "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\":\t{\n \"id\": \"13g32b103\",\n \"amount\": \"5.00000000\",\n \"currency\": \"PHP\",\n \"external_transaction_id\": \"YOUR_TRANSACTION_ID\",\n // ...\n \"payment_url\": \"https://coins.ph/payme/mypaymentpage/payment/13g32b103\"\n }\n}\n", "language": "json" } ] } [/block] You should now redirect the customer to `payment_url`, where they will able to complete their payment. Once the customer completes the payment flow, they will be redirected back to the `redirect_url` as set in your [merchant settings](doc:merchant-getting-started), and a callback will be made to your provided `callback_url` once payment is confirmed. ### 2. Receiving Payment Notifications Once payment has been confirmed from the customer, a POST request is sent to the `callback_url` to inform the merchant application that payment is complete. If your `callback_url` uses SSL, we will send the authorization header of `Authorization: Token YOUR_MERCHANT_API_TOKEN` so that you can validate the callback. otherwise, we recommend that you [retrieve the invoice](doc:invoices) via an API call instead. The example below illustrates handling of the callback on the merchant 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](doc:invoice-callbacks) invoice events that will trigger a callback and can be handled in a similar fashion