Request payments from anyone

Overview

The Coins Payment Requests API allows coins users to request for payments from anyone who has at least one of the following:

Coins account
Phone number
Email

A typical payment request flow will look like this:

The requester creates a payment request which would be sent to a chosen contact (coins account, phone number, email).
The payer receives a notification through the channel chosen by the requester (coins account, phone number, email).
The payer visits the payment link in the notification and chooses one of the currently available payment options.
The payer completes payment through their chosen payment option.
The requester receives their payment.

Using the Payment Requests API

Before proceeding, you may want to follow the the instructions for Creating your API keys and Choosing an Authentication method. We recommend using HMAC authentication, unless you would like to create a payment request in behalf of another coins user.

1. Creating a payment request:

A payment request requires the following to be present in the payload:

payer_contact_info - The contact to send a payment request to. It can be a phone number or an email address. If the target payer is a registered coins user, payer_contact_info may also be that user's Facebook ID.
receiving_account - Account ID of the wallet to receive funds. To retrieve a wallet's account ID, please use the accounts endpoint.
amount - The requested amount to be paid for by the payer.
message - An arbitrary message that will be attached to the payment request.

curl -X POST \
    -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json;charset=UTF-8" \
  -H "Accept: application/json" \
  -d '{"payer_contact_info": "[email protected]","receiving_account": "5411c4604c9b45b8b74837c84daa0f4c","amount": 20,"message": "Thanks for all the fish!"}' \
    "https://coins.ph/api/v3/payment-requests/"

import json
import requests

url = "https://coins.ph/api/v3/payment-requests/"

TOKEN = 'YOUR TOKEN'
headers = {
    'Authorization': 'Bearer {}'.format(TOKEN),
    'Content-Type': 'application/json;charset=UTF-8',
    'Accept': 'application/json'
}
body = json.dumps({
    'payer_contact_info': '[email protected]',
    'receiving_account': '5411c4604c9b45b8b74837c84daa0f4c',
    'amount': 20,
    'message': 'Thanks for all the fish!'
})

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

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

url = URI('https://coins.ph/api/v3/payment-requests/')

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"] = 'Bearer YOUR_BEARER_TOKEN'
request.body = JSON.dump({
  payer_contact_info: '[email protected]',
  receiving_account: '5411c4604c9b45b8b74837c84daa0f4c',
  amount: 20,
  message: 'Thanks for all the fish!'
})

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

Here's an example response:

{
    "payment-request": {
        "id": "5edc263fac7f4f61b87632cb5710050f",
        "invoice": "5713e3ab76e74e6b85194deaf0f14cel",
        "payer_contact_info": "[email protected]",
        "payer_contact_info_type": "email",
        "payer_email": "[email protected]",
        "amount": "20.00000000",
        "currency": "PHP",
        "message": "Thanks for all the fish!",
        "message_scope": "private",
        "status": "pending",
        "receiving_account": "5411c4604c9b45b8b74837c84daa0f4c",
        "payment_url": "https://coins.ph/payment/request/5edc263fac7f4f61b87632cb5710050f",
        "created_at": "2016-03-04T07:12:00.352338Z",
        "updated_at": "2016-03-04T07:12:00.474500Z",
        "expires_at":"2017-03-04T07:11:59.942484Z"
    }
}

2. Payer receives the payment request

Once the payment request is created, the payer will receive a notification through the contact information provided in the payment request. Once the payer clicks the link in the notification, they will be presented with a list of payment options:

Once the payer completes the payment, funds will be credited to the requester's provided receiving account.

More Information

The payment requests API is explained in more detail in their appropriate endpoint docs:

GET
POST