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"
  }
}