NAV Navbar
cURL

Introduction

Welcome to the PiP iT Global API! You can use our API to access PiP iT Global API endpoints to carry out requests, payments confirmations etc.

We have a language binding in cURL/Shell and you can view code examples in the dark area to the right.

Create an Order

Example Payload

{
  "vendorName": "PIPDEMOSHOP",
  "vendorOrderReference": "ABC-123",
  "orderCurrencyCode": "EUR",
  "orderValue": 123.58,
  "customerEmail": "foo@terraforma.ie"
}

Example Command

curl -v -H "Content-Type:application/json" -X POST -d'{"vendorName": "PIPDEMOSHOP","vendorOrderReference": "ABC-123","orderCurrencyCode": "EUR","orderValue": 123.58,"customerEmail": "foo@terraforma.ie"}'https://servers.pip-it.net/api/order

Example Response

HTTP/1.1 201 Created
Location: https://servers.pip-it.net/api/order/6377839876703799318
Content-Type:application/json;charset=UTF-8
{
  "barcode": "6377839804432803730",
  "reference": "280373",
  "vendorReference": "ABC-123",
  "orderValue": 123.58,
  "totalValue": 124.82,
  "createdDate": "2015-08-07T10:55:17Z",
  "expiryDate": "2015-08-08T10:55:17Z",
  "status": "PENDING"
}
Name Type Description Required
vendorName string The 'Merchant Username' created at sign up
vendorOrderReference string The vendor's order refernce
orderValue number The value of the order
orderCurrencyCode string The ISO-4217 currency code
customerEmail string The email address of the customer
signature string The SHA-1 signature
customerName string The customer's name
customerMobileNumber string
customerLanguage string
customerAddressLine1 string
customerAddressLine2 string
customerAddressLine3 string
customerAddressLine4 string
customerAddressLine5 string
customerAddressLine6 string
customerCountry string
customerTimezone string
extraInfo string
replyUrl string

Retrieve an Order

Example Command

curl https://servers.pip-it.net/api/order/6377839876703799318

Example Response

HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8
{
  "barcode": "6377839804432803730",
  "reference": "280373",
  "vendorReference": "ABC-123",
  "orderValue": 123.58,
  "totalValue": 124.82,
  "createdDate": "2015-08-07T10:55:17Z",
  "expiryDate": "2015-08-08T10:55:17Z",
  "status": "PENDING"
}

Merchant

Login

Example Command

curl -d 'username=acmetrading&password=donttellanyone' https://servers.pip-it.net/login
curl -c cookies.txt -d 'username=acmetrading&password=donttellanyone' https://servers.pip-it.net/login

Example Response

HTTP/1.1 200 OK
Content-Length: 0
Set-Cookie: JSESSIONID=C089BA3EAD86D257BAA77CABACC7FACC7FAF6; Path=/;HttpOnly
Name Type Required
username string
password string

Logout

Example Command

curl -b cookies.txt -X POST https://servers.pip-it.net/logout

Example Response

HTTP/1.1 200 OK
Content-Length: 0

Registration

Example Payload

{
    "name":"ACME TRADING", 
    "username":"acmetrading", 
    "password":"donttellanyone", 
    "ownerEmailAddress":"john.doe@terraforma.ie"
}

Example Command

curl -v  -H "Content-Type: application/json" -X POST -d '{"name":"ACME TRADING", "username":"acmetrading", "password":"donttellanyone", "ownerEmailAddress":"john.doe@terraforma.ie"}' https://servers.pip-it.net/api/merchant/register

Example Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "code": "MERCHANT_REGISTERED",
    "message": "An email has been sent to your email address.  Please follow the instructions in the email to verify your account.",
    "path": "/api/merchant/register",
    "timestamp": "2015-08-07T12:09:49Z"
}
Name Type Description Required
name string The name of the merchant.
username string The username to use to log in.
password string The password to use to log in.
ownerEmailAddress string The email address of the owner. The registration verification email will be sent to this address.
notificationEmailAddress string Order notifications will be sent to this address. If not specified, this will default to the value of ownerEmailAddress
enableNotificationEmail boolean Should order notification emails be sent? Defaults to true
orderCallbackUrl string The url to use for order callbacks
enableOrderCallbacks boolean Should order callbacks be invoked? Defaults to true if a orderCallbackUrl has been specified
orderExpiryTimeHours number The number of hours before an order expires. Defaults to 72 (3 days)
secretKey string The key used to sign order requests
contactName string The contact person for the merchant
telephoneNumber string The telephone number the contact person can be contacted on
website string The merchant's website
addressLine1 string The address of the merchant
addressLine2 string
addressLine3 string
addressLine4 string
addressLine5 string
addressLine6 string
country string The country that the merchant is located in
timezone string The timezone of the merchant
currencyCode string The default currency code that merchant's orders are placed in
language string

Account Verification

Example Command

curl -X POST https://servers.pip-it.net/api/merchant/verify/NzA1NjczMzMtYzIzNS00NDcxLThiMzctYjQxZTFlMzVhOTcy

Example Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "timestamp":"2015-08-07T12:29:49Z",
    "code":"MERCHANT_VERIFIED",
    "message":"Your account has been verified successfully",
    "path":"/api/merchant/verify/NzA1NjczMzMtYzIzNS00NDcxLThiMzctYjQxZTFlMzVhOTcy"
}

Verification of a merchants account allows the merchant to:

Retrieve a Profile

Example Command

curl -b cookies.txt -v https://servers.pip-it.net/api/merchant/profile

Example Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "notificationEmailAddress": "john.doe@terraforma.ie",
    "orderCallbackUrl": "https://servers.pip-it.net/callback",
    "orderExpiryTimeHours": 24,
    "secretKey": null,
    "website": null
}

Update a Profile

Example Payload

{
    "notificationEmailAddress": "john.doe@terraforma.ie",
    "orderCallbackUrl": "https://servers.pip-it.net/callback",
    "orderExpiryTimeHours": 22,
    "secretKey": "meowmeow",
    "website": null,
    "oldPassword": "myfirstsecret",
    "newPassword": "mycurrentsecret"
}

Example Command

curl -b cookies.txt -H "Content-Type: application/json" -X POST -d '{"notificationEmailAddress": "john.doe@terraforma.ie", "orderCallbackUrl": "https://servers.pip-it.net/callback", "orderExpiryTimeHours": 22, "secretKey": "meowmeow", "website": null, "oldPassword": "**myfirstsecret",  "newPassword": "mycurrentsecret"}' https://servers.pip-it.net/api/merchant/profile

Example Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "code": "PROFILE_UPDATED",
    "message": "Your account has been updated successfully.",
    "path": "/api/merchant/profile",
    "timestamp": "2015-08-07T23:59:19Z"
}

If a parameter is specified (even if it is null) it is assumed that the intent is to update the parameter (possibly to a null value). To leave a parameter unchanged, do not include it in the payload.

Name Type Description
notificationEmailAddress string The notification email address (cannot be specified as null)
orderCallbackUrl string The order callback url
orderExpiryTimeHours string The order expiry time in hours (cannot be specified as null)
secretKey string The secret key
website string The merchant's website address
newPassword string The new password (cannot be specified as null)
oldPassword string The existing password. Required only if newPassword is specified

Requesting a Password Reset Token

Example Payload

{
    "username":"acmetrading"
}

Example Command

curl -H "Content-Type: application/json" -X POST -d '{"username":"acmetrading"}' https://servers.pip-it.net/api/merchant/reset-password-token

Example Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{    
    "code":"MERCHANT_RESET_PASSWORD_TOKEN_GENERATED",
    "message":"An email has been sent to your email address with instructions on how to reset your password.",
    "timestamp":"2015-08-24T19:56:06Z",
    "path":"/api/merchant/reset-password-token"
}

Parameters

Name Type Description Required
username string The merchant's username (used to log in). Not necessarily the same at the merchant's name

Resetting the Password Using the Token

Example Payload

{
    "username":"acmetrading", 
    "token":"ZWI5MThhNGItOTBkZS00ZDI3LTk3ZjYtNTE1ZDA1MGVhMTMw", 
    "password":"p@ssword1"
}

Example Command

curl -v  -H "Content-Type: application/json" -X POST -d '{"username":"acmetrading", "token":"ZWI5MThhNGItOTBkZS00ZDI3LTk3ZjYtNTE1ZDA1MGVhMTMw", "password":"p@ssword1"}' https://servers.pip-it.net/api/merchant/reset-password

Example Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "code":"MERCHANT_RESET_PASSWORD_SUCCESS",
    "message":"Your password has been reset.",
    "timestamp":"2015-08-24T20:10:22Z",
    "path":"/api/merchant/reset-password"
}

Parameters

Name Type Description Required
token string The token
username string The merchant's username (used to log in). Not necessarily the same at the merchant's name
password string The new password

The token that needs to be supplied is sent in an email to the notification address of the merchant's account after successfully requesting a password reset token.

An example email is as follows:

Dear ACME TRADING,

A request to reset your Pip-it password has been received. In order to change your password, please click the following link:
https://servers.pip-it.net/api/merchant/reset-password/ZWI5MThhNGItOTBkZS00ZDI3LTk3ZjYtNTE1ZDA1MGVhMTMw
Please note that this link will expire at 22:09, 25 Aug, 2015

Regards, The Pip-it Team

In this example, the token is: ZWI5MThhNGItOTBkZS00ZDI3LTk3ZjYtNTE1ZDA1MGVhMTMw
Clicking the link in the email will allow you to reset the password using a HTML form. The following sections describe the REST API for performing the same operation.

Retrieve an Order Using a Barcode

Example Command

curl -v -b cookies.txt https://servers.pip-it.net/api/merchant/order/6377839824167832902

Example Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
  "barcode":"6377839824167832902",
  "reference":"783290",
  "vendorReference":"ABC-123",
  "orderValue":123.58,
  "totalValue":124.82,
  "createdDate":"2015-08-07T12:40:12Z",
  "expiryDate":"2015-08-10T12:40:12Z",
  "status":"PENDING"
}

Retrieve Details of an Order Using the Barcode

Example Command

curl -v -b cookies.txt https://servers.pip-it.net/api/merchant/order/6377839862260014614/details

Example Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "barcode": "6377839862260014614",
    "createdDate": "2015-08-07T19:47:28Z",
    "currencyCode": "EUR",
    "customerDetails": {
        "addressLine1": "7 Vancouver Place",
        "addressLine2": "Northcliff",
        "addressLine3": "Extension",
        "addressLine4": "15",
        "addressLine5": "2195",
        "addressLine6": "Gauteng",
        "country": "South Africa",
        "email": "john.doe@terraforma.ie",
        "name": "John Doe",
        "timezone": "SAST"
    },
    "expiryDate": "2015-08-08T19:47:28Z",
    "language": "ENG",
    "orderValue": 621.01,
    "reference": "1461",
    "status": "PENDING",
    "totalValue": 627.22,
    "vendorReference": "ZZ-3722"
}

Find an Order (General Syntax)

The following query parameters may be used to customise the results of any of the find order operations:

Name Type Description
page page=3 Page you want to retrieve, 0 indexed and defaults to 0.
size size=15 Number of results returned per page, defaults to 20.
sort sort=createdDate Properties that should be sorted by in the formatproperty (,ASC|DESC). Default sort direction is ascending. Use multiple sort parameters if you want to switch directions, e.g.sort=createdDate&sort=expiryDate,ascs

The following properties are supported for sorting:

Find Pending Orders

Example Command

curl -b cookies.txt "https://servers.pip-it.net/api/merchant/orders/pending"

Example Response

HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8
{
    "content": [
        {
            "barcode": "6377839815483408088",
            "createdDate": "2015-08-07T07:01:25Z",
            "expiryDate": "2015-08-08T07:01:25Z",
            "orderValue": 1234.0,
            "reference": "340808",
            "status": "PENDING",
            "totalValue": 1246.34,
            "vendorReference": "1234"
        },
        {
            "barcode": "6377839860745768754",
            "createdDate": "2015-08-07T13:24:48Z",
            "expiryDate": "2015-08-08T13:24:48Z",
            "orderValue": 1234.0,
            "reference": "576875",
            "status": "PENDING",
            "totalValue": 1246.34,
            "vendorReference": "1234"
        }
    ],
    "first": true,
    "last": true,
    "number": 0,
    "numberOfElements": 2,
    "size": 20,
    "sort": null
}

Other Examples

Find pending orders sorted by createdDate:

curl -v -b cookies.txt "https://servers.pip-it.net/api/merchant/orders/pending?sort=createdDate"

Find pending orders sorted by createdDate ascending, page size 2 and 3rd page:

curl -v -b cookies.txt "https://servers.pip-it.net/api/merchant/orders/pending?sort=createdDate,asc&size=2&page=3"

Find Expired Orders

Example Command

curl -b cookies.txt "https://servers.pip-it.net/api/merchant/orders/expired"

Example Response

HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8
{
    "content": [
        {
            "barcode": "605002828627001075113012260",
            "createdDate": "2007-11-30T10:16:23Z",
            "expiryDate": "2007-11-30T10:26:37Z",
            "orderValue": 10.0,
            "reference": "828627",
            "status": "EXPIRED",
            "totalValue": 10.75,
            "vendorReference": "1234"
        },
        {
            "barcode": "605002673473013332120413085",
            "createdDate": "2007-12-04T10:57:52Z",
            "expiryDate": "2007-12-04T11:12:02Z",
            "orderValue": 131.32,
            "reference": "673473",
            "status": "EXPIRED",
            "totalValue": 133.32,
            "vendorReference": "order_id"
        }
    ],
    "first": true,
    "last": true,
    "number": 0,
    "numberOfElements": 2,
    "size": 20,
    "sort": null
}

Other Examples

Find expired orders sorted by expiryDate:

curl -b cookies.txt "https://servers.pip-it.net/api/merchant/orders/expired?sort=expiryDate"

Show 5 results per page:

curl -b cookies.txt "https://servers.pip-it.net/api/merchant/orders/expired?size=5"

Sort by expiry date, desc, page size 5 and 3rd page:

curl -b cookies.txt "https://servers.pip-it.net/api/merchant/orders/expired?sort=expiryDate,desc&size=5&page=3"

Find Paid Orders

Example Command

curl -b cookies.txt "https://servers.pip-it.net/api/merchant/orders/paid"

Example Response

HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8
{
    "content": [
        {
            "barcode": "605002062654016668031412380",
            "createdDate": "2008-03-14T10:28:16Z",
            "expiryDate": "2008-03-14T10:38:28Z",
            "orderValue": 164.43,
            "paymentDate": "2008-03-14T10:29:00Z",
            "reference": "62654",
            "status": "PAID",
            "totalValue": 166.68,
            "vendorReference": "order_id"
        },
...
        {
            "barcode": "6377839896340627813",
            "createdDate": "2015-08-05T09:19:26Z",
            "expiryDate": "2015-08-06T09:19:26Z",
            "orderValue": 1234.0,
            "reference": "62781",
            "status": "PAID",
            "totalValue": 1246.34,
            "vendorReference": "1234"
        }
    ],
    "first": true,
    "last": false,
    "number": 0,
    "numberOfElements": 20,
    "size": 20,
    "sort": null
}

Pay an Order

Example Command

curl -b cookies.txt -X POST https://servers.pip-it.net/api/merchant/order/6377839862388449031/pay

Example Response

HTTP/1.1 200 OK
Content-Type:application/json;charset=UTF-8
{
    "timestamp":"2015-08-07T20:43:12Z",
    "code":"PAYMENT_SUCCESSFUL",
    "message":"Payment for the order has been recorded.",
    "path":"/api/merchant/order/6377839862388449031/pay"
}

Notes - Callbacks

Merchant Callbacks

If Pipit Global is providing live payment information (as opposed to in a batch process) to a merchant then merchants are able to enable live callbacks from Pipit Global to their own system. Callbacks are enabled via the 'callback' (Y or N) and 'callback_url' fields in their merchant profile.

Callbacks are done only once per status change so they can be reconciled with the order status lists from the RESTApi as defined previously if the merchant’s server was unable to received the callbacks at some stage during the day.

Order creation, payment and expiry are notified via the callback.

Payment Received

When a payment is received on the Pip-it system then a callback message is generated to the merchant’s servers using the Callback_URL provided by the merchant and set in their account profile (also the callbacks = 'Y' field must be set).

The POST request will contain the following fields:

▪ BARCODE The Pip-it barcode is for the newly paid Order.
▪ VENDOR_ORDER_ID The transaction id for the order used by the merchant. The merchant will use this id to identify the order on their own system.
▪ PAID_DATE The date and time the Order was paid in the format 'YYYMMDDHHMISS'. e.g. 20131114103000
▪ SIGN The Sha-2 hash for the message (Optional).

The Internet Merchant can identify this callback as a paid order callback because it contains the PAID_DATE field.

For example, in the case of a merchant providing ‘http://www.myshop.com/pip-itcallback’ as the callback URL and the barcode being

'605002264492001076102918376' then the http POST would be:

http://www.myshop.com/pip- itcallback?BARCODE=605002264492001076102918376&VENDOR_ORDER_ID=123456789&PAID_DATE=201 31114103000

This Payment message would be received on the merchant’s server and then the goods will be dispatched by the merchant to the customer.

If the merchant has set the 'Secret Key' parameter, then this message will also be signed using a Sha-2 hash in a similar fashion as for the new order message described earlier.

For the basic example we used above, this can be worked out as so (where “secret” is the secret key in this case): cleartext = ”60500226449200107610291837612345678920131114103000secret”; sha-2(cleartext) = e9798b09e37edef38f16a021c5b12ca41ad837e2;

This would then give the following URL:

http://www.myshop.com/pip- itpaymentreceived?BARCODE=605002264492001076102918376&VENDOR_ORDER_ID=123456789&PAID_D ATE=20131114103000&SIGN=e9798b09e37edef38f16a021c5b12ca41ad837e2

The merchant’s servers would then be expected to check the SIGN field to ensure that the message had indeed come from the Pip-it servers.

Order Created

There is also an order created callback. It has the same format as above but with CREATE_DATE substituting for PAID_DATE. It is activated when an order is created.

Order Expired

There is also an order expired callback. It has the same format as above but with EXPIRE_DATE substituting for PAID_DATE. It is activated when an order expires.