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.
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.
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.
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 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.
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:
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
{- "amount": "1.00",
- "currency": "EUR",
- "accountId": "8a5d4aac-8f8f-47ed-ae2f-36ffeaf57c79",
- "reference": "RF3517834735"
}
Response samples
- 200
- 400
{- "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:
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
{- "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:
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
{- "amount": "1.00",
- "currency": "EUR",
- "reference": "RF511459162006"
}
Response samples
- 200
- 400
{- "paymentId": "8a5d4aac-8f8f-47ed-ae2f-36ffeaf57c79",
- "totalRefundedAmount": "1.00"
}
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:
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
{- "providers": [
- {
- "bankId": "Bank1",
- "countryCode": "FI",
- "name": "Bank of ones",
- "status": {
- "current": "ENABLED"
}
}, - {
- "bankId": "Bank2",
- "countryCode": "FI",
- "name": "Bank of twos",
- "status": {
- "current": "ENABLED"
}
}
]
}