API docs by Redocly

OP Online Payment - Merchant callback API (1.1.1)

Download OpenAPI specification:Download

Support: onlinepayment@op.fi


OP Online Payment allows merchants and payment service providers to collect e-commerce payments as credit transfers to an OP account from both OP customers and other banks' customers (add-on service). The OP Online Payment service includes the collection of payments and the making of payment status requests and payment refunds.


OP Online Payment API's documentation consists of three parts:

  • REST API: initiation of online payments, refund and status query

  • Browser flow API: initiation of the payment flow in the browser

  • Merchant callback API: an optional service for receiving notifications on the payment status changes

Merchant callback API

The Merchant callback API defines a specification for a backend interface capable of receiving notifications from the OP Online Payment service.

Implementing this interface is optional for merchants, but highly recommended.

The notifications are sent to the target URL provided by the merchant when the payment is created in the OP Online Payment REST API. The authenticity and integrity of the notifications is verified the same way as in the OP Online Payment REST API (with api-key and HMAC signature).

Payment status change notification

The following notification is sent to the merchant’s callback address when the status of the payment changes. The notification is sent once, and the merchant should respond with HTTP 200 OK response when the notification has been received. The merchant should define its callback address when creating an Online Payment using the REST API.

Authorizations:
(xApiKeyAuthorization)
header Parameters
x-request-id
required
string <uuid> <= 36 characters

Unique identifier (UUID) of the request.

x-session-id
required
string <uuid> <= 36 characters

Unique identifier (UUID) of the session.

Date
required
string

Standard HTTP Date header containing the date and time when the request was sent.

Request Body schema: application/json

Result info

paymentId
required
string <alphanumeric> <= 36 characters

ID of the payment (from the OP Online Payment REST API Create payment response).

status
required
string
Enum: "CANCELLED" "REJECTED" "PROCESSED"
  • PROCESSED - the payment was successfully processed. Equivalent to the PAID status of the "Payment status" query in the REST API.
  • CANCELLED - the payment was cancelled before the payment processing started. Equivalent to the CANCELLED status of the "Payment status" query in the REST API.
  • REJECTED - the payment failed during payment processing. Equivalent to the FAILED status of the "Payment status" query in the REST API.
paymentType
required
string
Enum: "INVOICE" "CREDIT" "OTHER_CREDIT"

CREDIT refers to a payment as an OP credit transfer. INVOICE refers to a payment as an OP Lasku payment. OTHER_CREDIT refers to a payment where the transfer is completed by another bank.

Responses

Request samples

Content type
application/json
{
  • "paymentId": "ec1253bd-791a-4252-9da8-b1d7163d3c69",
  • "status": "PROCESSED",
  • "paymentType": "CREDIT"
}