Based on the eCommerce solution you are using for your online store, you have a few options. In any case, please feel free to contact Modena Developer Support for assistance in implementing our financing solutions.
This document explains how to start your integration with the Modena Financing API.
Modena API uses OAuth2 client credentials flow for authentication.
First you'll need to get your client_id and client_secret from the Modena Partner Portal dashboard. Click on "Generate Secret" to generate new client secret.
Example request:
curl https://login-dev.modena.ee/oauth2/token -X POST \
-u "{YOUR_CLIENT_ID}:{YOUR_CLIENT_SECRET}" \
-H "Content-Type: application/x-www-form-urlencoded"
-d "grant_type=client_credentials" \
-d "scope=slicepayment creditpayment" Scope must be set to slicepayment for initiating Slice Payment Order requests.
Scope must be set to clickandtrypayment for initiating Click and Try Payment Order requests.
Scope must be set to creditpayment for initiating Credit Payment Order requests.
Scope must be set to businessleasing for initiating Business Leasing Payment Order requests.
The response you'll receive after running the command given above:
{
"access_token": "eyJraWQiOiJmMzljZjBiMi1hZmQ1LTQzMDMtOTkzYS0...",
"scope": "slicepayment",
"token_type": "Bearer",
"expires_in": 299
}All further requests require you to pass access_token that was acquired above. You must pass access_token as Bearer Authentication header.
Authorization: Bearer YOUR_ACCESS_TOKEN'Payment Request API-s are documented on Swagger (see url-s above)
Note that this response returns with status code Found 302 and contains Location header where customer must redirected to start the onboarding flow.
Your backend system needs to implement two required endpoints where Modena API can postback status of the payment. Cancel endpoint is optional.
These endpoints are sent to Modena when creating the payment order and must be implemented by your backend system: return_url, callback_url and cancel_url (optional)
return_url: URL where customer will be redirected upon successful payment
cancel_url: URL where customer will be redirected upon cancelling or failing payment (optional, return_url will be used if missing)
callback_url: URL where Modena API can notify your backend system of successful payment. This request is async and we expect response code 2XX
Modena frontend will POST form request with 3 parameters back to either return_url or cancel_url depending on the payment outcome. Following parameters are POST-ed when redirecting back to merchant:
Modena API will make delayed asynchronous request to provided callback_url upon successful or failed payment. Callback by default is sent with 15 second delay and is attempted 10 times. POST request with following parameters is sent:
Form data:
payment.confirmedHeaders:
Example request:
curl --request POST \
--url '{CALLBACK_URL}?id={APPLICATION_ID}&orderId={ORDER_ID}&action=payment.confirmed'
--header 'Content-Type: application/x-www-form-urlencoded'In your callback handlers you must implement logic to request for payment status using Application Status endpoint (see Swagger).
Example status request:
curl -X 'GET' \
'https://api-dev.modena.ee/modena/api/merchant/applications/{APPLICATION_ID}/status' \
-H 'accept: application/json' \
-H 'Authorization: Bearer {YOUR_ACCESS_TOKEN}'Example response:
{
"status": "SUCCESS"
} OUTSTANDING: Payment is still being processed
SUCCESS: Payment was successfuly processed
REJECTED: Payment was rejected (customer blocked, customer defaults)
FAILED: Payment processing failed (internal errors)
Process your internal order accordingly to these statuses to finalize the payment.
Modena signs every callback request with HMAC signature. It is strongly suggested to verify the signature.
For merchant form redirects digest parameter is included and is signed with signature_key
For async callback X-Modena-Signature HTTP header is provided and is signed with signature_key
Signature calculation formula (string concat):
HMAC_SHA256("client_secret", "id+orderId")Example parameters:
- signature_key: 68de6cbe-395d-49d0-85a7-ed5995794aef
- id: caae8a5e-619a-4010-b7e5-fd8081438201
- orderId: 111222333
HMAC_SHA256("68de6cbe-395d-49d0-85a7-ed5995794aef", "caae8a5e-619a-4010-b7e5-fd8081438201111222333")Example digest:
c17962392545337ad71755be23254090bebbe96fcbd9c348c91d2fe35696d1c4