API docs by Redocly

OP Online Payment - REST API (1.3.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 as well as refunds and status queries
  • 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


OP Online Payment service flow:

  1. The merchant or payment service provider initiates an online payment process by using the Create payment operation.

  2. The merchant or payment service provider redirects the customer’s browser to the Browser flow API.

  3. After a successful payment the customer is redirected back to the web store's return URL given in the Create payment operation.

  4. As an optional service, the OP Online Payment service can make a callback to the merchant or payment service provider's Callback API (to b2bBackend URL given in the Create payment operation). We highly recommend implementing the Merchant callback API to ensure that the payment status will be received even if the customer’s browser does not come back to the shop for some reason (e.g. customer closes the browser or moves to another site).

  5. The merchant or payment service provider can also query a payment status with the Payment status operation.

  6. The merchant or payment service provider can return a payment with the Refund operation.

Authentication

The OP Online Payment REST API authenticates the caller by validating the API key (parameter x-api-key in the HTTP header) and the HMAC signature (parameter Authorization in the HTTP header) sent in the request.

The API key can be obtained from the OP Developer portal when a new application is created. The HMAC signature is calculated over the API request contents using the authentication signature scheme described in the authentication example.

See the sections Sandbox and Production access for further details on how to access specific environments.

Security Considerations

It is extremely important that the merchantId, the accountId and the client private key are not exposed at any point. Together they represent the identity of the client and thereby the corporation. In the possession of an attacker they could be used to make fraudulent API calls potentially causing considerable damage. Also, to secure the authenticity of the payment transaction, the paymentId should not be exposed to the customer (payer) or to any another party.

Sandbox

The OP Online Payment service can be tested in a sandbox environment by creating a new application in OP Developer and obtaining an API key. A secret is also generated, but it is not required for using the sandbox. Use the private key given in the authentication example when calculating the HMAC authentication signature for the sandbox API requests.

The merchantId and the accountId can be anything in the sandbox but they should follow the UUID format.

There is currently no test UI available in the sandbox environment. The Browser flow API sends the customer's browser directly to one of the return addresses (return, reject or cancel) specified in the Create payment request.

Payment cancellation can be simulated by using the accountId value "71fead42-b248-4fff-8b86-29296eacaf98" and similarly "eb3b688b-15da-48bd-b2fb-4f3eda501089" produces a failed payment (reject).

Other accountId values produce a successful payment (return).

The x-api-key header value for the Merchant callback API notifications in the sandbox environment is "dxB2AFwnwraQRrAsLZpJ5T4IrNGp7fhx".

Using the sandbox is free of charge although some restrictions on the number of calls apply.

Production access

Production access requires a contract with your local OP co-operative bank. Contact your OP co-operative bank directly.

Pricing information for production use is available from OP co-operative banks.

Once you have signed the contract, apply for production access to get an API key.

The API key will be available through OP Developer after we have accepted your application. The API keys are different for the sandbox and production.

We will also request a public key for the signatures by e-mail from your technical contact. Carefully read the instructions in the e-mail on how to onboard the public key to the production environment. After the public key has been received, the merchantId, accountId and production API URLs will be sent to the technical contact in a secure email.

For more information about the keys and how to generate them, see the page on Authentication Signatures.

Change log

v1.3.1 (04/2024)

Changed

  • Deprecated request parameter messageToCustomer in endpoint Create payment

v1.3 (03/2024)

Added

  • Code examples in C#, Java, Node.js, PHP and Python added for all endpoints.

Changed

  • Updated API doc format from Swagger 2.0 to OpenAPI 3.0.1
  • Error code 403 added to the response of Create payment
  • Request body parameter url usage limitation (no localhost URLs) added to schema documentation

v1.2.2 (10/2021)

Changed

  • Multiple small fixes

v1.2.1 (10/2021)

  • Initial version

Payments

Create payment

Initiates an online payment process to collect a payment from customer. The return, cancel and reject urls are used as browser redirect addresses in the customer’s browser flow. Depending on the outcome of the payment flow, the customer’s browser is directed to one of these addresses from the OP Online payment service.

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

Unique identifier (UUID) of the session. All requests in the same session should use the same session ID. Each x-session-id and x-request-id combination can only be used once.

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

Unique identifier (UUID) of the request. Each request must have a unique request ID. Each x-session-id and x-request-id combination can only be used once.

Date
required
string

Standard HTTP Date header containing the date and time (GMT) when the request was sent (for example: Wed, 21 Oct 2019 07:28:00 GMT).

Request Body schema: application/json
required

Payment info

accountId
required
string <alphanumeric> <= 36 characters

Unique id for target account

amount
required
string^\d{1,13}\.\d{2}$

Amount of the payment with two decimal precision

currency
required
string
Value: "EUR"

ISO 4217 currency code of the payment.

reference
required
string <alphanumeric> [ 2 .. 25 ] characters

Reference number without spaces. Finnish national reference format or RF reference.

required
object (SuccessEndpoint)

Endpoint where customer's browser is redirected to at the end of the browser flow when the payment was successful. http://localhost:port type URL's not accepted.

required
object (CancelEndpoint)

Endpoint where customer's browser is redirected to at the end of the browser flow when the payment was cancelled. http://localhost:port type URL's not accepted.

required
object (RejectEndpoint)

Endpoint where customer's browser is redirected to at the end of the browser flow when the payment failed. http://localhost:port type URL's not accepted.

object (Message)
language
string
Enum: "fi" "sv" "en"

ISO 639-1 Code. fi = Finnish, sv = Swedish, en = English. Finnish is the default language.

object (CallbackRequestEndpoint)

Endpoint for Merchant callback API notifications. http://localhost:port type URL's not accepted.

messageToCustomer
string <alphanumeric with spaces> <= 500 characters
Deprecated

Beneficiary message to customer. Will not be shown in customer's balance sheet, but shown in payment page.

object (UltimateBeneficiary)

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "paymentId": "8a5d4aac-8f8f-47ed-ae2f-36ffeaf57c79",
  • "paymentOperationId": "a2697d49-30ec-4d50-b08b-459b73e7872d2e133836-8bfa-440c-a0b0-9f38613897b4",
  • "paymentOperationValidation": "MEUCIBNNSSslt+JUCCi/N7vwyoBzgbjekyvafeQvsItlAg0mAiEAjZC5RBFRf+hs6dOMfes/mz7jN6Fo69PxpnblXCnuEmw="
}

Payment status

Returns the status of an online payment.

Authorizations:
(xApiKeyAuthorization)
path Parameters
paymentId
required
string <= 36 characters

ID of the payment returned from the Create payment (POST) call.

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

Unique identifier (UUID) of the session. All requests in the same session should use the same session ID. Each x-session-id and x-request-id combination can only be used once.

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

Unique identifier (UUID) of the request. Each request must have a unique request ID. Each x-session-id and x-request-id combination can only be used once.

Date
required
string

Standard HTTP Date header containing the date and time (GMT) when the request was sent (for example: Wed, 21 Oct 2019 07:28:00 GMT).

Responses

Request samples 

curl --request GET \ --url 'https://sandbox.apis.op.fi/paymentbutton/v1/payments/8a5d4aac-8f8f-47ed-ae2f-36ffeaf57c79' \ --header 'Date: Tue, 02 Nov 2021 14:21:38 GMT' \ --header 'x-request-id: 1b2de711-5813-43f4-bd49-ea853554c388' \ --header 'x-session-id: a07dd344-71a3-4249-a64e-c4eb99b3a80b' \ --header 'x-api-key: 3AL1...' \ --header 'Authorization: c3efaaee-a6bb-449f-9213-e45e23a462ef:1:1:39a05bba09481...'

Response samples

Content type
application/json
{
  • "paymentId": "string",
  • "amount": "10.00",
  • "status": "INITIAL",
  • "refunds": [
    ],
  • "refundOf": "string",
  • "createTime": "2020-03-10T11:23:57.917Z",
  • "updateTime": "2020-03-10T11:23:57.917Z",
  • "paymentType": "CREDIT",
  • "totalRefundedAmount": "10.00",
  • "failureReason": "UnknownError",
  • "errorType": "string",
  • "errorCode": "string"
}

Refund

Initiates a refund to the original payer.

Authorizations:
(xApiKeyAuthorization)
path Parameters
paymentId
required
string <= 36 characters

ID of the payment returned from the Create payment (POST) call.

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

Unique identifier (UUID) of the session. All requests in the same session should use the same session ID. Each x-session-id and x-request-id combination can only be used once.

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

Unique identifier (UUID) of the request. Each request must have a unique request ID. Each x-session-id and x-request-id combination can only be used once.

Date
required
string

Standard HTTP Date header containing the date and time (GMT) when the request was sent (for example: Wed, 21 Oct 2019 07:28:00 GMT).

Request Body schema: application/json
required

Refund info

amount
required
string^\d{1,13}\.\d{2}$

Amount of the refund to an accuracy of two decimal places. Maximum amount is the amount of the original payment.

currency
required
string
Value: "EUR"

ISO 4217 currency code of the payment.

reference
string <alphanumeric> [ 2 .. 25 ] characters

Reference number without spaces. Finnish national reference format or RF reference. Refund must have reference or message, but not both.

object (RefundMessage)

Responses

Request samples

Content type
application/json
{
  • "amount": "1.00",
  • "currency": "EUR",
  • "reference": "RF511459162006"
}

Response samples

Content type
application/json
{
  • "paymentId": "8a5d4aac-8f8f-47ed-ae2f-36ffeaf57c79",
  • "totalRefundedAmount": "1.00"
}

Other bank providers

List of banks in multibank service

Returns a list of supported banks and their statuses for the OP Online Payment multibank service (add-on service). The IDs can be used to initiate a payment in banks other than OP (with the Browser flow API). The returned list is unlikely to change frequently and it is recommended to store the returned bankId:s in the client-side instead of re-fetching the list every time.

Authorizations:
(xApiKeyAuthorization)

Responses

Request samples 

curl --request GET \ --url 'https://sandbox.apis.op.fi/paymentbutton/v1/payments/multibank/providers' \ --header 'Date: Tue, 02 Nov 2021 14:40:12 GMT' \ --header 'x-request-id: 0079ae15-395a-4a45-bcba-502538f62654' \ --header 'x-session-id: 38cda2a2-2b5c-47ca-b06a-be8170e7becc' \ --header 'x-api-key: 3AL1...' \ --header 'Authorization: c3efaaee-a6bb-449f-9213-e45e23a462ef:1:1:ab64246fd9512...'

Response samples

Content type
application/json
{
  • "providers": [
    ]
}