NAV Navbar
Partpay logo 625x135

Introduction

Welcome to the PartPay Developer documentation. Here you will find documentation for integrating PartPay as a payment option onto your e-commerce site, as well as a number of helpful marketing widgets.

Authentication

E.g. To obtain an access token:

curl -X POST \
  https://partpay.au.auth0.com/oauth/token \
  -H 'content-type: application/json' \
  -d '{
  "client_id":"[client id]",
  "client_secret":"[client secret]", 
  "audience":"https://auth.partpay.co.nz",
  "grant_type":"client_credentials"
}'

Example response

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciO.....",
    "expires_in": 86400,
    "scope": "read:me merchant",
    "token_type": "Bearer"
}

PartPay uses OAuth2 Client Credentials Flow as the primary means for authorising requests when interacting with the Merchant API

This is a multiple step process, in that the client must obtain an access token via the OAuth token endpoint, and then use this bearer token to access the PartPay API endpoints.

Authorisation Endpoints

  Sandbox Production
Token Endpoint https://partpay-dev.au.auth0.com/oauth/token https://partpay.au.auth0.com/oauth/token
Audience https://auth-dev.partpay.co.nz https://auth.partpay.co.nz

Client Id & Secret

These will be issued to you from the PartPay support team.

Merchant API

Base Urls

Sandbox

https://api-ci.partpay.co.nz/

Production

https://api.partpay.co.nz/

Payment Flow

TODO: Image

Each of these steps is described in more detail below:

  1. User selects PartPay This is typically offered as a payment option for users when they are at the stage of checkout on the merchant site.
  2. Merchant Server POSTs to PartPay API The merchant server creates an API call to the PartPay ‘Create Order’ endpoint. This contains:
  3. Customer details (email, name, phone number)
  4. Order details (what the customer is purchasing from the merchant site)
  5. Billing and Shipping addresses
  6. Amount (plus optional information regarding discounts / shipping / tax)
  7. RedirectUrl - this is a merchant hosted URL, to return the customer to once they have completed the PartPay process.
  8. PartPay API returns a token and a Redirect URL The PartPay API returns a unique token for the order and the URL to redirect the user to.
  9. Redirect User to PartPay payment page Redirect the user to the URL returned in step 3 from the API
  10. (As above)
  11. User Completes Payment Steps at PartPay User completes their payment information on partpay site. This will result in a user being able to pay via PartPay or not.
  12. User is returned to the Merchant page when complete Once user has completed the PartPay process, they are redirected to the Merchant page. When the user is returned back to the merchant page, the URL will have the following parameters appended to the URL:
  13. paymentStatus indicates the status of the payment. Possible values are:
    • success : Payment via PartPay completed.
    • failure : Payment not taken - PartPay service not offered, or payment declined.
    • cancelled : User cancelled out of PartPay process and returned to merchant site.
  14. orderId used to uniquely identify the order
  15. (Optional) Merchant Server queries PartPay API for order information This can be used to reconcile any orders that have started, but users have not returned to the merchant site, for whatever reason.
  16. As Above
  17. Merchant site reconciles payment On receipt of a payment status (successful or otherwise), it is expected the merchant server will reconcile the order status.

Testing

In the sandbox environment, we allow simulation of a number of scenarios with the following test cases.

AML / Credit Scenarios

Scenario Full Name DOB Address D/L D/L Version
Pass Credit / AML (anything) (any DOB over 18 yo) (any valid address) AB123456 111
Fail AML (anything) (any DOB over 18 yo) (any valid address) FA123456 111
Fail Credit (anything) (any DOB over 18 yo) (any valid address) AB000012 111

Payment Scenarios

To test a successful payment, you will need to use: 4111111111111111 as the card no, any (future dated expiry) and any CVV. If you want to test a failing payment, set the order amount to $87.04

Emails

We do not send out emails from the sandbox enviornment, but if you would like accounts activated (so you can login with user/pass each time) then please contact PartPay tech support to enable this.

Phone Numbers / SMS

We do not send out SMS’s from the sandbox environment. In order to complete a signup process, enter and valid NZ phone number. When prompted to input the SMS verification code, use 999999.

Configuration

Get Configuration

Code sample

curl -X get https://api.partpay.co.nz/configuration 
  -H 'Accept: application/json' 
  -H 'Authorization: Bearer [access_token]

Endpoint

GET https://api.partpay.co.nz/configuration

Request Parameters

(none)

Response Values

Example Response

{
  "minimumAmount": 50,
  "maximumAmount": 950
}
Field Type Description
minimumAmount integer Minimum order amount
maximumAmount integer Maximum order amount

Response Codes

Code Reason
200 OK
401 Unauthorized

Order

Create Order

Code sample

curl -X post https://api.partpay.co.nz/order
  -H 'content-type: application/json' 
  -H 'authorization: Bearer [access_token]'
  -d '{
  "amount": 105.00,
  "consumer": {
    "phoneNumber": "64274123456",
    "givenNames": "James",
    "surname": "Smith",
    "email": "abc123.test@partpay.co.nz"
  },
  "billing": {
    "addressLine1": "23 Duncan Tce",
    "addressLine2": "",
    "suburb": "Kilbirnie",
    "city": "Wellilngton",
    "postcode": "1000",
    "state": ""
  },
  "shipping": {
    "addressLine1": "23 Duncan Tce",
    "addressLine2": "",
    "suburb": "Kilbirnie",
    "city": "Wellilngton",
    "postcode": "1000",
    "state": ""
  },
  "description": "",
  "items": [
    {
      "description": "test",
      "name": "test",
      "sku": "test",
      "quantity": 1,
      "price": 100.00
    }
  ],
  "merchant": {
    "redirectConfirmUrl": "http://merchantsite.com/confirm",
    "redirectCancelUrl": "http://merchantsite.com/cancel"
  },
  "merchantReference": "test",
  "taxAmount": 0,
  "shippingAmount": 5
}'

Endpoint

POST https://api.partpay.co.nz/order

Request Parameters

Field Type Description
amount number Amount for order to be charged to consumer.
consumer
    phoneNumber string optional
    givenNames string optional
    surname string optional
    email string optional
billing
    addressLine1 string optional
    addressLine2 string optional
    suburb string optional
    city string optional
    postcode string optional
    state string optional
shipping
    addressLine1 string optional
    addressLine2 string optional
    suburb string optional
    city string optional
    postcode string optional
    state string optional
description string optional A description of the order
items array (below) optional Optional but recommended array of order items. Customers will be able to view this on the PartPay customer portal.
    description string optional
    name string optional
    sku string optional
    quantity integer optional
    price number optional
merchant
    redirectConfirmUrl string required successful transactions redirect url
    redirectCancelUrl string required failed or cancelled transactions redirect url
merchantReference string required The merchant’s id/reference that this order corresponds to
taxAmount number optional The included tax amount after applying all discounts. ,
shippingAmount number optional The shipping amount.
productType string optional The product type (“classic” or “plus”). Defaults to “classic”.

Response

Example Response

{
    "token": "00fbfe84-600f-44e6-9894-953ccd42a2d1",
    "expiryDateTime": "2017-08-02T03:35:32.9915516Z",
    "redirectUrl": "https://checkout.partpay.co.nz/checkout?token=00fbfe84...",
    "orderId": "0f3c0875-000c-4c6f-a215-cf355cd7e600"
}

Example Response with warnings

{
    "token": "00fbfe84-600f-44e6-9894-953ccd42a2d1",
    "expiryDateTime": "2017-08-02T03:35:32.9915516Z",
    "redirectUrl": "https://checkout.partpay.co.nz/checkout?token=00fbfe84...",
    "orderId": "0f3c0875-000c-4c6f-a215-cf355cd7e600",
    "warnings": [
        "Order.Amount rounded 123.20555 to 123.21"
    ]
}
Field Type Description
token string The order token. A temporary token for an in-flight order. Expires in 1h
expiryDateTime dateTime The time (utc) the token expires
redirectUrl string The URL to redirect the user to, in order to complete the PartPay payment process
orderId string The durable order token, use to poll order status from PartPay GET /order operation
warnings string[] Only present if there are warnings with data passed to the create the order.

Response Codes

Code Reason
200 OK
400 The request is malformed
401 Unauthorised

Get Order

Request Sample

curl -X get https://api.partpay.co.nz/order/0f3c0875-000c-4c6f-a215-cf355cd7e600\
  -H 'Accept: application/json'\
  -H 'Authorization: Bearer [access_token]'

Endpoint

GET https://api.partpay.co.nz/order/{orderId}

Request Parameters

Field Type Description
orderid string (required) order id when creating the order during the Create Order step

Response

Example Response

{
    "orderId": "8eb068f..",
    "orderNumber": "180518-902291P",
    "orderStatus": "Created",
    "amount": 105,
    "consumer": null,
    "billing": {
        "addressLine1": "23 Duncan Tce",
        "addressLine2": "",
        "suburb": "Kilbirnie",
        "city": "",
        "postcode": "1000",
        "state": null
    },
    "shipping": {
        "addressLine1": "23 Duncan Tce",
        "addressLine2": "",
        "suburb": "Kilbirnie",
        "city": "",
        "postcode": "1000",
        "state": null
    },
    "description": null,
    "items": [
        {
            "description": null,
            "name": "test",
            "sku": "test",
            "quantity": 1,
            "price": 100
        }
    ],
    "merchant": {
        "redirectConfirmUrl": null,
        "redirectCancelUrl": null
    },
    "merchantReference": "test",
    "taxAmount": 10,
    "shippingAmount": 5,
    "token": "1eea52..."
}
Field Type Description
amount number Amount for order to be charged to consumer.
orderId string A unique reference for the order. This value will need to be persisted onto the client side, for the purposes of refunds
orderNumber string Identifies an order but smaller and more readable than the OrderId.
orderStatus string A status representing the status of an order on PartPay.
Created: The order has been created on PartPay, but not yet completed.
Approved: Payment has been successfuly taken/approved on PartPay.
Declined: The the payment process on PartPay was not successful
Abandoned: User abandoned PartPay process before first payment is taken. Orders will tranisition to this state after a maximum of one hour.
consumer
    phoneNumber string optional
    givenNames string optional
    surname string optional
    email string optional
billing
    addressLine1 string optional
    addressLine2 string optional
    suburb string optional
    city string optional
    postcode string optional
    state string optional
shipping
    addressLine1 string optional
    addressLine2 string optional
    suburb string optional
    city string optional
    postcode string optional
    state string optional
description string optional A description of the order
items array (below) optional Optional array of order items
    description string optional
    name string optional
    sku string optional
    quantity integer optional
    price number optional
merchant
    redirectConfirmUrl string required
    redirectCancelUrl string required
merchantReference string required The merchant’s id/reference that this order corresponds to
taxAmount number optional The included tax amount after applying all discounts. ,
shippingAmount number optional The shipping amount.

Response Codes

Code Reason
200 OK
400 The request is malformed
401 Unauthorised
404 Order is not found

Get Order by Token

Request Sample

curl -X get https://api.partpay.co.nz/order/?token=string\
  -H 'Accept: application/json'\
  -H 'Authorization: Bearer [access_token]'

This legacy method returns the same data as GET /order, however it may fail as soon as the token has expired (approximately 1 hour).

Endpoint

GET https://api.partpay.co.nz/order/?token={token}

Request Parameters

Field Type Description
token string (required) order token when creating the order during the Create Order step

Refund

Example Request

curl -X post https://api.partpay.co.nz/order/{orderId}/refund \
  -H 'Content-Type: application/json'
  -H 'authorization: Bearer [access_token]'
  -d '{
    "requestId": "c6f32647-03b1-4206-818f-c2e2fe8ae7f8",
    "amount": 1,
    "merchantRefundReference": "c6f32647-03b1-4206-818f-c2e2fe8ae7f8"
    }'

The resource is idempotent if a unique requestId is provided.

Endpoint

POST https://api.partpay.co.nz/order/{orderId}/refund

orderId is the orderId returned from the Get Order operation

Request Parameters

Field Type Description
requestId string optional A client created unique request ID required for safe retries. It is recommended that the client generate a GUID as this ID must be globally unique to the merchant
amount number required The refund amount. The refund amount can not exceed the associated order
merchantRefundReference string required Merchant refund reference.

Response Body

N/A

Response Codes

Code Reason
200 OK
400 The request is malformed
401 Unauthorised
404 Order Not found
422 A 422 occurs when the request was well formed, but the system is unable to process the request. Scenarios:
The sum of all refunds, including the new refund, exceed the (original) order amount. OR
The refund with merchantRefundReference has already been applied. OR
The refund request is otherwise invalid.
e.g. merchantRefundReference is required OR the refund amount is invalid OR the order was never completed and is not eligible for a refund

Update Merchant Reference

Example Request

curl -X PUT 
  https://api.partpay.co.nz/order/{orderId}/merchantReference
  -H 'authorization: Bearer [access_token]' 
  -H 'content-type: application/json' 
  -d '{
        "merchantReference": "03942300934"
    }'

This endpoint allows an order have it’s merchantReference changed after the order has been accepted and payment taken via PartPay.

Endpoint

PUT https://api.partpay.co.nz/order/{orderId}/merchantReference

orderId is the orderId returned from the Get Order operation

Request Parameters

Field Type Description
merchantReference New merchant reference for the order

Response Body

N/A

Response Codes

Code Reason
200 OK
401 Unauthorised
404 Order Not found

Lightbox Checkout

The lightbox checkout allows a more seamless experience at the checkout stage. Rather than being redirected to PartPay, it allows the PartPay checkout process to be loaded in a lightbox within the merchant site.

Mobile Devices

NB: Mobile devices are not supported for this experience, given the limited screen size, but the lightbox will detect the device used, and will redirect users who are on a mobile device.

Script

Example <script> head tag

    <head>
        <script src="https://checkout.partpay.co.nz/assets/sandbox/partpay-sandbox-v1.js"></script>
    </head>

Example dynamically loading script:

    function appendSandboxScript() {
        var el = document.createElement("script");
        el.setAttribute("src", "https://checkout.partpay.co.nz/assets/sandbox/partpay-sandbox-v1.js");
        document.getElementsByTagName("head")[0].appendChild(el);
    }

There are 2 options to load the script onto the page, either by adding a <script> element to their checkout page <head>, OR dynamically add the script element when the CHECKOUT button has been clicked:

Flow

Example PartPay intitialisation

    // CHECKOUT button clicked.
    // Initiate the partpay checkout.
    PartPay.checkout({
        orderToken: token, // <--- token is the returned when creating an order.
        success: function () {
            // TODO: Handle a successful checkout.
            alert("Success");
        },
        cancel: function () {
            // TODO: Handle a cancelled checkout.
            alert("Cancelled");
        }
    });

Merchant should POST to https://checkout.partpay.co.nz/order as stipulated in the POST /order endpoint, to create an order. The response will include the token to be used with the checkout process.

When the customer clicks the CHECKOUT button activate the PartPay checkout with the PartPay javascript object:

Embedded Checkout

An embedded checkout allows the PartPay checkout to be hosted within an iframe on the merchant’s web site, rather than being redirected to PartPay.

iframe src attribute

After creating an order via the PartPay Merchant API append &embedded=true to the redirect url and set the src attribute of the iframe to the url

Example iframe element:

    <iframe src="https://checkout.partpay.co.nz?token=ae59b28b-81dc-40de-b51a-e915ed87b381&embedded=true" style="width:600px;height:700px"></iframe>

NOTE: You will have to detect changes to the src attribute to detect when the checkout process has been completed.

Widgets

PartPay offers merchants a number of helpful & informative widgets, which display more information about the product to site customers. The widgets are really easy to load onto the relevant pages, and should be able to completed by most merchant site admins.

If you are having any issues implementing these on your site, please contact support@partpay.co.nz

PartPayPlus Info Widget

The PartPayPlus Info Widget is used to explain details of the PartPayPlus product to a potential client. It is useful on, for example, a checkout page.

Usage

...
<head>
  ...
  <script src="https://cdnjs.cloudflare.com/ajax/libs/webcomponentsjs/1.0.22/webcomponents-loader.js"></script>
  <link rel="import" href="https://widgets.partpay.co.nz/pp-info.html">
  ...
</head>
<body>
  ...
  <pp-info></pp-info>
  ...
</body>

The PartPay Plus Info Widget is built using Web Components. Depending on the browser versions you plan to support, you will need to add a polyfill include. It is recommended you use the polyfill unless you only support modern browsers, or you happen to use the polymer framework (which includes a polyfill by default).

Sizes

The Info Widget‘s width size can be controlled by wrapping the <pp-info> tag inside of a div tag, and then setting using that div’s width. The Info Widget is designed to be responsive so it should resize properly for screen sizes that are 320px or greater.

PartPay Calculator Widget

...
<head>
  ...
  <script src="https://cdnjs.cloudflare.com/ajax/libs/webcomponentsjs/1.0.22/webcomponents-loader.js"></script>
  <link rel="import" href="https://widgets.partpay.co.nz/pp-calculator.html">
  ...
</head>
<body>
  ...
  <pp-calculator min="30" max="400" amount="39.59"></pp-calculator>
  ...
</body>

The PartPay Calculator widget is used to display the installment payments for PartPay. Similar to the PartPay Plus Info Widget, this widget uses Web Components and will likely require a polyfill (see example usage below).

Additionally, this widget takes a number of parameters which are used to control the installment display.

Parameters

The calculator widget can take three parameters:

Name Description
min Your minimum PartPay amount
max Your maximum PartPay amount
amount The order or cart amount

Usage

Here is an example using an amount of $39.59:

<pp-calculator min="30" max="400" amount="939.59"></pp-calculator>

Here is an example of giving an amount that is beyond the max amount:

<pp-calculator min="30" max="400" amount="5.59"></pp-calculator>

And lastly, and example of giving an amount that is below the minimum amount:

Sizes

The Calculator Widget’s width size can be controlled by wrapping the <pp-calculator> tag inside of a div tag, and then setting using that div’s width. The Info Widget is designed to be responsive so for screen sizes that are 320px or greater.

Legacy Calculator / More Info

Example script tag

<script async src="https://widgets.partpay.co.nz/your-merchant-name/partpay-widget-0.1.0.js?type=calculator&min=50&max=400&amount=300" type="application/javascript"></script>

Simply insert a <script> tag, as defined below, onto the part of the page that is the right place for this to be displayed.

Base Url : https://widgets.partpay.co.nz/your-merchant-name/partpay-widget-0.1.0.js?type=calculator

Parameters

Name Description
min Your minimum PartPay amount
max Your maximum PartPay amount
amount The order or cart amount

Demo

(*item / cart worth $300)

Get Installments

Request Sample

curl -X get https://api.partpay.co.nz/order/calculate-installments?amount=87.02 \
  -H 'Accept: application/json'

Endpoint

GET https://api.partpay.co.nz/order/calculate-installments

URL Query Parameters

Field Type Description
amount decimal (required) amount to be queried, either the product or basket size, depending on the context from where it is being called.

Response

Example Response

{
    "amount" : 87.02,
    "installments" : [
        {
            "sequence" : 0,
            "amount": 21.75,
            "date": "2017-11-03"
        },
         {
            "sequence" : 1,
            "amount": 21.75,
            "date": "2017-11-17"
        },
        {
            "sequence" : 2,
            "amount": 21.76,
            "date": "2017-12-01"
        },
        {
            "sequence" : 3,
            "amount": 21.76,
            "date": "2017-15-01"
        }
    ]
}
Field Type Description
amount number Queried amount value
installments
sequence number Sequence of the installment (i.e. 0 = first installment)
amount decimal Amount due for the installment
date date Date of the installment (ISO8601 format), shown in NZST

Shopify

When using this widget in Shopify, you can pass the following values for the amount parameters.

Shopify Parameters

Shopify Page Value
Cart {{ cart.total_price | divided_by: 100.0 }}
Product {{ current_variant.price | divided_by: 100.0 }}

i.e. <script async src="https://widgets.partpay.co.nz/partpay-widget-0.1.0.js?type=calculator&min=50&max=400&amount={{ current_variant.price | divided_by: 100.0 }}" type="application/javascript"></script>

WooCommerce

When using this widget on WooCommerce, you can pass the following values for the amount parameters.

WooCommerce Parameters

WooCommerce Page Value
Cart WC()->cart->cart_contents_total;
Product WC()->product-> get_price();

i.e (product page). <script async src="https://widgets.partpay.co.nz/partpay-widget-0.1.0.js?type=calculator&min=50&max=400&amount=<?php echo $product->get_price(); ?>" type="application/javascript"></script>

In-Store API

PartPay offers an in-store process, whereby customers are able to pre-request credit, and complete the payment of the order at the point of sale, in a seamless manner.

Base Urls

Sandbox

https://sandbox.partpay.co.nz/

Production

https://api.partpay.co.nz/

Authentication

Authentication is one by the obtaining of a bearer token, by posting a client_id and a client_secret to the token endpoint. Given these values are particularly long and cumbersome to input to a POS terminal, we offer the ability to have an interactive enrolment process whereby a retailer is able to enrol their terminal from the Merchant Portal.

Enrolment

Once the merchant has signed up for the In-Store api, the Point of Sale terminal can download client credentials using the enrol endpoint.

Enrollment is a 2-step process initiated via the Merchant Portal.

  1. Obtain Activation Code From Merchant Portal
  2. Enrol the device and receive credentials

Enrolment Step 1 - Obtain Activation Code From Merchant Portal

Before attempting authorization, please ensure you are logged into the Merchant Portal.

  1. Go to the Terminal Enrolment section in the Merchant portal ie. /instore/terminal-enrollment
  2. Enter in required fields
    • Terminal Name (A human readable)
    • Secret (min 5 characters)
  3. Click the [Add] link.

This will create a short, time-limited code like A5B1D2.

Enrolment Step 2 - Enrol your POS Terminal

The enrol endpoint is primarily a way to use a one-time code to easily download the client credentials for your Point of Sale terminal to enable it to use the In-Store Api. This has been designed for Point of Sale terminals that have limited configuration abilities.

Enrol Request

curl -X POST "https://api.partpay.co.nz/pos/terminal/enrol" \
    -H 'content-type: application/json' \
    -d '{
            "activationCode" : "A5B1D2",
            "secret" : "SN@9#*74",
            "terminal": "LV7-4414-XXXX-1"
        }'

Enrol Response (200 OK)

{
    "client_id": "a PartPay generated id",
    "client_secret": "a PartPay generated secret"
}

Enrol Response (400 Bad Request)

{
  "errorCode": "InvalidActivationCode",
  "message": "The request is invalid.",
  "isValid": false,
  "errors": []
}

POST https://api.partpay.co.nz/pos/terminal/enrol

Field Type Description
activationCode string required The activation code provided from the Merchant Portal
secret string required The one-time secret, that you used on the Merchant Portal
terminal string required The unique name of the terminal
Response Description
200 OK Enrollment was successful
400 Bad Request The error code InvalidActivationCode covers all of: missing, expired, or incorrect Activation Code, or the secret is incorrect.

POS Terminal Authentication

Authenticate the Point of Sale Terminal

curl -X POST "https://partpay.au.auth0.com/oauth/token" \
    -H 'content-type: application/json' \
    -d '{
            "grant_type" : "client_credentials",
            "client_id" : "{your enrol client id}",
            "client_secret" : "{your enrol client secret}",
            "audience" : "https://auth.partpay.co.nz"
        }'

Sample Response (200 OK)

{
    "token_type" : "Bearer",
    "expires_in" : "43200",
    "access_token" : "{a JWT signed by the Auth0 Authorization server}"
}

Sample Error Response - (403 Forbidden) client_id used is not set up for In-Store

{
  "error": "access_denied",
  "error_description": "Client has not been granted scopes: point_of_sale"
}

Sample Error Response - (500 Error) missing or empty ‘state’

{
  "error": "server_error",
  "error_description": "PointOfSaleRequiresState - Point Of Sale requires the 'state' to be set."
}

Authentication is a client credentials grant.

Field Type Description
grant_type string required This is always client_credentials
client_id string required The enrol client identifier provided
client_secret string required The enrol client secret provided
audience string required PartPay Api

Flow

A typical in-store order flow with PartPay is a 2-step process.

  1. The customer requests a pre-approval code via their phone.
  2. At the point of sale, the pre-approval code is entered when PartPay is selected as a payment method. The merchant terminal then creates the order (with some order metadata), along with a uniquely identifiable token, which the customer will present at the time of checkout. See more in Create Order
  3. The customer is presented an option to confirm or cancel the transaction on their device.
  4. The merchant terminal will poll PartPay to enquire if this order has been confirmed by the customer. See more in Order Status

The below diagram shows the typical 2-step flow for a POS integration with PartPay.

POS-Flow

Create Order

Code sample

curl -X POST https://api.partpay.co.nz/pos/order
  -H 'content-type: application/json' 
  -H 'authorization: Bearer [access_token]'
  -H 'partpay-terminalid: ABC123456'
  -d '{
        "customerApprovalCode" : "A5B312",
        "operator" : "Frank",
        "amount": 105.00,
        "merchantReference": "abc12345",
        "items": [
            {
            "description": "test",
            "name": "test",
            "sku": "test",
            "quantity": 1,
            "price": 100.00
            }
        ]
    }'

Endpoint

POST https://api.partpay.co.nz/pos/order

Request Headers

Field Type Description
partpay-terminalid string required A required header that unqiuely identifies the Point of sale terminal being used as part of this request.

Request Parameters

Field Type Description
customerApprovalCode string required Unique 6-character approval code that the customer will have as part of their pre-approval from PartPay.
operator string required Current Point of Sale terminal operator.
amount number Amount to be charged to consumer.
merchantReference string required The merchant’s id/reference that this order corresponds to.
items array (below) optional Optional array of order items
    description string optional
    name string optional
    sku string optional
    quantity integer optional
    price number optional

Response

Example Response

{
    "orderId": "00fbfe84-600f-44e6-9894-953ccd42a2d1",
}
Field Type Description
orderId string The unqiue reference ID for this order within PartPay. This will need to be used as a parameter in the Order Status endpoint.

Response Codes

Code Reason
201 Created. The order is created, and is now pending the customer’s authorisation. Your system should now poll the Order Status endpoint for this information. The header Operation-Location will be set to the status endpoint.
400 The request is malformed
401 Unauthorised
403 Forbidden. See Error Code Table
404 Not Found. This represents the supplied approval code is not found, or the approval code has timed out.

Error Codes

To see how errors are returned, see the Errors section.

Error Code Meaning
BelowMinimumOrderAmount Amount is below the minimum amount offered at the time.
AboveMaximumPreApprovalAmount Amount is above the amount the user is pre-approved for.

Order Status

Code sample

curl -X GET https://api.partpay.co.nz/pos/order/00fbfe84-600f-44e6-9894-953ccd42a2d1/status 
  -H 'content-type: application/json' 
  -H 'authorization: Bearer [access_token]'

Endpoint

GET https://api.partpay.co.nz/pos/order/{id}/status

Request Parameters

Field Type Description
id string required OrderId returned from Create Order endpoint.

Response

Sample Response (200 OK)

{
  "orderId": "3c83ccc7-ae30-45df-abcd-74b163011694",
  "orderNumber": "180518-902291P",
  "orderStatus": 1,
  "amount": 464.99,
  "items": [
    {
      "description": "test",
      "name": "test",
      "sku": "test",
      "quantity": 1,
      "price": 100.00
    }
  ],
  "taxAmount": null,
  "createdDateTime": "2018-05-17 22:15:52Z"
}
Field Type Description
orderId string The unqiue reference ID for this order within PartPay. This will need to be used as a parameter in the Order Status endpoint.
orderNumber string Identifies an order but smaller and more readable than the OrderId.
orderStatus string The order status from a payment perspective, 0 - Created, 1 - Approved, 2 - Declined, 3 - Abandoned.
amount number The amount to be charged to consumer.
items array An array of order items.
taxAmount number The included tax amount after applying all discounts.

Response Codes

Code Reason
200 OK. Payment for this order has completed and the order can be completed from the merchant side. The Location header will also be supplied.
202 Accepted. The order has been accepted, and is pending the customer’s authorisation to complete the order. Continue to re-query this endpoint until the order is complete (200), or abandoned (410).
401 Unauthorised
404 Order not found.
410 Gone. This represents the order has been abandoned by the customer. The payment has not been completed for this order.

Cancel Order

Cancel Order Request

curl -X POST "https://api.partpay.co.nz/pos/order/cancel" \
    -H 'content-type: application/json' \
    -H 'partpay-terminalid: ABC1234' \
    -d '{
            "operator" : "Sally",
            "cancelOrderId" : "{your order id}"
        }'

Sample Response (200 OK)

{
    "orderId" : "{your order id}"
}

Sample Error Response (409 Conflict)

{
    "errorCode" : "Bearer",
    "message" : "the order has already been processed"
}

Endpoint

POST https://api.partpay.co.nz/pos/order/cancel

If a customer is unable to perform the customer approval step for any reason, the merchant may cancel the order from the Point of Sale terminal.

Request Headers

Field Type Description
partpay-terminalid string required A required header that unqiuely identifies the Point of sale terminal being used as part of this request.

Request Parameters

Field Type Description
cancelOrderId string required OrderId returned from Create Order endpoint.
operator string required Current Point of Sale terminal operator.

Response Parameters

Field Type Description
orderId string The cancelled order id.

Response Codes

Code Reason
200 OK. The order has been cancelled.
409 Conflict. Cancelling has failed because the order has already succeeded.
401 Unauthorised
404 Order not found.

Refund

Point of Sale Refund Request

curl -X POST "https://api.partpay.co.nz/pos/order/00fbfe84-600f-44e6-9894-953ccd42a2d1/refund" \
    -H 'content-type: application/json' \
    -H 'partpay-terminalid: ABC123456' \
    -d '{
            "operator" : "Sally",
            "amount" : 1.99,
            "merchantRefundReference": "dress incorrect size"
        }'

Sample Response (200 OK)

{
    "id" : "{refund id}",
    "refundedDateTime" : "2017-09-13T03:56:15.3353813Z",
    "merchantReference" : "dress incorrect size",
    "amount" : 1.99
}

Sample Error Response (422 Preconditions failed)

Refund of $999.00 is greater than available refund amount of $121.43

Endpoint

POST https://api.partpay.co.nz/pos/order/{orderId}/refund

Refunding from a Point of Sale terminal is identical to the normal refund api except for the capturing the additional information of terminal and operator.

Request Headers

Field Type Description
partpay-terminalid string required A required header that unqiuely identifies the Point of sale terminal being used as part of this request.

Request Parameters

Field Type Description
orderId string required OrderId returned from Create Order endpoint. Located in the endpoint path.
operator string required Current Point of Sale terminal operator.
amount number required A decimal value to 2 decimal places that indicates the amount to refund
merchantRefundReference string required Your reference for this refund.

Response Parameters

Field Type Description
id string A refund id generated by the system.
refundedDateTime string The UTC timestamp when the refund was processed.
merchantReference string Your reference for this refund.
amount number The amount refunded.

Response Codes

Code Reason
200 OK. The order was refunded.
422 Preconditions failed. A text error response provided.
401 Unauthorised
404 Order not found.

In-Store Testing

To enable 3rd parties the ability to test their integrations with PartPay, we provide some test enpoints to simulate the customer action as part of this process. We also provide a couple of scenarios by sending a set of pre-defined approval codes.

Test Scenarios

We allow the use of a number of request values in order to simulate various responses from the endpoints. NB: these scenarios only work within the sandbox environment.

Create Order Test Scenarios

Use the following values for the pre-approval codes:

Value Scenario
AA00 - AA99 Valid pre-approval code (order will automatically be marked as complete after creation during the Order Status, and return a 200). 00 - 99 is the delay, in seconds, before the order will complete.
CA00 - CA99 Valid pre-approval code, which will return a 410 status code in the Order Status endpoint. 00 - 99 is the delay, in seconds, before the order will decline.
AM00 Returns error code AboveMaximumPreApprovalAmount (see Error Codes)
BM00 Returns error code BelowMinimumOrderAmount (see Error Codes)
(any other 4 digit value) Will return a 404 status code at the Create Order stage
(any valid 6 digit value) Use of any valid code for the environment will work accordingly.

Create Refund Test Scenarios

In this case you can post any value to the orderId component of the request URL (https://api.partpay.co.nz/pos/order/{orderId}/refund). Use the following values for the merchantRefundReference property in your request body:

Value Scenario
RT01 Returns 200 OK for a successful refund
RE01 Returns a 429 response code signalling the requested refund amount is greater than the value of the order
NF01 Returns a 404 Not found response code signalling the order is not found

Errors

Error codes are returned in the following format:

Basic Errors

Basic Error Response

{
  "message": "The request is invalid",
  "isValid": false,
  "errors": []
}

The most basic error has a message and an indication that the request was invalid.

Errors with Error Codes

Error Response with Error Code

400 Bad Request

PartPay-Error: AboveMaximumPreApprovalAmount

{
  "errorCode": "AboveMaximumPreApprovalAmount",
  "message": "The request is invalid",
  "isValid": false,
  "errors": []
}

Some errors can include an error code. If an error code is present, it will be provided in the body of the response as well as a custom PartPay-Error header.

The following is an error from POST /pos/order where the customer approval code entered has been approved for an amount that is less than the requested order amount.

Other validation errors.

Validation Error Response

400 Bad Request
{
  "message": "'Amount' must be greater than '0'.",
  "isValid": false,
  "errors": [
    {
      "propertyName": "createOrderModel.amount",
      "errorMessages": [
        "'Amount' must be greater than '0'."
      ]
    }
  ]
}

A generic validation error can be a 400 Bad Request or a 422 Unprocessable Entity

The following is an error from POST /pos/order where the order amount was incorrect.

Please note that if there are multiple validation errors, the message property is populated with just the first message.