Transaction webhooks

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>

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.

Request Body

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:

Example for REFUND_DECLINED: 

Example for PAYMENT_AUTHORIZED:

Example for PAYMENT_DECLINED:

Example for SETTLEMENT: