Skip to content

Latest commit

 

History

History
128 lines (84 loc) · 7.46 KB

Payment.md

File metadata and controls

128 lines (84 loc) · 7.46 KB

Introduction

The Globe Payment API lets you develop client applications to charge people using the most basic form of electronic communication. This document describes how to use the OAUTH/RESTful calling style and client libraries for varrefuious programming languages (currently Java, Python, PHP, NodeJS and Ruby) to charge subscribers. For other languages and libraries you can access the Payment protocol manually. The following documentation describes how you can access the Payment API directly with examples of request types, options and responses.

Getting Started

The first thing we need to do is obtain an APP ID and APP SECRET from Globe's Developer Website. When visiting the link provided you should see a login form similar to Figure PROTO.PAYMENT.1.

Figure PROTO.PAYMENT.1 - Login

Login Screen

Currently Globe's RESTful API is in BETA Mode. Ask your local Globe support to gain access to this BETA.

Next, login with your given credentials to get to the APP screen. When you get to the app screen scroll to the bottom right and click the "create" button to create a new app. You should see something familiar to Figure PROTO.PAYMENT.2

Figure PROTO.PAYMENT.2 - Create App Button

Create App Button

This will bring you to a form with required information that Globe will need to process your app creation. Fill out this form with the required fields at the very least and press Submit found at the bottom right in Figure PROTO.PAYMENT.3.

Figure PROTO.PAYMENT.3 - Create App Form

Create App Form

**Important:** It's important that the Redirect URI and the Notify URI are using actual 
URLs as in http://www.example.com/callback. Globe will call these URLs as described in the field.

From here you should be returned to the APP Detail Page in Figure PROTO.PAYMENT.4. The important thing here is the APP ID and APP SECRET. These will be the information that you will need to manually set in the configurations when writing your application.

Figure PROTO.PAYMENT.4 - App Details

Create App Form

**Note:** The data in this screen doesn't actually work. Please don't assume something went 
wrong because you tried to use it.

Authentication

Once we obtain the APP ID and APP SECRET we can begin to understand how the authentication works. Globe uses OAUTH2, a common protocol to authenticate developers to use API protocols. To begin the authentication process you must redirect the user to a formatted URL using your APP ID as in Figure PROTO.PAYMENT.5.

Figure PROTO.PAYMENT.5 - Invoke a Redirection
http://developer.globelabs.com.ph/dialog/oauth?app_id=[YOUR APP ID]

Before invoking your redirect, please replace [YOUR APP ID] in the figure above with your actual APP ID. Based on what you inputed as your Redirect URI in your app details. Globe will authenticate permissions first with the user which should look like Figure PROTO.PAYMENT.6a and Figure PROTO.PAYMENT.6b.

Figure PROTO.PAYMENT.6a - User Flow

User Flow

Figure PROTO.PAYMENT.6b - Authorize

Authorize

Once the user gives permission, Globe will redirect the user to your Redirect URI with a code parameter appended to the end of it. This is how we recieve the code to continue the authentication process. Figure PROTO.PAYMENT.7 shows how this redirect will look like given that we set our redirect URI to http://www.example.com/callback in our app create form in Figure PROTO.PAYMENT.3.

**Important:** It is also possible that a user can give permissions to your app using just their 
phone via SMS. Globe will call (not a phone call) your redirect URI with `access_token` and 
`subscriber_number` appended to the end of it. From here you can process this request and 
ignore the rest of the authentication process below.
Figure PROTO.PAYMENT.7 - Redirected URI Sample
http://www.example.com/callback?code=12345

12345 in the URL figure above is what we need in order to get a more long lasting token for your app to use when making API calls. Everytime you make this call the code returned will be unique, so you should not hard code the code value in your application. The final step in the authentication process is about exchanging your code with a more permanent access token. We need to send Globe one final request shown in Figure PROTO.PAYMENT.8

Figure PROTO.PAYMENT.8 - Get the Access Token
POST http://developer.globelabs.com.ph/oauth/access_token?app_id=[YOUR APP ID]&app_secret=[YOUR APP SECRET]&code=[CODE]

Before sending, please replace [YOUR APP ID] in the figure above with your actual APP ID, replace [YOUR APP SECRET] in the figure above with your actual APP SECRET and replace [CODE] in the figure above with the code given from Figure PROTO.PAYMENT.7.

**Note:** Remember set your access token request to globe using the POST method.

Finally, Globe will return an access token you can use to start using the Charge API. Figure PROTO.PAYMENT.9 shows how this response will look like

Figure PROTO.PAYMENT.9 - Access Token via JSON
{
  "access_token": "GesiE2YhZlxB9VVMhv-PoI8RwNTsmX0D38g",
  "subscriber_number": "9051234567"'
}

**Note:** The data in above doesn't actually work. Please don't assume something went wrong 
because you tried to use it.

Charge

To use charge API you will need to send a POST request to the URL given below.

Request URL

http://devapi.globelabs.com.ph/payment/v1/transactions/amount

Parameters

Field Definition Data Type
transactionOperationStatus set this field to charged
access_token which contains security information for transacting with a subscriber. Subscriber needs to grant an app first via SMS or Web Form Subscriber Consent Workflow. String
endUserId is the MSISDN (mobile number) which you will charge to. Parameter format can be 09xxxxxxxx String or Integer
amount can be a whole number or decimal String
referenceCode Is a unique transaction ID with a format of [SHORTCODE]+####### where ####### is an incremented number beginning from 1000001. Integer
**Note:** You can get your Short Code value from your Globe App Details in `Figure PROTO.PAYMENT.4. You also need to remove the `2158` digit in your short code.
Figure PROTO.PAYMENT.10 - Sample Charge Request
POST http://devapi.globelabs.com.ph/payment/v1/transactions/amount
  -F "transactionOperationStatus=[STATUS]"\
  -F "access_token=[YOUR ACCESS TOKEN]" \
  -F "endUserId=[MOBILE NUMBER]" \
  -F "amount=[AMOUNT]" \
  -F "referenceCode=[UNIQUE REFERENCE]" \
Figure PROTO.PAYMENT.11 - Sample Charge Response
{
  "access_token": "GesiE2YhZlxB9VVMhv-PoI8RwNTsmX0D38g",
  "transactionOperationStatus": "charged",
  "endUserId": "9171234567",
  "amount": "10",
  "referenceCode": "12341000001",
  "success": true
}