Shopifyn tarjoama maksurajapinta ei mahdollista lisätietojen tallentamista maksujen tietoihin. Tästä johtuen, mikäli käytössäsi on tapahtumakohtaiset tilitykset, eli malli jossa jokainen verkkokaupassa tehty maksu tilitetään erikseen pankkitilille viitesiirtona, ei tilisiirrossa käytettyä viitenumeroa ole mahdollista tallentaa Shopifyn maksun tietoihin.
Lisäksi, tapahtumakohtaisten tilitysten ollessa käytössä, Paytrailin raporteilta ei löydy Shopifyn sisäistä maksun tunnistetta, vaan ainoastaan tilisiirrossa käytetty integraation luoma viitenumero.
Näistä rajoitteista johtuen, olemme julkaisseet erillisen viitenumerorajapinnan, josta on mahdollista kysellä Shopifyn sisäistä maksun tunnistetta (payment_id) vastaava tilisiirron viitenumero tai kääntäen tilisiirron viitenumeron perusteella Shopifyn maksutunniste.
Rajapintakuvaus
Rajapinta palvelee osoitteessa http://europe-west2-paytrail-production.cloudfunctions.net/. Autentikaatio tapahtuu integraation asetuksiin syötetyn kauppiasvarmenteen perusteella, tarkemmat tiedot alla olevassa rajapintakuvauksessa:
GET /references
- ?shop is the Shopify shop domain of the calling store (<store>.myshopify.com)
- ?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)
?signature
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:
ts
const params = { ... };
const secret = 'SAIPPUAKAUPPIAS';
const hmacPayload = Object.keys(params)
.sort()
.map((key) => [key, params[key]].join(':'))
.concat('') // additional empty string for the "body"
.join('\n');
const digest = crypto.createHmac('sha256', secret).update(hmacPayload).digest('hex');
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:
http request
GET /references?shop=my-store.myshopify.com&test=true&ids=0Kp2nCxCGW3ZaRdmsFdQPGwG,1F39S7GlENawQL44HbAhk7NS&references=1234561&signature=...
{
"references": {
"0Kp2nCxCGW3ZaRdmsFdQPGwG": "1234561"
},
"ids": {
"1234561": "0Kp2nCxCGW3ZaRdmsFdQPGwG",
}
"invalid": [
"1F39S7GlENawQL44HbAhk7NS"
]
}
.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.