Join Dev Community
Login

Introduction

Getting Started

Welcome to UFPay Api!

This is the official API documentation of United Family Pay (UFPay) intended for developers who want to integrate the UFCoin payments into their projects, this documentation will guide you to understand the working principles of the UFPay API and endpoints, guide you on getting started and will guide you on how to start accepting payments and making payouts in UFC without much hassles within seconds.

This documentation is still being updated constantly and more functions are currently being developed to be added to this documentation. Kindly go ahead and join our Developers Community so that you can get the latest updates and announcements. Feel free to drop any feedback if you find errors in this documentation, in the way the API works or if you have any improvement suggestions.

How to read this document

The top of this documentation has the search bar and some navigation menus to some crucial destinations; This Documentation has three parts, the left hand side is a nav list for quick access, the middle part is the documentation body, and the right hand side shows request and response samples.

Was this section helpful? Yes No

Basic Overview

The UFPay API is built using REST architectural programming style and strives to be restful so as to make api calls to its endpoints simple and straightforward. The UFPay API has well organised and predictable endpoint URLs, uses JSON as both the input (request bodies) and output (responses) payload format, and uses standard HTTP status codes, authentication, and verbs.

API HTTP Verbs

GET to fetch an existing resource. POST to create a new resource and performing actions that requires some input body. PUT to update an existing resource. DELETE to delete an existing resource.

More on Authentication & HTTP Status Code will be discussed in depth in another section of this documentation

Live Mode & Test Mode

You can use the UFCoin Live API or Test Api, and both have very minor differences. The Test Api uses TUFC (Test UFCoins) and doesn't affect your live balances. The API key used to authenticate the request determines whether the request is a Live Request (live mode) or Test Request (test mode).

Note that both the Live Mode and the Test Mode uses same baseurl and endpoints.

This is just an introduction to the UFCoin Api Live Mode & Test Mode, their working principles and how they can be used will be discussed in depth in another section of this documentation.

Was this section helpful? Yes No

Check out our development quickstart guide.

Base URL
https://api.united-family.org
Code Samples
Ruby
Python
PHP
Java
Node.js
Go
.NET

Authentication

Where do I even start from? Before you do anything:

1. Go ahead and Create a UF Developer Account
2. Grab your Test Api Keys from your UF Developer Account Dashboard

You'll need both public and secret keys. Public keys are meant to be used from your front-end and for when performing certain functions like creating payments. By design, public keys cannot modify any part of your account besides creating payment transactions on your App. The secret keys however perform more delicate validations, if you think your keys may have been compromised (for instance, you accidentally committed them to an online repo), you should immediately generate new ones using the "Generate New Keys" button on the Api Keys page in your developer dashboard. This will invalidate all existing keys and give you a new set, and you can then update your app to use the new ones just generated.

Test mode public keys & secret keys are prefixed UFPK-TEST- & UFSK-TEST- respectively and in the same way the live mode public keys & secret keys are prefixed UFPK-LIVE- & UFSK-LIVE- respectively.

Authenticate all your API calls by including your secret key in the header of every request you make. API requests made without authentication will fail with the status code 401: Unauthorized.

To authenticate API calls from your server, pass your public key or secret key with a header key Authorization in Bearer format.

All API requests made over HTTP will fail. UFPay Api will only interact over HTTPS. API requests without authentication will also fail.

Was this section helpful? Yes No

For example, an API call authentication header could look like this:

Authentication Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<?php
  $curl = curl_init();
  curl_setopt_array($curl, array(
	CURLOPT_URL => "https://api.united-family.org/v1/payments",
	CURLOPT_RETURNTRANSFER => true,
	CURLOPT_CUSTOMREQUEST => "POST",
	CURLOPT_HTTPHEADER => [
	  "Authorization: Bearer UFPK-TEST-009a466860704ed7c5d7e0b40d2",
	  "Cache-Control: no-cache",
	],
	CURLOPT_POSTFIELDS => json_encode([
	  //Payload...
	]),
  ));
?>
Request without authentication: HTTP 400 
{
  "status": "error",
  "message": "Missing API Key",
  "data": null,
}

Errors

There are five main kinds of errors you can come accross with using the UFPay API: authentication errors, validation errors, server errors. UFPay API follows RESTful architectural programming style and as such, each type of error comes with an appropriate HTTP response codes to indicate the success or failure of requests. All errors share the same basic response format: a status key set to "error", a message describing the error and data key returns null.

HTTP status code summary
200, 201 - OK Everything worked as expected.
400 - Bad Request The request was unacceptable, often due to missing a required parameter.
401 - Unauthorized Invalid API key provided.
402 - Request Failed The parameters were valid but the request failed.
403 - Forbidden The API key doesn't have permissions to perform the request.
404 - Not Found The requested resource doesn't exist.
422 - Unprocessible Entity The parameters failed during validation checks.
429 - Too Many Requests Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504 - Server Errors Something went wrong on UFPay Server. These errors rarely happen.

Was this section helpful? Yes No

Making any API call without an Authorization Header will return the response below:

Response: HTTP 400 
{
  "status": "error",
  "message": "Missing API Key",
  "data": null,
}

Making any API call with an incorrect public key or secret key will return the response below:

Response: HTTP 401 
{
  "status": "error",
  "message": "Invalid API Key",
  "data": null,
}

Making any API call with invalid request body will return the response below:

Response: HTTP 400 
{
  "status": "error",
  "message": "Validation Error",
  "data": null,
}

Receive Payments

To start receiving United Family Coins payments with the UFPay API, first ensure you've gone through these prerequisites:

• First of all Create a UF Developer Account if you haven't.
• Grab your Test Api Keys from your UF Developer Account Dashboard.
• When you're ready to start receiving Live Payments, create an App from your developer dashboard to get an app ID.
• Connect a UF Wallet to your app and then you can finally grab your Live Api Keys.

Here's the process workflow

1. From your server, send a POST request to UFPay payments endpoint with the payment details.
2. You'll get a payment link to a payment page in the response.
3. Redirect user to this link to make the payment.
4. When the transaction is completed, the user will be redirected back to your redirect_url setup in your developer account.

Step 1: Set payments details

To receive payment from a user/customer you'll need to send the following in the request header:
• Authorization: Bearer Set value to your public API key
• content-type: Set value to application/json

To receive payment from a user/customer you'll need to send the following in the request body:
• amount: Amount you're charging the user/customer
• currency: The currency to charge in. If you don't specify a currency, it'll default to "UFC". (optional)
• tx_ref: Unique transaction reference. Should not be more than 30 characters, only alphanumeric characters and hyphen - allowed. (optional)

Step 2: Get a payment link

Next, create the payment by making an API request with the collected payment details.

Step 3: Redirect the user to the payment link

Now all you need to do is to redirect the user to the payment link returned in the response data.link, and they'll get the UFPay API payment gateway interface for them to make the payment.

Step 4: After making payment

After making payment successfully or if user cancels payment or if payment expires they'll be redirected back to the URL your submitted when setting up that particular app.
If in Test Mode or you did not input a redirect_url they'll be redirected to the default redirect_url.

Was this section helpful? Yes No

For example, to start a payment process (creating payment) could look like this:

Post Payments
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
<?php
  $curl = curl_init();
  curl_setopt_array($curl, array(
	CURLOPT_URL => "https://api.united-family.org/v1/payments",
	CURLOPT_RETURNTRANSFER => true,
	CURLOPT_CUSTOMREQUEST => "POST",
	CURLOPT_HTTPHEADER => [
	  "Authorization: Bearer UFPK-TEST-009a466860704ed7c5d7e0b40d2",
	  "content-type: application/json",
	  "Cache-Control: no-cache",
	],
	CURLOPT_POSTFIELDS => json_encode([
	  "amount" => 0.0123,
	  "currency" => "UFC",
	]),
  ));
?>
Response: json 
{
  "status": "success",
  "message": "Hosted Link",
  "data": {
    "payment_id": "239889009",
    "link": "https://hosted.united-family.org/v1/payments/UFMmPnQJX9UJPTIZ1bPMijUuB3OIW07ZUtOJV",
  },
}

Verify Payment

To verify a payment, send a GET request to the verify payment endpoint, passing in the payment ID in the URL. You can get the payment ID from the data.id field that is present in the response you get after creating a payment.

Here are some important things to check for when verifying a payment:

• Verify that the payment_id matches the one you got when you created the payment and either stored in your database or sessioned
• Verify that the status of the transaction is successful.
• Verify that the amount paid was greater than or equal to the amount you expect. If the amount was greater, you can give the customer value and refund the rest.
• Verify that you have not given value for this particular payment to avoid giving value twice for the same payment.

Quick Note:

Ensure after every payment is completed successfully and redirected back to you, that you verify the payment was successful and confirmed on the UF blockchain before giving value to your customer in your application. This serves as a failsafe, ensuring that the payment that was made is the payment you requested.

Headers:

When verifying payments, you have to pass your Test Secret Key or Live Secret Key through the header parameter Authorization
Therefore "Authorization: Bearer ***Valid Secret Key***"

Body:

No body/payload is required as this is a GET request.

You can also verify a payment using the tx_ref if you sent one while initializing the payment by sending a GET request to the verify-by-ref endpoint

• If you'll be using tx_ref for verifying payment ensure you always send a unique string for every payment initialized.
• The tx_ref parameter is an optional parameter but if provided, after a successful, cancelled or expired payment it'll be sent to your redirect url and if not provided the payment_id will be sent instead.

Was this section helpful? Yes No

For example, to verifying a payment could look like this:

Get payments/:id/verify
1
2
3
4
5
6
7
8
9
10
11
12
13
<?php
  $curl = curl_init();
  curl_setopt_array($curl, array(
	CURLOPT_URL => "https://api.united-family.org/v1/payments/239889009/verify",
	CURLOPT_RETURNTRANSFER => true,
	CURLOPT_CUSTOMREQUEST => "GET",
	CURLOPT_HTTPHEADER => [
	  "Authorization: Bearer UFSK-TEST-009a466860704ed7c5d7e0b40d2",
	  "content-type: application/json",
	  "Cache-Control: no-cache",
	],
  ));
?>
Response: json 
{
  "status": "success",
  "message": "Payments fetched successfully",
  "data": {
    "payment_id": "239889009",
    "tx_ref": "Nike-019229",
    "app_id": "3003",
    "status": "Successful",
    "state": "Paid",
    "coin": "UFC",
    "currency": "USD",
    "requested_amount": "1.22000000",
    "paid_amount": "1.22000000",
    "sender_address": "UF0mPnQJX9UJPTIZ1bPMijUuB3OIW07ZUtOJV",
    "receiver_address": "UFMmPnQJX9UJPTIZ1bPMijUuB3OIW07ZUtOJV",
    "created_at": "2022:10:09T13:41:59.000Z",
    "paid_at": "2022:10:09T13:41:59.000Z",
  },
}