PayPics is a place-based promotion and payment platform allowing consumers to use their smartphones to take advantage of promotional offers wherever they encounter them while on the go.
SUMMARY
The PayPics integration framework is based on OAUTH and consists of the following API operations:
- CREATEPAYMENT: A signed OAUTH request that returns a URL for a payment mobile tag.
- CREATEPROMOTION: A signed OAUTH request that returns a URL for a promotion mobile tag.
- CREATEOFFER: A signed OAUTH request that returns a URL for a place-based offer mobile tag (coming soon).
- PMTREFUND: A signed OAUTH request that returns a parameter (refund) that is set to true if the transaction has been successfully refunded.
- CHECKPAYMENTSTATUS: A signed OAUTH request that returns a parameter (pmt) which will be set to: paid, refund, other, or unknown (error condition).
PAYPICS PAYMENT INTEGRATION DETAILS
The PayPics Payment Integration framework is based on the open authentication standard OAUTH. The overall process is made up of the following steps:
- Create an account at the PayPics website. Once registered you will have access to an OAUTH Consumer Key and Secret, and you will be able to obtain an OAUTH Access Token and Secret to use with the API operations described below (Merchants menu option on the PayPics website).
- Create a payment request via the CREATEPAYMENT API operation, which is a signed OAUTH request that returns a URI pointer to a Microsoft Tag jpeg image . It contains the following parameters:
- transactionid - a transaction ID that is created and used by the calling application to track the payment transaction (up to 50 characters). Set transactionid to “auto” and PayPics will create the transactionid for each transaction (this allows for one PayPics mobile tag to be used for multiple transactions).
- amount – the purchase price or amount of the transaction.
- memo – a description of the purchased items that will be verified by the user. This should be descriptive enough to help the user/buyer recognize the products they have purchased (up to 140 characters).
- delegate – a URI on the merchant website that will be invoked by PayPics to report the status of the payment transaction identified by transactionid. Contact PayPics to discuss a PayPics hosted script.
- marketingurl – a mobile optimized URL that provides additional details on the transaction that can be viewed by the buyer
- buyerprice – optional parameter that is set to true to indicate that the buyer will provide an amount for the transaction. This is appropriate for donations that allow the user to specify how much they wish to donate. If the parameter is missing or set to false, the amount provided in the API request is used for the price. In either case, the amount parameter must be provided, and in donation transactions is the suggested amount for the donation.
- gratuity – optional parameter that is set to true to indicate that the buyer can specify a gratuity amount that will be added to the payment amount. If the parameter is missing or set to false, the user cannot specify a gratuity amount.
- tab – optional parameter that is set to true to indicate that the buyer can open a tab instead of paying for each purchase. If the parameter is missing or set to false, the buyer must pay for each purchase individually.
The response of the CREATEPAYMENT request will contain the following parameters:
- ACK – set to Success or Failure to indicate whether the operation was successful or not
- tag_url – a URI for the mobile tag image that is displayed to the user/buyer
- errormsg – included when an error occurs (ACK=Failure) and provides additional error information
- Once the user has scanned the payment tag and authorized the payment, the delegate URI is invoked by PayPics with the following parameters in the body of the POST request:
- ACK – the status of the payment request which is set to “paid” once the user has authorized payment via a PayPal account. Set to “unpaid” if the user cancels the payment operation.
- transactionid – the transaction ID sent with the original CREATEPAYMENT API method (or created by PayPics if transactionidwas set to “auto”) This transactionid should be used for PMTREFUND and CHECKPAYMENTSTATUS operations and should be retained by the calling application.
- verification – a verification code for the transaction. Store with the transaction record in case there is a problem with a payment.
- errormsg- included when an error occurs and provides additional error information
- consumer – a unique and persistent token that identifies the PayPics user for future transactions
- info – the user’s personal contact information
- gross – the transaction amount
- paypicsfee – the amount of the PayPics fee for this transaction (the gross amount minus the paypicsfee will be deposited into the merchant’s PayPal account as the PayPal gross amount)
- datetime – the date and time that the PayPics user scanned the payment tag
- signature – an HMAC-SHA1 signature that is a hash of the preceeding parameters using the merchant’s OAUTH consumer secret and a null OAUTH token (i.e. the OAUTH secret followed by an “&”). Use the signature to verify that the payment result is valid and has not been modified.
- IMPORTANT: Your application should validate the transaction information and then respond with an HTTP status code of 200 to indicate a success, or an HTTP status code 204 to indicate a failure. In this way PayPics can notify the user about any error conditions. In addition, the HTTP status description value can be set to a short informative message that will be displayed to the PayPics user.
PAYPICS PROMOTION INTEGRATION DETAILS
The PayPics Promotion Integration framework is based on the open authentication standard OAUTH. The overall process is made up of the following steps:
- Create an account at the PayPics website. Once registered you will have access to an OAUTH Consumer Key and Secret, and you will be able to obtain an OAUTH Access Token and Secret to use with the API operations described below (Merchants menu option on the PayPics website).
- Create a promotion via the CREATEPROMOTION API operation, which is a signed OAUTH request. It contains the following parameters:
- promotion – the name of the promotion (up to 50 characters).
- id – a merchant provided ID for the promotion (up to 50 characters).
- memo – a description that will help the user understand the promotion (140 characters).
- type – the promotion type. Allowable values include: discount, contest, prospect, track.
- track – optional merchant generated ID that is used to associate a new promotion enrollment with an internal user. The track parameter will be returned as part of the promotion transaction response.
- delegate – a URI on the merchant’s website that will be invoked by PayPics to report the status of the CREATEPROMOTION operation. Contact PayPics to discuss a PayPics hosted script.
- marketingurl – a mobile optimized URL that provides additional details on the transaction that can be viewed by the buyer
The response of the CREATEPROMOTION request will contain the following parameters:
- id – the merchant provided promotion ID
- tag_url – a URL for the promotion tag.
- ACK – the status of the promotion request which is set to “Success” or “Failure”.
- errormsg – included when an error occurs (ACK=Failure) and provides additional error information.
- When a user scans a PayPics Promotion Tag the delegate URI will be invoked via a HTTP POST request that contains promotion transaction information including:
- ACK – the status of the promotion transaction
- id – the merchant provided ID for the promotion
- consumer – a unique and persistent token that identifies the PayPics user for future transactions
- track – the merchant generated ID that is used to track a user
- info - a series of fields that enumerate the users contact information (name, address, phone, email, etc.)
- datetime – the date and time that the PayPics user scanned the promotion tag
- signature - an HMAC-SHA1 signature that is a hash of the preceeding parameters using the merchant’s OAUTH consumer secret and a null OAUTH token (i.e. the OAUTH secret followed by an “&”). Use the signature to verify that the transaction result is valid and has not been modified.
- IMPORTANT: Your application should validate the transaction information and then respond with an HTTP status code of 200 to indicate a success, or an HTTP status code 204 to indicate a failure. In this way PayPics can notify the user about any error conditions. In addition, the HTTP status description value should be set to an informative message that will be displayed to the PayPics user.
OTHER PAYPICS API OPERATIONS
- PMTREFUND – a signed OAUTH request that will refund the purchase price of a previous payment transaction. This operation accepts one parameter: transactionid which identifies the transaction that should be refunded (transaction ID can be found in your PayPal account). This operation returns the following parameters:
- ACK – set to Success or Failure and indicates whether the operation was successful or not
- transactionid - the txid provided in the request
- refund – set to true if the transaction was successfully refunded, false otherwise
- errormsg – included when an error occurs and provides additional error information
- CHECKPAYMENTSTATUS – a signed OAUTH request that will report the status of a payment transaction. This operation accepts one parameter: txid which identifies the transaction (transaction ID can be found in your PayPal account). This operation returns the following parameters:
- ACK – set to Success or Failure and indicates whether the operation was successful or not
- transactionid - the txid provided in the request
- payment – indicate the status of the payment (paid, refund, unknown, other)
- errormsg – included when an error occurs and provides additional error information
