/
Webhooki wersja v2

Webhooki wersja v2

Owned by Joanna Wołosz
Last updated: Mar 26, 2025
2 min read

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.valueInCents
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.valueInCents
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.valueInCents
eventData.createdDate
eventData.eventDateTime
eventData.merchantId
eventData.settlementId
eventData.transferReference
eventType

Request Body

{ "eventType":"string", "eventData":{ "operationId":"string", "status":"string", "amount":{ "valueInCents": INTEGER, "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):

      • valueInCents (INTEGER): Całościowa kwota płatności będąca sumą payload.amount.value i payload.additionalFundingAmount.value wyrażona w groszach.
        Przykłady:
        a) Jeśli kwota wynosi 124.50, to wartość valueInCents =12450.
        b) Jeśli kwota wynosi -75, to wartość valueInCents = -7500.
        c) Jeśli kwota wynosi 1.23, to wartość valueInCents = 123.

      • 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).

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":{ "valueInCents": -4565, "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":{ "valueInCents": -4565, "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":{ "valueInCents": 10686, "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" } }

Przykład dla PAYMENT_DECLINED:

{ "eventType":"PAYMENT_DECLINED", "eventData":{ "orderReference":"abcabc0-1|df6352d7-dbc1-4e86-967f-b0a21573a3f4", "status":"DECLINED", "amount":{ "valueInCents": 6047, "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" } }

Przykład dla SETTLEMENT:

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

 

 

 

Related content