Callback

A callback is our preferred option to notify the Payment terminal gateway that the PartPay process has completed, and the payment can be considered authorised from the terminal point of view.

Content-Type

The PartPay callback will return with a Content-Type of application/x-www-form-urlencoded

Response Values

Below is a list of the response values posted to the payment terminal gateway once an order changes it’s status

parameter type exmaple notes
orderId uuid 123e4567-e89b-12d3-a456-426655440000 this is the orderId value from the create terminal order endpoint
orderNumber string 181211-303902 a human readable PartPay identifier for the order
orderStatus enum approved, declined
gatewayReference string value passed as gatewayReference field in create terminal order endpoint
merchantReference string value passed as merchantReference field in create terminal order endpoint
signature string

Example

Example callback POST request
POST /partpay-callback HTTP/1.1
Host: paymentterminalserver.com
Content-Type: application/x-www-form-urlencoded

orderId=123e4567-e89b-12d3-a456-426655440000&orderNumber=181211-303902&orderStatus=approved&gatewayReference=ab3902094330&merchantReference=87654321&signature=016df815e41f06afd4b35cae1ad1764a147230192ab125d5d7b0c3a65c3f3b42

HMAC Signature

This is computed by taking all parameters (excluding the signature parameter) and performing a hash on these.

Signing Example

Suppose the following values as an example:

key value
orderId 123e4567-e89b-12d3-a456-426655440000
orderNumber 181211-303902
orderStatus approved
gatewayReference ab3902094330
merchantReference 87654321

We would end up with a (pre-signed) payload with:

orderId=123e4567-e89b-12d3-a456-426655440000&orderNumber=181211-303902&orderStatus=approved&gatewayReference=ab3902094330&merchantReference=87654321

We will then sign this using the HMAC-SHA256 signing algorithm and a pre-shared key (iDt3PoeoSHu3r/mTbzkaHg for this example). This gives us the following signature: 016df815e41f06afd4b35cae1ad1764a147230192ab125d5d7b0c3a65c3f3b42

The signature is then appended to the body, so that the payload of the body ends up as:

orderId=123e4567-e89b-12d3-a456-426655440000&orderNumber=181211-303902&orderStatus=approved&gatewayReference=ab3902094330&merchantReference=87654321&signature=016df815e41f06afd4b35cae1ad1764a147230192ab125d5d7b0c3a65c3f3b42

Verifying

Verifying the payload when it is POSTed to the payment terminal gateway is a critical step. It guarantees the authenticity of the sender to be PartPay.

Verifying the signature is effectively a repeat of the signing process.

  1. The body without &signature=016df... should be signed with the same shared private key as the sender
  2. A simple comparison to see if the signatures are the same is the basis for a valid signature or not.