This documentation is deprecated and only available for supporting old/legacy integrations using for example hashes.
New documentation can be found here: Home
Reference number API
- Heli Kettunen
The new Payment App launched by Shopify 2022 does not allow additional data to be stored in the payment data. This means that reference number that were previously used to connect a payment with an order is not stored anymore in Shopify's payment data. The only data available is Shopify payment identifier (payment_id).
In order to be able to connect Shopify's payment id with the refenrence number and /or payment id in Svea system we have published an interface which allows the e-commerce to use Shopify payment_id to query corresponding reference number of the payment and or Svea payment_id.
The API is available at https://europe-west2-svea-payments.cloudfunctions.net
Integration handlers
/references (get-references.ts)
This handler will provide additional functionality for Svea payments app to, after payments, check and associate one or more (copes with none) Svea system IDs and internal Shopify IDs for external reporting. Caller must know the store's secret from Svea system to calculate a hash of the payload.
This handler will take in the order identifiers and return a mapping of the internal IDs and reference numbers.
GET references
?shopis the Shopify shop domain of the calling store (<store>.myshopify.com)?testflag tells, if test credentials (true) or production credentials (false) should be used. Missing/invalid defaults tofalse. The desired credentials must also be saved in the configuration for the system to be able to use them for verification!?idsparameter with one or more IDs (pmt_id in Svea system), separated using comma (,):?ids=ID1,ID2,IDN?internalparameter with one or more Shopify internal IDs, separated using comma (,):?internal=INT1,INT2,INTN?signatureis an uppercasesha256hash calculated over the arguments used, with appended key being the customer secret obtained from Svea (same secret that's inserted into the admin application's Merchant Key field)
?signature
When calculating the sha256 hash, each query parameter's value is used, separated by ampersand (&). The order of the parameters must be alphabetical by the keys (ids, internal, shop, test) but the order in the URL isn't meaningful. Missing query parameters won't be used for the signature calculation.
This process is analogous to the Svea API convention. Note, that the hashed value must end with the shared secret and additional ampersand and resulting hash must be uppercase.
Responses
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:
GET /references?shop=my-store.myshopify.com&test=true&ids=nDPGXbmrlTe9jmXqS5m,Invalid_ID&internal=nfzEJM7DOw0D5laQeUkuFGJCN,Invalid_Internal&signature=...
{
"ids": {
"nDPGXbmrlTe9jmXqS5m": {
"internal": "nDPGXbmrlTe9jmXqS5mXPy9Rn",
"reference": "00000000009544178350"
}
},
"internal": {
"nfzEJM7DOw0D5laQeUkuFGJCN": {
"id": "nfzEJM7DOw0D5laQeUk",
"reference": "00000000004675838917"
}
}
"invalid": [
"Invalid_ID", "Invalid_Internal"
]
} |
.internal[] is a key-value object with all successfully mapped internal IDs. .ids[] like wise is a key-value object mapping internal IDs to Svea IDs. .invalid will contain all IDs, 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.