Overview

The GroupPay API lets you send payments to up to 100 recipients with a single API call. You specify the payment amount for each recipient individually, but you must use the same currency type for all payments in a GroupPay API request. You can identify recipients either by pinpay username or their Pinpay account number. Pinpay api server receives the GroupPay request and returns a response indicating success or failure for each transaction. If Pinpay returns a successful response, then Pinpay successfully processes the payments. If any error occurs during the processing, Pinpay returns error response.

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);

GroupPay API Using NVP

Pinpay facilitates user with two step of transaction processing. The first step for checking the status and transaction charge for each transaction in the batch and proceeding the payment in next step. The first process is called as 'CHECK' process and the second one is called as 'PROCEED'. To proceed from step one to step two, the batch data are needed to be hold in session. Also the user can directly carry on the 'PROCEED' process if does not want to use 'CHECK' process. Each API request for calling API request consists of required and optional parameters and their values.

GroupPay API Server

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

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

Request string format for checking fee and transaction status

The following is a sample GroupPay API call to two recipients using the NVP (Name-Value Pair). The recipients are specified by username.

SENDER=sender_username &METHOD=GROUPPAY &API_KEY=AD720964-5B7D-4B48-97C8-F738B8CB946B &FEE_PAYER=SENDER &CURRENCY_CODE=USD &PROCESS=CHECK &RECEIVER_0=receiver1_username &AMOUNT_0=10 &NOTE_0=Monthly+Installment &CUSTOM_0=12 &RECEIVER_1=receiver2_username &AMOUNT_1=11 &NOTE_1=Sales+Commission &CUSTOM_0=3.5

Response String Format for checking fee

For each response, Pinpay returns a response message with a http_code and a message associated with the http_code. A successful transaction will always contain a HTTP_CODE of 200 and will include a 'REFERENCENUMBER'

This is a sample response for a successful GroupPay transaction with a 'CHECK' process

SENDER=sender_username &RECEIVER_0=receiver1_username &AMOUNT_0=10.00 &NOTE_0=Monthly+Installment &CUSTOM_0=12 &STATUS_0=OK &FEE_0=0.85 &RECEIVER_1= receiver2_username &AMOUNT_1=11.00 &NOTE_1=Sales+Commission &CUSTOM_0=3.5 &STATUS_1=OK &FEE_1=0.85 &TOTAL_AMOUNT=21.00 &TOTAL_FEE=1.7 &FEE_PAYER=SENDER &HTTP_CODE=200 &PROCESS=CHECK &MESSAGE=Success

Format of an unsuccessful response

An unsuccessful transaction may contain different HTTP_CODE depending upon the nature of error. Let's say, 601 for invalid username or account number, 602 for invalid amount and so on.

Here is a sample response for an unsuccessful GroupPay Transaction.

HTTP_CODE=605 &MESSAGE=API+Key+is+invalid

Request string format for proceeding transaction

This is a sample request which contains all of the necessary fields for proceeding the GroupPay transaction

SENDER=sender_username &METHOD=GROUPPAY &API_KEY=AD720964-5B7D-4B48-97C8-F738B8CB946B &FEE_PAYER=SENDER &CURRENCY_CODE=USD &PROCESS=PROCEED &RECEIVER_0= receiver1_username &AMOUNT_0=10 &NOTE_0=Monthly+Installment &CUSTOM_0=12 &RECEIVER_1= receiver2_username &AMOUNT_1=11 &NOTE_1=Sales+Commission &CUSTOM_0=3.5

Format of a successful response

A successful transaction will always contain a HTTP_CODE of 200 and will include a REFERENCENUMBER. This is a sample response for a successful GroupPay transaction:

SENDER=sender_username &RECEIVER_0= receiver1_username &AMOUNT_0=10.00 &NOTE_0=Monthly+Installment &CUSTOM_0=12 &STATUS_0=OK &FEE_0=0.85 &RECEIVER_1= receiver2_username &AMOUNT_1=11.00 &NOTE_1=Sales+Commission &CUSTOM_0=3.5 &STATUS_1=OK &FEE_1=0.85 &TOTAL_AMOUNT=21.00 &TOTAL_FEE=1.7 &FEE_PAYER=SENDER &REFERENCE_NUMBER=RMJQF-Z4370-TK9GN &RESULT_0=Completed &RESULT_1=Completed &HTTP_CODE=200 &PROCESS=PROCEED &MESSAGE=Success

GroupPay Request Parameters

Fields	Requirement	Description	Type/Format
SENDER	Required	Pinpay username or account name of the payer.	Alphanumeric   SENDER=sender_username
METHOD	Required	Determines the type of api call. For GroupPay it must be GROUPPAY	Alphabetic   METHOD=GROUPPAY
API KEY	Required	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
FEE PAYER	Required	Determines whether to charge the Pinpay Transaction fee to the SENDER or the RECEIVER	Alphabetic   FEE_PAYER=SENDER or FEE_PAYER=RECEIVER
CURRENCY CODE	Required	Determines the currency for the pinpay transaction. The values must be a 3 letter ISO-4217 Code	CURRENCY_CODE=USD
PROCESS	Required	Pinpay facilitates user with two step of transaction processing. The first step for checking the status and transaction charge for each transaction in the batch and proceeding the payment in next step. The first process is called as 'CHECK' process and the second one is called as 'PROCEED'. To proceed from step one to step two, the batch data are needed to be hold in session. Also the user can directly carry on the 'PROCEED' process if does not want to use 'CHECK' process.	Alphabetic   PROCESS=CHECK or PROCESS=PROCEED
RECEIVER_x	Required	The payment recipient's Pinpay username or account number. The "x" represents the receiver number associated with this batch payment starting from 0.	Alphanumeric   RECEIVER_0=receiver1_username
AMOUNT_x	Required	The amount to be paid for RECEIVER_x. The amount must be greater than 1 for any currency used.	Numeric   AMOUNT_0=10.50
NOTE_x	Optional	Note that you would like to add to this transaction. The "x" represents the receiver number associated with this note. This note is sent to the receiver in the payment notification email.	Alphanumeric   NOTE_0=Monthly Installment
CUSTOM_x	Optional	Custom value you can pass along with the GroupPay payment.This value will not be viewable to the receiver. This may contain receiver count or any information about the payemnt.	Alphanumeric   CUSTOM_0=Some sample value

For RECEIVER_x, AMOUNT_x, NOTE_x and CUSTOM_x, the appended _x is the receiver number, starting with 0 and increasing by one for each additional receiver. The first receiver must be defined as a variable ending with _0 and must be present before adding any other number. The receiver number specified by _x value ties with the required variable AMOUNT_x and with the corresponding NOTE_x variable, which is optional. To properly process your GroupPay requests, the _x values must increase by increments of one continuously. Skipping a number will result in our API ignoring the remaining payments. For example, if you skip from receiver #2 to receiver #4, only receiver #2's payment will be processed.

GroupPay Response Parameters

Fields	Description	Process	Type/Format
SENDER	Pinpay username or account name of the payer.	Both CHECK and PROCEED	Alphanumeric   SENDER=sender_username
HTTP_CODE	The HTTP_CODE determines the result. For each successful request it returns 200.	Both CHECK and PROCEED	Numeric   HTTP_CODE=200
FEE PAYER	The Pinpay transaction fee payer as sent on request by user.	Both CHECK and PROCEED	Alphabetic   FEE_PAYER=SENDER or FEE_PAYER=RECEIVER
CURRENCY CODE	Currency for the pinpay transaction as sent on request by user.	Both CHECK and PROCEED	CURRENCY_CODE=USD
PROCESS	Determines whether to check the traansction status and charges or to carry out the transaction as sent on request by user.	Either CHECK or PROCEED	Alphabetic   PROCESS=CHECK or PROCESS=PROCEED
RECEIVER_x	The payment recipient's Pinpay username or account number.	Both CHECK and PROCEED	Alphanumeric   RECEIVER_0=receiver1_username
AMOUNT_x	The amount to be paid for RECEIVER_x.	Both CHECK and PROCEED	Numeric   AMOUNT_0=10.50
NOTE_x	Any note about the transaction as sent on request by user.	BOTH CHECK and PROCEED	Alphanumeric   NOTE_0=Sales Commission
CUSTOM_x	Any custom value about the transaction as sent on request by user.	BOTH CHECK and PROCEED	Alphanumeric   CUSTOM_0=Some sample value
REFERENCE NUMBER	A 17 digit unique Reference Number to identify the batch of payment.	Only PROCEED	Alphanumeric   REFERENCE_NUMBER=RMJQF-Z4370-TK9GN
FEE_x	Pinpay charges certain amount per transaction in the batch. FEE_x consists of fee for transaction of RECEIVER_x.	BOTH CHECK and PROCEED	Numeric   FEE_0=1.25
STATUS_x	Represents the status of each transaction whether there's any error or not.	BOTH CHECK and PROCEED	Alphabetic   STATUS_0=OK or STATUS_0=ERROR
RESULT_x	Any custom value about the transaction as sent on request by user.	BOTH CHECK and PROCEED	Alphanumeric   RESULT_0=Completed
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.	BOTH CHECK and PROCEED	Alphanumeric   MESSAGE=Success

Downloads

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

Here is a sample code of a complete application using GroupPay api and GetBalance API. Click Here to downlaod.