Introduction

In order to receive notifications from PAYONE Link you have to implement the following API on your systems.

You can choose whatever endpoint urls you like. The endpoint urls in the following open api documentation are only examples. To let us know where your PAYONE Link notification is available you need to provide the parameter notifyUrl when creating or updating a link.

We highly recommend to only process verified notifications. See How to Verify Notifications for more details.

Please consider that the provided execution status of PAYONE Link notification only provides the information if a link was used by an end customer.
If additional information about the payment status of a transaction is needed please refer to the TransactionStatus notification which provides the current status of the transaction itself.

You can connect both notifications by using “paymentProcess” (ID) from PAYONE Link notification and “txid” from transaction status notification.

---end

API Definition
openapi: 3.0.4
info:
  version: v1
  title: PAYONE Link Notification API
paths:
  /linkExecutionNotification:
    post:
      tags:
        - PAYONE Link Notifications
      operationId: receiveLinkExecutionNotification
      parameters:
        - in: header
          name: X-Request-ID
          schema:
            type: string
            format: uuid
          required: true
        - in: header
          name: X-Auth-Code
          schema:
            type: string
          required: true
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LinkExecutionNotification'
      responses:
        '200':
          description:
            'Link Status received. Any other response status will trigger a retry to deliver the notification.'
components:
  schemas:
    LinkExecutionNotification:
      type: object
      properties:
        header:
          $ref: '#/components/schemas/NotificationHeader'
        linkExecutionData:
          $ref: '#/components/schemas/LinkExecutionData'
    NotificationType:
      type: object
      properties:
        type:
          type: string
          enum:
            - PAYONE_LINK_EXECUTION
        version:
          type: string
          enum:
            - '1.0'
    NotificationHeader:
      type: object
      properties:
        notificationType:
          $ref: '#/components/schemas/NotificationType'
        merchantId:
          type: string
          example: "12345"
        portalId:
          type: string
          example: "12345678"
        mode:
          type: string
          enum:
            - LIVE
            - TEST
    LinkExecutionData:
      type: object
      properties:
        linkId:
          pattern: '[0N1RWU4X6F8Z9ALBQC3EG5HJKM2PS7TVDY]{32}'
          type: string
          example: 'MFBZP2VRJZAK4P2H0J4WJHT1226GM2FG'
        paymentProcess:
          type: string
          example: '123456789'
        executionStatus:
          type: string
          enum:
            - APPROVED
            - REDIRECTED
            - PENDING
            - ERROR
        paymentMethod:
          type: string
          enum:
            - VISA
            - MASTERCARD
            - AMEX
            - PAYPAL
            - SOFORT
            - PAYDIREKT
            - POSTFINANCE_E
            - POSTFINANCE_CARD
            - BANCONTACT
            - PRZELEWY24
            - ALIPAY
            - IDEAL
            - EPS
            - GIROPAY
            - SEPA
        executionTime:
          type: string
          format: date-time

---end

Download Yaml Datei

---end

For security reasons (authenticity, integrity), every transmitted notification is provided with a signature. 

This signature is calculated both on the side of the service recipient (PAYONE) and on the side of the service provider (notification recipient). Requests should only be processed technically by the service provider if the calculated signature based on the request content corresponds to the signature provided by the service recipient.

Structure of the Signature

The signature is created based on the 'string-to-sign' and the 'secret' using the function HMAC-SHA-512 [RFC 2104]
The 'secret' is never transmitted in the communication, but is kept at the respective participant. An SHA512 hash of the PortalKey is used as the secret.

Determination of the 'string-to-sign'
The following values are included to determine the string-to-sign:

parameter format description

X-Request-ID

UUID

Unique request-ID from the HTTP-Header.

example: 67e96638-8295-41ad-894d-914900461f26

SHA512-Hash des Request Body

String

SHA512 Hash without salt of the request body.

example: B5AB92007F8FC0F2BE26919EE9064C6268767D67DBDA1E6FA8691D1AEA7359F1D19B464F1F72393585DD7F42DA0B2C941FAEEAEA2F13CCF88

---end

From the above-mentioned parameters, the string-to-sign is created in the order given above. For this, the values are concatenated separated by the separator ":".

Example 'string-to-sign': 
67e96638-8295-41ad-894d-914900461f26:B5AB92007F8FC0F2BE26919EE9064C6268767D67DBDA1E6FA8691D1AEA7359F1D19B464F1F72393585DD7F42DA0B2C941FAEEAEA2F13CCF88

---end

Transmission of the Signature

The signature is transmitted by the service recipient - in addition to the unique technical request ID (X-Request ID) required to create the signature on the recipient side - in the http header field X-Auth-Code.

---end

PHP-Example
function verifyNotificationSignature(Request $request): bool
{
    $stringToSign = $request->getHeaderLine('X-Request-ID') . ':' . hash('sha512', trim($request->getBody()), false);
    $key = hash('sha512', $_ENV['PORTAL_KEY'], false);
    $signature = hash_hmac('sha512', $stringToSign, $key);
    return hash_equals($signature, $request->getHeaderLine('X-Auth-Code'));
}

---end