New Paytrail: Shopify reference number interface

The new payment interface offered by Shopify does not allow additional data to be stored in the payment data. As a result, if you have transaction specific settlements, i.e. a model in which each payment made in the online store is credited to a bank account as a reference transfer, it is not possible to store the reference number used in the transfer in Shopify's payment information.

In addition, when transaction specific settlements is enabled, Paytrail's reports do not include Shopify's internal payment ID, but only the reference number generated by the integration used in the account transfer.

Due to these limitations, we have published a separate reference number interface from which it is possible to query the transfer reference number corresponding to Shopify's internal payment identifier (payment_id) or, conversely, the Shopify payment identifier based on the transfer reference number.

Interface description

The interface is available at Authentication is based on the merchant secret key entered in the integration settings, more details in the interface description below:

GET /references

  • ?shop is the Shopify shop domain of the calling store (<store>
  • ?test flag tells, if test credentials (true) or production credentials (false) should be used. Missing/invalid defaults to false
  • ?ids parameters with one or more IDs, separated using comma (,): ?ids=ID1,ID2,IDN
  • ?references parameters with one or more reference numbers, separated using comma (,): ?references=REF1,REF2,REFN
  • ?signature is a sha256 HMAC digest calculated over the arguments used, cryptographic key being the customer secret obtained from Paytrail (same secret that's inserted into the admin application's _Merchant Key_ field)


When calculating the HMAC sha256 digest, each query parameter is added as a key-value pair, parts separated by colon (:), ordering the pairs alphabetically. Finally, add an empty string at the end of the pairs list before joining them using line feed characters (\n). This process is analogous to the Paytrail API convention. Note, that missing query parameters won't be used for the signature calculation

Example in TypeScript:

const params = { ... };
const secret = 'SAIPPUAKAUPPIAS';
const hmacPayload = Object.keys(params)
    .map((key) => [key, params[key]].join(':'))
    .concat('') // additional empty string for the "body"
const digest = crypto.createHmac('sha256', secret).update(hmacPayload).digest('hex');


If the request is proper, and the signature is calculated properly and with credential information found in the system, 200 OK response with a JSON response is returned:

http request
GET /references?,1F39S7GlENawQL44HbAhk7NS&references=1234561&signature=...
    "references": {
        "0Kp2nCxCGW3ZaRdmsFdQPGwG": "1234561"
    "ids": {
        "1234561": "0Kp2nCxCGW3ZaRdmsFdQPGwG",
    "invalid": [

.references is a key-value object (Payment.orderId as key, Payment.reference as value) with all successfully mapped references. .ids like wise is a key-value object mapping references to IDs. .invalid will contain all IDs and references that for some reason weren't found for the particular store.

If any of the query parameters are invalid, 401 Unauthorized is returned. In other error cases, HTTP 4xx or 500 may be returned.


Was this article helpful?
0 out of 0 found this helpful