Versions Compared

Version Old Version 2 New Version 3
Changes made by

Joanna Wołosz

Joanna Wołosz

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

The article describes endpoint and data structures that would need to be implemented by merchants in order to receive information about refunds, payments and settlements.

Info

In order to receive webhooks merchant should provide to InPost appropriate URL for payments, refunds and settlements by writing at integracjapay@inpost.pl.

Merchant Refunds Receiver API

Single endpoint

Status
colourGreen
titlePOST
/events

Headers

  • Content-Type: application/json

  • X-Signature: <calculated_signature>

  • X-API-Version: <api_version>

Signature

Signature is calculated by concatenating X-API-Version header value, particular (listed below) request body field values in alphanumerical order and a merchant secret (If any of the values is null, then it should be treated as an empty string). Final signature is a lowercase hexadecimal digest of a SHA-512 hash function applied to the concatenated message. In order to verify the signature, please compare the calculated value with the X-Signature header value.

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

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

Field Descriptions

  • eventType (string): The type of event (e.g., REFUND, REFUND_DECLINED, PAYMENT_AUTHORIZED, PAYMENT_DECLINED, SETTLEMENT).

  • eventData (object): The data related to the specific event.

    Common Fields:

    • amount (object, required):

      • value (string): The total amount of the payment. This is the sum of payload.amount.value and payload.additionalFundingAmount.value.

      • currency (string): The currency of the payment amount.

    • merchantId (string, required): The merchant ID on the InPostPay side.

    • eventDateTime (string, required): The date and time when the event occurred.

    • createdDate (string, required): The date and time when the payment was created.{}

      Payment/Payment Declined Specific Fields:

    • status (string, required): The status of the payment (DECLINED, AUTHORIZED).{}

    • payment (object, required):

      • id (string, required): The ID of the payment.

      • method (string, required): The name of the payment method used.

      • reference (string): payment reference

    • orderReference (string): The reference of the order (optional, for payment-related events).{}

    • zonedCreatedDate (string, required): The date and time with timezone when the payment was created.{}

      Settlement Specific Fields:

    • settlementId (string, required): The external payment ID.

    • transferReference (string): The transfer reference number.

      Refund Specific Fields:

    • status (string): The status of the refund (e.g., REFUNDED, DECLINED).{}

    • operationId (string): The ID of the operation related to the payment.

    • refundReference (string): The refund reference number.

    • payment (object, required):

      • id (string, required): The ID of the payment.

      • method (string, required): The name of the payment method used.

      • reference (string): payment reference

Example for REFUND:

Code Block
{
   "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"
   }
}

Example for REFUND_DECLINED: 

Code Block
{
   "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"
   }
}

Example for PAYMENT_AUTHORIZED:

Code Block
{
   "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"      }
}

Example for PAYMENT_DECLINED:

Code Block
{
   "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"          }
}

Example for SETTLEMENT:

Code Block
{
  "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"
  }
}