Technical Details

URL format

As defined by the W3C (Worldwide Web Consortium), a URL (Uniform Resource Locator) must conform to URI (Uniform Resource Indicator) specifications. Also, the request and response are in URL-encoded format. You can find out more about URI at http://www.w3.org/Addressing/

URL-encode

The request string that is sent to the API must be URL-encoded into a valid URL format. In order to transmit special characters, characters that are not allowed in a URL and characters that have special meaning in a URL sent properly across the internet, URL-encoding must be performed prior to sending any data.

For example, the following string, NOTE=This is a test data & only a test, will be URL-encoded as follows: NOTE=This+is+a+test+data+%26+only+a+test

$encoded_data = urlencode($data);

GetBalance API Server

https://api.pinpay.co/apirequests/GetBalance

Security

HTTPS: User-Agent

To ensure data security, we recommend all the user to use standard HTTPS request. The data that are passed while making a Pinpay API request must be confidential so they have to be SSL encrypted. The primary reason why SSL is used is to keep sensitive information sent across the Internet encrypted so that only the intended recipient can understand it. This is important because the information you send on the Internet is passed from computer to computer to get to the destination server. Any computer in between you and the server can see your api keys, usernames and passwords, and other sensitive information if it is not encrypted with an SSL certificate. When an SSL certificate is used, the information becomes unreadable to everyone except for the server you are sending the information to. This protects it from hackers and identity thieves.

URL For API Registration

https://www.pinpaysoftcard.com/api_management.php

An api key can be used to send GetBalance Request to the username or account associated with the api key. Checking the balance of other accounts is not allowed.

Request string format

Here is a sample request with all of the necessary fields to make a GetBalance API call.

USERNAME=pinpay_username &API_KEY=9f78a9sd-800j-foqi-wroj-8240-9384aoifu8w0 &METHOD=GETBALANCE &CURRENCY_CODE=USD

Response String Format

The response messages are urlencoded. The response message includes the total balance of the user. In an unsuccessful request, the message includes error string.

Format of a successful response

A successful response will always return a HTTP_CODE of 200 and will include a success message.

Here is a sample response for a successful GetBalance API call

HTTP_CODE=200 &MESSAGE=SUCCESS &BALANCE=500.00 &CURRENCY_CODE=USD

Format of an unsuccessful response

An unsuccessful transaction may contain different HTTP_CODE depending upon the nature of error. Let's say, 605 for invalid api key..

Here is a sample response for an unsuccessful GetBalance request.

HTTP_CODE=301 &MESSAGE=INVALID+API+KEY

GetBalance Request Parameters

Fields	Requirement	Description	Type/Format
USERNAME	Required	Pinpay username or account name to check the balance.	Alphanumeric   USERNAME=pinpay_username
METHOD	Required	Determines the type of api call. For GetBalance it must be GETBALANCE	Alphabetic   METHOD=GETBALANCE
API KEY	Required	GetBalance API key associated with the username. To ensure that a request made to the API comes from you, you must submit a api key with your request.	Alphanumeric   API_KEY=XXXXXXXX-XXXX-XXXXX-XXXX-XXXXXXXXXXXXX
CURRENCY CODE	Required	Determines the currency for the pinpay transaction. The values must be a 3 letter ISO-4217 Code	CURRENCY_CODE=USD

GetBalance Response Paramenters

Fields	Description	Type/Format
SENDER	Pinpay username or account name of the payer.	Alphanumeric   SENDER=sender_username
HTTP_CODE	The HTTP_CODE determines the result. For each successful request it returns 200.	Numeric   HTTP_CODE=200
CURRENCY CODE	Currency for the pinpay transaction as sent on request by user.	CURRENCY_CODE=USD
BALANCE	The pinpay balance of the user.	Numeric   BALANCE=500.00
MESSAGE	Message is the real response body of the batch payment. It consists of message according to the HTTP_CODE associated with the GroupPay request.	Alphanumeric   MESSAGE=Success

Downloads

Here is a sample code to call the Pinpay GetBalance api. Click Here to downlaod.