4. Widget Integration

4.1 Script Inclusion

<script src="https://cdnecozum.com/static/finrota-widget/v1.0.0/index.umd.js"></script>

4.2 Widget Initialization

FinrotaPay.init({
   token: "WIDGET_TOKEN",
   amount: 6650,
   currency: "TRY",
   mode: "modal",
   containerId: "payment-container",
   environment: "prod",

   onReady() {},
   onSuccess(data) {},
   onFail(error) {},
   onClose() {}
});

4.3 Widget Events

Event	Description
onReady	Checkout ready
onSuccess	Payment successful
onFail	Error occurred
onClose	User closed

5. Widget Payment Flow

In widget integration, the payment process is carried out as a hybrid between frontend (widget) and backend (merchant server).

1 – AccessToken is Purchased (Backend)

Merchant backend receives AccessToken via Finrota API.

POST /auth/api/token/connect

2 – WidgetToken is Generated (Backend)

A transaction-based WidgetToken is created using AccessToken.

• GET /b2c/widget/token
• Authorization: Bearer {AccessToken}

this token

• Unique for each payment
• Valid for 20 minutes

3 – Widget is Transferred to Frontend

WidgetToken generated by the backend is transmitted to the frontend.

4 – Widget Starts (Frontend)

FinrotaPay.init({
   token: "WIDGET_TOKEN",
   amount: 2750,
   currency: "TRY",
   mode: "modal",
   containerId: "payment-container",
   environment: "prod"
});

5 – User Enters Card Information (Widget UI)

• Card number
• CVV
• Expiration date
• Installment selection (comes dynamically)

At this stage

• Widget → Automatically calls endpoint /paymentOptions
• Lists suitable POS and installment options

6 – Widget PreparePayment Call (Internal)

widget when user presses payment button

• POST /b2c/widget/preparePayment

makes the call and

• Card information
• Selected installment (installmentToken)

forwarded to Finrota

As a result of this step
→ prepareToken is created

7 – onSuccess Event is Triggered (Frontend)

onSuccess(data) {

// payment ready

}

this event

• Does not mean that the payment has been completed
• Only indicates that the payment request is ready

8 – Request to Merchant Backend

The frontend sends the following information to its backend:

Area	Description
prepareToken	Token created for payment
amount	Transaction amount
other metadata	order information etc.

9 – Payment Endpoint Called (Backend)

Merchant backend

• POST /b2c/widget/payment
• Authorization: Bearer {AccessToken}

makes the call

10 – Payment Result

3D Secure Scenario

Response

{

"paymentType": "RedirectUrl",

"redirectTo": "3D\_URL"

}

Flow

1. Frontend → redirects the user
2. Bank → OTP verification
3. User → returns to returnUrl

Scenario without 3D

{

"paymentType": "DirectSale",

"success": true

}

→ Payment is completed directly

Critical Behaviors

Token Management

Token	Where to Use
AccessToken	Backend
WidgetToken	Frontend (widget init)
PrepareToken	Backend payment call

Event Management

Event	Real Meaning
onReady	UI ready
onSuccess	payment prepared (no withdrawals yet)
onFail	validation / system error
onClose	user logged out

Most Mistakes

• onSuccess → payment is thought to be completed
• Finishing the process without going to the backend
• Initing a widget with AccessToken
• Using WidgetToken instead of PrepareToken

6. Widget Token Generation

Endpoint: GET /b2c/widget/token

Header

Area	Type	Mandatory	Description
Authorization	string	✔	Bearer {AccessToken}

Response

Area	Type	Description
token	string	Token to be used for widget operation

Features

• Does not take parameters
• Valid for 20 minutes