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

A typical merchant's journey is as follows:

1. Customer confirms the checkout of his order
2. Merchant consumes the Invoices API
3. Customer is redirected to the Coins.ph payment widget screen, as seen in the sample screens above.
4. 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

   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.

5. After the customer has fully paid the particular invoice, he is redirected back to the merchant’s application via the redirect URL
6. Merchant will receive a notification upon confirmation of payment via a secure callback

Building with the Merchant API

📘

Before starting to integrate with the payment gateway, you may want to follow the instructions for setting up your merchant account and retrieving your merchant_api_token first

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. When creating an invoice, you may specify amount, currency, and description.

curl -H 'Authorization: Token YOUR_MERCHANT_API_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{"amount": 5, "currency": "PHP", "external_transaction_id": "YOUR_TRANSACTION_ID"}' \
     -X POST \
     https://api.coins.asia/v1/invoices/

import json
import requests

url = "https://api.coins.asia/v3/invoices/"

TOKEN = 'YOUR TOKEN'
headers = {
    'Authorization': 'Bearer {}'.format(TOKEN),
    'Content-Type': 'application/json;charset=UTF-8',
    'Accept': 'application/json'
}
body = json.dumps({
     "amount": 120,
     "currency": "PHP",
     "external_transaction_id": "89723952"
})

requests.post(url, headers=headers, data=body)
print(response.text)

require 'uri'
require 'json'
require 'net/http'

url = URI('https://collector.coins.ph/v1/invoices')

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url.request_uri)
request["content-type"] = 'application/json'
request["authorization"] = 'Token YOUR_MERCHANT_API_TOKEN'
request.body = JSON.dump({
    amount: 5,
    currency: 'PHP',
    external_transaction_id: 'YOUR_TRANSACTION_ID'
})

response = http.request(request)
puts response.read_body

Here is a sample response (some fields removed for brevity).

{
  "invoice": {
    "id": "voro5v750qyig7dayil9wkteokfc90kg",
    "status": "pending",
    "category": "merchant",
    "amount": "120.00000000",
    "currency": "PHP",
    "external_transaction_id": "89723969",
    "payment_url": "https://coins.ph/payment/invoice/voro5v750...",
    "supported_payment_collectors": ["cash_payment"],
  }
}

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 through a GET request through API call instead.

The example below illustrates handling of the callback on the merchant's side:

import json
from django.http import HttpResponse

MERCHANT_API_TOKEN = 'YOUR_MERCHANT_API_TOKEN'

# Using Django
def my_callback_view(request):
    # Verify callback
    authorization_header = request.META.get('Authorization')
    auth_parts = authorization_header.split(' ')
    if (len(auth_parts) != 2 or auth_parts[1] != MERCHANT_API_TOKEN) :
        return HttpResponse(status=401)
  
    # Retrieve the request's body and parse it as JSON
    event_json = json.loads(request.body)
    message = 'Event {} for "{}" was received'.format(
        event['name'],
        event['data'].get('id', 'Unspecified')
    )
    
    print message

    return HttpResponse(status=200)

MERCHANT_API_TOKEN = 'YOUR_MERCHANT_API_TOKEN'

require 'json'

# Using Sinatra
post "/my/webhook/url" do
  # Verify webhook
  authorization_header = request.headers['Authorization']
  _, api_key = authorization_header.split(' ')
  
  if api_key != MERCHANT_API_TOKEN:
    status 401
  
  # Retrieve the request's body and parse it as JSON
  event_json = JSON.parse(request.body.read)

  puts "Event #{event_json["event"]["name"]} was received"

  status 200
end

Here is an example payload for a confirmed payment event:

{
  "event": {
    "name": "invoice.fully_paid",
    "data": {
      "id": "13g32b103",
      "currency": "PHP",
      "amount": "5.00000000",
      "amount_received": "0.00000000",
      "external_transaction_id": "YOUR_TRANSACTION_ID"
    }
  }
}

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 document.

Sample errors for Invoices API: