Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Version History

Version 1 Next »

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.

Merchant Refunds Receiver API

Single endpoint

POST /events

Headers

  • Content-Type: application/json

  • X-Signature: <calculated_signature>

  • X-API-Version: <api_version>

Request Body

{
   "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:

{
   "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: 

{
   "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:

{
   "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:

{
   "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:

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

  • No labels