📃Quick start: Payform

To start the integration with Finipay please follow these steps

1. Credentials

Good to know: Before you begin, make sure you have obtained the login and password from the administrator. These credentials are required to authenticate and successfully execute the API requests.

Please provide administrator with your work email

For example,

Authorization Type: Basic Auth

Test	Credentials
url	https://test.finipay.kg
login	PaymentTest
password	&9zx97)h$=JN(RhDH}=E

1. Request to make the test payment

Name	Type	Description
amount*	BigDecimal	Limitation: Cards/Mbank - 1 KGS Megapay - 5 KGS
serviceName*	String
callbackURL*	String	Your callback service
returnURL*	String	Implies which page the user will be redirected to after successful payment

Take into consideration

Minimal amount for paymemts via Cards/Mbank - 1 KGS

Minimal amount for Megapay - 5 KGS

Authorization Type: Basic Auth

To receive the payment page, please send POST request to the following endpoint:

Request

POST https://test.finipay.kg/api/v1.1.0/pay-form

Body

//method: POST 
//Content-Type: application/json 
//Authorization: Basic Auth
{ 
    "amount": "10", 
    "serviceName": "test", 
    "callbackUrl": "example.com", 
    "returnUrl": "example.com" 
}

returnURL implies which page the user will be redirected to after successful payment

Response

110 CREATED

{
    "code": "110",
    "message": "CREATED",
    "data": {
        "payFormUrl": "https://example.com",
        "orderNumber": "2b78ee66-5d4a-4e54-8e48-74940d5aadc1"
    }
}

400 Bad Request

 {
    "timestamp": "2025-03-10T17:44:13.037+00:00",
    "status": 400,
    "error": "Bad Request",
    "path": "/api/v1.1.0/pay-form"
} 

You will need to open the page by using the link payFormUrl that was created in the succesful response, in a new browser

// "payFormUrl": "https://example.com"

After redirecting to the page we see that test payment was created, here you can choose different types of payment

Finipay Payform

Limitation:

For payments by Mbank/Cards - 1 KGS

For Megapay - 5 KGS

Credentials for making test payment

MBANK

Номер телефона 996772140014

OTP - 0000

Megapay

Номер телефона 996555002108

OTP - 1441

Реквизиты карты

Номер карты 2200112611773794

Срок истечения - текущий месяц

CVV - любое значение

1. URL for Callback

Callback Mechanism for Retrieving Payment Status

The callback mechanism allows you to receive payment status updates in real-time. When a payment status changes, the system will send a callback notification to your specified endpoint.

In order to receive payment statuses you need to implement endpoint, which receive POST requests with the following body:


dateCreated format - LocalDateTime

Name	Type	Description
orderNumber*	String	The unique number of the transaction
amount*	BigDecimal	Amount of the transaction
currency	String	Сurrency codes according to the international standard ISO 4217
status*	String	Status of the transaction
dateCreated*	Date	Date of the transaction
requisite	String	Used only for QR payments
provider*	String	Provider (Cards, MegaPay, MBank)

Example

Body

//method: POST 
//Content-Type: application/json 
//Authorization: No auth
{
  "orderNumber": "ORD123456",
  "amount": 1500.75,
  "currency": "KGS",
  "status": "CHARGE",
  "dateCreated": "2025-05-20 14:30:45",
  "requisite": null,
  "provider": "MEGAPAY"
}

1. URL for receiving the status of the payment

Name	Type	Description
orderNumber*	String	The unique number of the transaction
provider*	String	Provider of the transaction

To receive status of the payment you should create request to this endpoint

Authorization Type: Basic Auth ( login and password, that were provided to you)

POST https://test.finipay.kg/api/v1.1.0/get-status

Request

Body

//method: POST
//Content-Type: application/json 
//Authorization: Basic Auth
{
    "orderNumber": "smt321321342321", 
    "provider": "Cards" 
}

Response

200

{
    "code": "200",
    "message": "PAYMENT_SUCCESS",
    "data": "CHARGE"
}

404

{    
    "code": "404",
    "message": "Платёж не найден",
    "data": null
}

By following this link you can find more status codes that can appear in the responses

✅Status Codes

1. Dashboard

After completing test payments, you can see all transaction information on Finipay Dashboard

Dashboard is a platform where all the information on your payments is displayed, you can see the schedule, analysis, number of payments by cards, by payment wallets or QR.

1. Credentials that were issued in the beginning should be entered for Login into the Dashboard.

Enter Login and Password (сredentials that were given to you)

On this page you can view transactions that you made earlier

Home Page of Dashboard Finipay

QR test payments does not show up in the dashboard