KOPA Installments

KOPA is a payment gateway that enables customers to pay for orders in installments using their bank cards. This payment option is particularly popular in the Serbian market for higher-value purchases.

Overview

KOPA installment payments allow customers to:

• Split the order total across multiple monthly payments
• Use their existing Visa or Mastercard
• Complete purchases with 3D Secure authentication
• Pay the first installment at checkout

For merchants, KOPA provides:

• Higher average order values
• Increased conversion on expensive items
• Secure payment processing
• Automated recurring charges

Prerequisites

Before configuring KOPA, you need:

• A merchant account with KOPA
• Your KOPA API credentials
• Products that qualify for installment payments (typically higher-value items)

Obtaining KOPA Credentials

To set up a KOPA merchant account:

1. Contact KOPA to apply for a merchant account
2. Complete the merchant verification process
3. Receive your credentials:
   • Merchant ID
   • HMAC Key
   • API Username
   • API Password

Configuration Steps

Step 1: Access Payment Settings

1. Log in to your Mozhe dashboard
2. Navigate to your organization settings
3. Select the site you want to configure
4. Go to Settings > Shop > Payments

Step 2: Enable KOPA

1. In the payment gateway options, enable KOPA Installments
2. Enter your KOPA credentials:
   • Merchant ID: Your KOPA merchant identifier
   • : Your HMAC signing key (hexadecimal format)

Step 3: Configure Installment Options

Specify which installment plans to offer:

• 3 months
• 6 months
• 12 months
• 24 months

The available plans depend on your merchant agreement with KOPA.

Customer Payment Flow

When a customer selects KOPA installments at checkout:

1. Checkout Selection

Customer selects installment payment and chooses the number of installments.

2. Card Entry

Customer enters their card details on the secure payment form.

3. Bank Authentication

For Visa and Mastercard, customer is redirected to their bank for 3D Secure authentication.

4. Installment Confirmation

Customer confirms the installment plan:

• Total amount
• Number of installments
• Monthly payment amount
• First payment date

5. First Payment

The first installment is charged immediately. Order status changes to "Confirmed".

6. Subsequent Payments

KOPA automatically charges remaining installments monthly.

Transaction Types

PreAuth (Physical Products)

For physical products, KOPA uses a PreAuth flow:

1. PreAuth: Reserves the first installment amount
2. PostAuth: Captures funds when you ship the order
3. Recurring: KOPA handles subsequent monthly charges

This protects both you and the customer. If you cannot fulfill the order, you can void the PreAuth without charging the customer.

Auth (Digital Products)

For digital products, KOPA uses direct authorization:

1. Auth: Charges the first installment immediately
2. Delivery: Customer receives digital product
3. Recurring: KOPA handles subsequent monthly charges

3D Secure Requirements

KOPA requires 3D Secure authentication for Visa and Mastercard payments:

Dinacard is not currently supported for KOPA installment payments.

Handling 3D Secure Results

After 3D Secure authentication, customers return to your store with one of these results:

Mozhe automatically handles these results and updates the order status accordingly.

Managing Installment Orders

Viewing Installment Details

In the order details page, you can see:

• Total order amount
• Number of installments
• Amount per installment
• Payment status
• KOPA cycle ID

Refunding Installment Orders

To refund an installment order:

1. Go to the order in your dashboard
2. Click Refund
3. Enter the refund amount
4. KOPA processes the refund against remaining installments

Partial refunds adjust the remaining installment schedule.

Voiding Installment Orders

To void an order before shipment (PreAuth stage):

1. Go to the order in your dashboard
2. Click Void
3. The PreAuth is released
4. No charges are made to the customer

PostAuth for Physical Products

For physical products using PreAuth flow:

When to PostAuth

Run PostAuth when you are ready to ship the order:

1. Go to the order in your dashboard
2. Verify the order is ready to ship
3. Click Capture Payment or mark as shipped
4. KOPA captures the first installment
5. Recurring charges begin

PostAuth Deadline

You must PostAuth within the PreAuth validity period (typically 7-14 days). After this period, the authorization expires and you must request a new payment from the customer.

Saved Cards (MOTO Payments)

KOPA supports saved cards for returning customers:

How MOTO Works

1. Customer pays with a card that has completed 3D Secure
2. Card is saved securely in KOPA's system
3. For future orders, customer can pay without 3D Secure
4. Card must have a valid traceId from the original 3D Secure transaction

Requirements

• Card must have completed at least one 3D Secure authentication
• Card must be stored with KOPA's card management API
• MOTO is only available for cards with is3dAuth = true

Webhooks and Notifications

KOPA sends real-time notifications for:

• Payment authorized
• 3D Secure completed
• PostAuth captured
• Payment failed
• Refund processed

Mozhe automatically processes these notifications and updates order status.

Troubleshooting

Common Issues

"Bank details failed"

• Check that your KOPA credentials are correct
• Verify the order amount is valid
• Ensure your merchant account is active

"3D Authentication failed"

• Customer may have cancelled authentication
• Bank may have declined the transaction
• Try again or use a different card

"Card not eligible for installments"

• Card may not support installment payments
• Customer's bank may not participate
• Try a different card from a participating bank

"PostAuth failed"

• Authorization may have expired
• Card may have been blocked since authorization
• Insufficient funds at capture time

Error Codes

KOPA returns specific error codes for different issues:

Security Considerations

• Card data is encrypted using KOPA's PI Key
• HMAC signatures verify request integrity
• All transactions use secure HTTPS connections
• Mozhe never stores raw card numbers

Eligibility and Limits

KOPA installments are typically subject to:

• Minimum order value (varies by merchant agreement)
• Maximum order value (varies by merchant agreement)
• Product category restrictions
• Customer credit limits (determined by issuing bank)

Configure these limits in your KOPA merchant dashboard.

Next Steps

• Configure card payments for standard card payments
• Enable Cash on Delivery as an alternative
• Set up shipping methods