OP Online Payment - REST API (1.2.1)

Download OpenAPI specification:Download

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:

The merchant or payment service provider initiates an online payment process by using the Create payment operation.
The merchant or payment service provider redirects the customer’s browser to the Browser flow API.
After a successful payment the customer is redirected back to the web store's return URL given in the Create payment operation.
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).
The merchant or payment service provider can also query a payment status with the Payment status operation.
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 (x-api-key HTTP header) and the HMAC signature (Authorization 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 OP cooperative bank. Contact your OP cooperative bank directly. Pricing information for production use is available from OP cooperative 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.

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

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.
required	object (CancelEndpoint) Endpoint where customer's browser is redirected to at the end of the browser flow when the payment was cancelled.
required	object (RejectEndpoint) Endpoint where customer's browser is redirected to at the end of the browser flow when the payment failed.
	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.
messageToCustomer	string <alphanumeric with spaces> <= 500 characters Beneficiary message to customer. Will not be shown in customer's balance sheet, but shown in payment page.
	object (UltimateBeneficiary)

Responses

Request samples

Payload
CLI

Content type

application/json

{"amount": "1.00",
"cancel": {"url": "https://shop.domain/cancel/path"
},
"reject": {"url": "https://shop.domain/reject/path"
},
"return": {"url": "https://shop.domain/return/path"
},
"currency": "EUR",
"accountId": "8a5d4aac-8f8f-47ed-ae2f-36ffeaf57c79",
"reference": "RF3517834735"
}

Response samples

200
400

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

CLI

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

200
400

Content type

application/json

{"paymentId": "string",
"amount": "10.00",
"status": "INITIAL",
"refunds": [{"paymentId": "string",
"amount": "10.00",
"status": "INITIAL",
"createTime": "2020-03-10T11:23:57.917Z",
"updateTime": "2020-03-10T11:23:57.917Z"
}
],
"refundOf": "string",
"createTime": "2020-03-10T11:23:57.917Z",
"updateTime": "2020-03-10T11:23:57.917Z",
"paymentType": "CREDIT",
"totalRefundedAmount": "10.00",
"failureReason": "UnknownError"
}

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

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

Payload
CLI

Content type

application/json

{"amount": "1.00",
"currency": "EUR",
"reference": "RF511459162006"
}

Response samples

200
400

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

CLI

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

200
400

Content type

application/json

{"providers": [{"bankId": "Bank1",
"countryCode": "FI",
"name": "Bank of ones",
"status": {"current": "ENABLED"
}
},
{"bankId": "Bank2",
"countryCode": "FI",
"name": "Bank of twos",
"status": {"current": "ENABLED"
}
}
]
}