Webhooki transakcyjne

W artykule opisano endpoint i strukturę danych, jakie merchant powinien zaimplementować aby otrzymywać informacje o zwrotach, płatnościach i rozliczeniach.

Aby otrzymywać webhooki merchant powinien przekazać do InPost odpowiedni adres URL dla płatności, zwrotów oraz rozliczeń poprzez kontakt na adres integracjapay@inpost.pl.

Merchant Refunds Receiver API

Endpoint

POST /events

Nagłówki

Content-Type: application/json
X-Signature: <calculated_signature>
X-API-Version: <api_version>

Sygnatura

Sygnatura jest wyliczana poprzez połączenie wartości nagłówka X-API-Version, wartości wymienionych poniżej pól treści żądania w kolejności alfanumerycznej oraz merchant secret (Jeżeli któraś z wartości jest pusta, wtedy powinna być traktowana jako pusty ciąg znaków.). Końcowa sygnatura to szesnastkowy skrót funkcji skrótu SHA-512 zastosowany do połączonej wiadomości, zapisany małymi literami. W celu weryfikacji sygnatury należy porównać wyliczoną wartość z wartością nagłówka X-Signature.

Payment:
eventData.amount.currency
eventData.amount.value
eventData.createdDate
eventData.eventDateTime
eventData.merchantId
eventData.orderReference
eventData.payment.id
eventData.payment.method
eventData.payment.reference
eventData.status
eventType
Refund:
eventData.amount.currency
eventData.amount.value
eventData.createdDate
eventData.eventDateTime
eventData.merchantId
eventData.operationId
eventData.payment.id
eventData.payment.method
eventData.refundReference
eventData.status
eventType
Settlement:
eventData.amount.currency
eventData.amount.value
eventData.createdDate
eventData.eventDateTime
eventData.merchantId
eventData.settlementId
eventData.transferReference
eventType

Request Body

{
   "eventType":"string",
   "eventData":{
      "operationId":"string",
      "status":"string",
      "amount":{
         "value": DECIMAL,
         "currency":"string"
      },
      "payment":{
         "id":"string",
         "method":"string",
         "reference":"string"
      },
      "merchantId":"string",
      "eventDateTime":"string",
      "createdDate":"string",
      "orderReference":"string",            "refundReference":"string",             "settlementId":"string",
      "transferReference":"string"
   }
}

Opis parametrów

eventType (string): Typ eventu (np. REFUND, REFUND_DECLINED, PAYMENT_AUTHORIZED, PAYMENT_DECLINED, SETTLEMENT).
eventData (object): Dane powiązane z eventem

Wspólne parametry:
- amount (object, wymagany):
  - value (DECIMAL): Całościowa kwota płatności będąca sumą payload.amount.value i payload.additionalFundingAmount.value.
  - currency (string): Waluta płatności
- merchantId (string, wymagany): Wartość merchant ID nadana przez InPost
- eventDateTime (string, wymagany): Data i czas wystąpienia eventu
- createdDate (string, wymagany): Data i czas utworzenia płatności .{}
  
  Parametry określone dla Payment/Payment Declined:
- status (string, wymagany): Status płatności (DECLINED, AUTHORIZED).{}
- payment (object, wymagany):
  - id (string, wymagany): ID płatności
  - method (string, wymagany): Nazwa metody płatności, która została użyta
  - reference (string): Referencja płatności
- orderReference (string): Referencja zamówienia (parametr opcjonalny dla payment-related events).{}
- zonedCreatedDate (string, wymagany): Data i godzina wraz ze strefą czasową, kiedy płatność została utworzona.{}
  
  Parametry określone dla Settlement:
- settlementId (string, wymagany): Zewnętrzny ID płatności
- transferReference (string): Numer referencyjny przelewu
  
  Parametry określone dla Refund:
- status (string): Status zwrotu (np. REFUNDED, DECLINED).{}
- operationId (string): Wartość ID operacji powiązanej z płatnością
- refundReference (string): Numer referencyjny zwrotu
- payment (object, wymagany):
  - id (string, wymagany): ID płatności
  - method (string, wymagany): Nazwa użytej metody płatności
  - reference (string): Referencja płatności

Przykład dla REFUND:

{
   "eventType":"REFUND",
   "eventData":{
      "operationId":"4t54e318-54r3-4f27-b61b-ebd65tr2450d",
      "status":"REFUNDED",
      "amount":{
         "value": -45.65,
         "currency":"PLN"
      },
      "payment":{
         "id":"442b1448-c9c7-4f27-b61b-ebd89a8c850d",
         "method":"CARD_TOKEN"
      },
      "merchantId":"V000000000",
      "eventDateTime":"2022-12-19T07:21:21Z",
      "createdDate":"2020-06-02T11:21:55.0002",
      "refundReference":"refund#1_234b1448-c9c7-4f27-b61b-ebd89a8c8re3"
   }
}

Przykład dla REFUND_DECLINED:

{
   "eventType":"REFUND_DECLINED",
   "eventData":{
      "operationId":"4t54e318-54r3-4f27-661b-ebd65tr2450d",
      "status":"DECLINED",
      "amount":{
         "value": -45.65,
         "currency":"PLN"
      },
      "payment":{
         "id":"442b1448-c9c7-4f27-b61b-ebd89a8c850d",
         "method":"CARD_TOKEN"
      },
      "merchantId":"V000000000",
      "eventDateTime":"2022-12-19T07:21:21Z",
      "createdDate":"2020-06-02T11:21:55.000Z",
      "refundReference":"refund#1_234b1448-c9c7-4f27-b61b-ebd89a8c8re3"
   }
}

Przykład dla PAYMENT_AUTHORIZED:

{
   "eventType":"PAYMENT_AUTHORIZED",
   "eventData":{
      "orderReference":"kasast0-1|56ff8e24-d310-4719-ba54-ce4f28f4c83d",
      "status":"AUTHORIZED",
      "amount":{
         "value": 106.86,
         "currency":"PLN"
      },
      "payment":{
         "id":"5117c049-c01c-4f9d-9d53-ca261525b85c",
         "method":"CARD_TOKEN",
         "reference":"kasast0-1_52f0db9e-546d-4c38-a246-d2ffa4f090ae"
      },
      "merchantId":"V000000000",
      "eventDateTime":"2024-04-17T10:29:36.320685806Z",
      "createdDate":"2024-04-17T10:29:36.3206858Z",      "zonedCreatedDate": "2024-04-17T13:21:55.000+02:00"      }
}

Przykład dla PAYMENT_DECLINED:

{
   "eventType":"PAYMENT_DECLINED",
   "eventData":{
      "orderReference":"abcabc0-1|df6352d7-dbc1-4e86-967f-b0a21573a3f4",
      "status":"DECLINED",
      "amount":{
         "value": 60.47,
         "currency":"PLN"
      },
      "payment":{
         "id":"42170024-c4c7-438a-b8fb-e9c8d5d7279d",
         "method":"CARD_TOKEN",
         "reference":"kasast0-1_52f0db9e-546d-4c38-a246-d2ffa4f090ae"
      },
      "merchantId":"V000000000",
      "eventDateTime":"2024-04-17T09:58:45.180521112Z",      "createdDate":"2024-04-17T10:29:36.3206858Z",      "zonedCreatedDate": "2024-04-17T13:21:55.000+02:00"          }
}

Przykład dla SETTLEMENT:

{
  "eventType": "SETTLEMENT",
  "eventData": {
    "settlementId": "442b1448-c9c7-4f27-b61b-ebd89a8c850d",
    "merchantId": "V000000000",
    "amount": {
      "value": 13421.4,
      "currency": "PLN"
    },
    "transferReference": "240426714007",
    "eventDateTime": "2024-04-26T07:21:21Z",
    "createdDate": "2023-01-05T13:13:14"
  }
}

Developer Documentations