PayGate Integration Guide

What is PayGate?

PayGate is a complete automated payment system by ENTERSOFTONE designed to streamline the collection of invoices, documents, and general debts. It acts as a bridge between Issuers (businesses that need to collect payments) and Payers (recipients who owe money), leveraging the Greek banking infrastructure (DIAS) to enable secure, automated transactions.

Core Concepts

Before diving into the integration, it's important to understand the key actors and concepts:

How It Works — The Big Picture

1. The Issuer sends a payment request through the RestAPI

2. The Payer receives an email (or link) with the payment details

3. The Payer clicks the link, reviews the debt, selects their bank, and pays

4. The Issuer is notified automatically and their system is updated

Key Features

• Automated Payment Collection — Create and distribute payment requests programmatically

• Multiple Payment Methods — IRIS instant payments and RF payment codes

• Flexible Payment Options — Fixed, variable, open amount, and split payment support

• Real-time Notifications — Callback URLs and polling APIs for instant updates

• Refund Support — Full and partial refunds through DIAS

• Easy Registration — Automated Eurobank onboarding for partner platforms

• ERP-Agnostic — Integrates with any system via RestAPI

Who Should Use This API?

• ERP/CRM developers automating invoice collection workflows

• e-Commerce platforms embedding payment links in order flows

• Partner platforms onboarding their merchants to PayGate via Easy Registration

• Financial integrators building reconciliation pipelines

Authentication Overview

PayGate uses a three-step authentication model that separates initial registration from ongoing API access. This design ensures that credentials are securely provisioned and that API tokens are short-lived.

Authentication Flow

Step 1: Activation (One-Time)

Activation is performed once per issuer. It registers your system with PayGate and returns an applicationKey that acts as a permanent credential.

What you need:

• activateGuid — Your license key, provided by the PayGate administrator upon service enrollment

• hostName — The hostname of the calling machine

What you get:

• applicationKey — A permanent key used in all subsequent token requests

Step 2: Token Generation (Recurring)

Before making any payment-related API call, you must obtain a short-lived access token. Tokens expire after 50 minutes, so your integration should handle token refresh proactively.

What you need:

• activateGuid — Your license key

• hostName — Can be any value; the company name is recommended

• applicationKey — From the Activate step

What you get:

• access_token — A Bearer token used in the Authorization header of all subsequent calls

Token Management Best Practices

• Cache the token and reuse it for multiple calls within the 50-minute window

• Track the token's creation time and refresh it proactively before expiry (e.g., at 45 minutes)

• Handle 401 responses by requesting a new token and retrying the call

• Never hardcode tokens — always generate them dynamically

Payment Request Overview

A Payment Request is the core entity in PayGate. It represents a demand for payment from an Issuer to a Payer. Understanding its full lifecycle is essential for a robust integration.

Payment Request States

Creating a Payment Request

Understanding Payment Ways

The PaymentWay field controls how much flexibility the payer has when making a payment. Choosing the right option depends on your business scenario.

Understanding Redirect Types & TTL

The RedirectType field, combined with TimeToLive and DueDate, controls the payment link's behavior and what status information is available.

The Payer's Journey

Once a payment request is created, the payer goes through the following experience:

Key points about the payer experience:

• The payer does not need to be registered with PayGate

• The payment form is pre-filled — the payer doesn't need to enter amount, IBAN, or reference

• Payment approval uses the bank's own security (e.g., OTP)

• The payer can pay via IRIS (instant) or RF codes (standard bank transfer)

Strategy 1: Callback URL (Push — Recommended Primary)

When you create a payment request with a CallBackUrl, PayGate will POST to that URL whenever a payment action occurs. This is the fastest way to learn about payments.

What you receive in the callback:

• paymentRequestId — To match against your records

• amount — The amount paid

• paymentStatus — 1 for successful payments

• myBankOrderId — IRIS Order ID (if applicable)

• rf — RF code (if applicable)

• paymentDate — When the payment was completed

Your endpoint must respond with:

or

Strategy 2: Status Polling (Pull — Recommended Fallback)

For cases where callbacks may fail (network issues, server downtime), or for reconciliation purposes, you can poll PayGate for payment status.

Recommended Notification Architecture

Best practices:

1. Primary: Implement a Callback URL endpoint to receive real-time notifications

2. Fallback: Run a periodic reconciliation job (e.g., every 15–30 minutes) that polls the Status API for any payments your callback might have missed

3. Idempotency: Always check if you've already processed a payment before applying it (use paymentRequestId + paymentId as a unique key)

Refund Overview

PayGate supports refunds for completed payments through the DIAS banking system. Refunds can be full (entire payment amount) or partial (a portion of the payment). The refund process is asynchronous — you submit a request and then poll for the result.

Refund Flow

Refund States

Refund Rules & Constraints

Refund Reason Codes

When submitting a refund, you must provide a reason code. FOCR (FollowingCancellationRequest) is the most commonly used and is recommended for testing.

Easy Registration Overview

Easy Registration is designed for partner platforms that want to onboard their merchants to PayGate automatically. It integrates with Eurobank's Easy Registration service to handle the bank authentication and account setup without manual intervention.

When to Use Easy Registration

• You are a software platform (ERP, CRM, e-commerce) that serves multiple businesses

• You want your merchants to accept payments through PayGate under your partner umbrella

• You need automated onboarding without requiring merchants to contact PayGate directly

Easy Registration Flow

Step-by-Step Breakdown

Important Notes

General Error Structure

All error responses follow a consistent pattern. For payment-related calls, errors are returned as an array of descriptive strings:

For cancel and refund operations, errors use code + label format:

Common Error Scenarios & Resolution

API Base URLs

Testing Checklist

• [ ] Successfully activate and obtain applicationKey

• [ ] Generate and refresh tokens correctly

• [ ] Create a payment request with PaymentWay = 1 (fixed amount)

• [ ] Create a payment request with PaymentWay = 2 (variable amount)

• [ ] Verify payment link opens and displays correct details

• [ ] Receive callback notification on your endpoint

• [ ] Poll payment status and verify response

• [ ] Cancel a pending payment request

• [ ] Submit a refund and poll for completion

• [ ] Test batch payment creation

• [ ] Test token expiry and refresh handling

• [ ] Test error scenarios (invalid VRN, expired link, etc.)