ePay API

https://kb.epay.bg/en
Admin
ePay.bg provides a quick and easy solution for accepting payments via the Internet, at an ATM, or in...
Tokens:40,383
Snippets:163
Trust Score:10
Update:1 year ago
Show doc for...
Tokens:
Raw
### ePay One Touch API - Getting Started and Usage

Source: https://kb.epay.bg/en/web/web

Provides guidance on getting started with the ePay One Touch API and details its usage, including options for registered and non-registered users.

```APIDOC
ePay One Touch API:
  - Getting Started
  - One Touch API
  - One Touch No Reg API
```

--------------------------------

### ePay One Touch API - Getting Started

Source: https://kb.epay.bg/en/billing/system/merchant-requirements

Provides initial guidance and setup instructions for the ePay One Touch API, designed for streamlined payment experiences.

```APIDOC
ePay One Touch API - Getting Started

Initial steps and prerequisites for integrating the One Touch API.
```

--------------------------------

### ePay.bg One Touch API Server Communication

Source: https://kb.epay.bg/en/onetouch/ot_pre

Details on communicating with ePay.bg servers, including entry points for testing and the concept of tokenization.

```APIDOC
Server Communication:
  - Entry points for testing purposes.
  - Tokenization.
```

--------------------------------

### Epay Billing Payment Confirmation Examples

Source: https://kb.epay.bg/en/billing/protocol

Provides examples of HTTP GET requests for confirming payments in the Epay billing system, covering full repayment, invoice payments, and partial repayments.

```APIDOC
GET /pay/confirm

Parameters:
  DATE: Request execution date (Mandatory)
  TYPE: Transaction type (e.g., BILLING, PARTIAL) (Mandatory)
  MERCHANTID: Merchant ID (Mandatory)
  IDN: Customer ID (Mandatory)
  CHECKSUM: HMAC-SHA-1 HEX of incoming data sorted by key (Mandatory)
  TOTAL: Amount in stotinki (Mandatory)
  TID: Transaction ID (Mandatory)
  VOICES: Invoice number (Optional, for invoice payments)

Response:
  STATUS: Status code (e.g., "00" for success) (Mandatory)
```

--------------------------------

### ePay One Touch API Services

Source: https://kb.epay.bg/en/faq

Documentation for the ePay One Touch API, including getting started, the main API, and the One Touch No Registration API.

```APIDOC
ePay One Touch API:
  Getting Started: https://kb.epay.bg/en/onetouch/ot_pre/
  One Touch API: https://kb.epay.bg/en/onetouch/onetouch/
  One Touch No Reg API: https://kb.epay.bg/en/onetouch/onetouch_no_reg/
```

--------------------------------

### ePay.bg Payment Response Examples

Source: https://kb.epay.bg/en/billing/protocol

Examples of ePay.bg payment responses. The first shows a general obligation response with basic details, and the second includes invoice details when multiple invoices are paid.

```json
{
"STATUS":"00",
"IDN":"12345",
"SHORTDESC":"Ivan Ivanov, Internet service",
"LONGDESC":":customer number: 12345\nNames: Ivan Ivanov\n        Internet service 01.03.2017 - 31.03.2017",
"AMOUNT":"16600",
"VALIDTO":"20170317"
}
```

```json
{
"STATUS":"00",
"IDN":"12345",
"SHORTDESC":"Ivan Ivanov, Internet service",
"LONGDESC":"customer number: 12345\nNames: Ivan Ivanov\n    Internet service 01.03.2017 - 30.04.2017",
"AMOUNT":"16600",
"VALIDTO":"20170317",
"INVOICES":[
{
"IDN":"12345.001",
"SHORTDESC":"Business Int. - 100 mbps BGN 78",
"AMOUNT":"7800",
"LONGDESC":"customer number: 12345\nNames: Ivan Ivanov\n    Internet service 01.03.2017 - 31.03.2017",
"VALIDTO":"20170331"
},
{
"IDN":"12345.002",
"SHORTDESC":"Business Int. - 150 mbps BGN 88",
"AMOUNT":"8800",
"LONGDESC":"customer number: 12345\nNames: Ivan Ivanov\n    Internet service 31.03.2017 - 30.04.2017",
"VALIDTO":"20170430"
}]
}
```

--------------------------------

### ePay.bg Payment Initiation Requests

Source: https://kb.epay.bg/en/billing/protocol

Examples of payment initiation requests for ePay.bg. One example shows a 'CHECK' type request for verification only, while the other shows a 'BILLING' type request for a payment that may follow.

```http
https://example.com/pay/init?IDN=12345&CHECKSUM=702de02734d25c719c6ccc87526478e851f6271d&MERCHANTID=0000334&TYPE=CHECK
```

```http
https://example.com/pay/init?IDN=12345&CHECKSUM=2736e17a183ed4b6923f7e0395b6c0523fdf0404&TID=20170317121650591535700020&MERCHANTID=0000334&TYPE=BILLING
```

--------------------------------

### ePay Billing API and File System

Source: https://kb.epay.bg/en/faq

Information on the ePay Billing API, including getting started, file system operations for loading/downloading files, and technical requirements for merchants.

```APIDOC
ePay Billing API:
  Getting Started: https://kb.epay.bg/en/billing/billing/
  File System:
    Loading/downloading files: https://kb.epay.bg/en/billing/system/fileupload/
    Technical Requirements: https://kb.epay.bg/en/billing/system/merchant-requirements/
  Billing API Protocol: https://kb.epay.bg/en/billing/protocol/
```

--------------------------------

### ePay.bg One Touch API Registration Process

Source: https://kb.epay.bg/en/onetouch/ot_pre

The process of registering an application for the ePay.bg One Touch API involves liaising with the sales department, defining a reply address, and obtaining an APPID and SECRET key.

```APIDOC
Application Registration:
  1. Liaison with the sales department.
  2. Defining the Reply address.
  3. Obtain APPID + SECRET.
```

--------------------------------

### ePay.bg REST API Communication

Source: https://kb.epay.bg/en/onetouch/ot_pre

Details the communication with ePay.bg servers using the JSON REST API, including testing entry points and response formats for successful and failed requests.

```APIDOC
System | Address | Description
---|---|---
API_BASE | <https://demo.epay.bg/xdev/api> | Primary communication address
API_BASE_WEB | <https://demo.epay.bg/xdev/mobile> | It is used in the TOKEN generation process

Upon successful request, you receive a response containing:
```json
{
"status":"OK"
/*and data as requested*/
}
```

In the case of a failed request, you receive:
```json
{
"status":"ERR",
"err":"SOME_ERROR_CODE",
"errm":"A message to display to the user"
}
```
```

--------------------------------

### File Loading Session Example

Source: https://kb.epay.bg/en/billing/system/fileupload

Provides a concrete example of the session format, breaking down the date and time components for clarity. This helps users understand how to construct a valid session identifier.

```text
Year: 2022
June
Day: 09
Hour: 10
Minutes: 32
Seconds: 22
```

--------------------------------

### Epay GET /pay/init API Endpoint

Source: https://kb.epay.bg/en/billing/protocol

Details the GET /pay/init API endpoint for initiating payments in the epay billing protocol. It outlines mandatory and optional input parameters, as well as the structure of the JSON output, including details for individual invoices.

```APIDOC
GET /pay/init:
  Description: Initiates a payment process for a customer obligation.

  Input Data:
    Parameter   | Description                                      | Optional
    ------------|--------------------------------------------------|----------
    IDN         | Customer ID                                      | Mandatory
    MERCHANTID  | Merchant ID                                      | Mandatory
    CHECKSUM    | HMAC-SHA-1 HEX of incoming data sorted by key    | Mandatory
    TYPE        | May contain 'CHECK' or 'BILLING'                 | Mandatory
    TID         | Does not appear in requests with TYPE=CHECK      | Optional

  Output Data:
    JSON Object | Description                                      | Optional
    ------------|--------------------------------------------------|----------
    STATUS      | On response other than '00', all other params ignored | Mandatory
    IDN         | Customer ID                                      | Mandatory
    AMOUNT      | Amount in stotinki. Total value for invoices.    | Mandatory
    VALIDTO     | Date until which the obligation is valid         | Mandatory
    SHORTDESC   | Brief customer information (one line)            | Mandatory
    LONGDESC    | Synthesized information for all invoices         | Mandatory
    INVOICES    | Not submitted if merchant does not allow invoice payments | Optional

  Output Data of array 'INVOICES' (for individual invoice payments):
    Data in INVOICES | Description                                      | Optional
    -----------------|--------------------------------------------------|----------
    IDN              | Subscriber number and invoice concatenated with a dot (IDN.INVOICE) | Mandatory
    AMOUNT           | Amount for the specific invoice                  | Mandatory
    VALIDTO          | Date until which the specific invoice is valid   | Mandatory
    SHORTDESC        | Short description for the specific invoice       | Mandatory
    LONGDESC         | Full description for the specific invoice        | Mandatory

  Good Practice:
    It is recommended that each invoice has its own description of the service or period it is associated with.
```

--------------------------------

### ePay.bg One Touch API Description

Source: https://kb.epay.bg/en/onetouch/ot_pre

The ePay.bg One Touch API facilitates communication with ePay.bg servers. Registered applications receive a secret key (SECRET) and a unique identifier (APPID) for server requests. The API enables payments from client bank cards to merchant accounts and checks the availability of payment instruments.

```APIDOC
ePay.bg One Touch API:
  Purpose: Interface for communication with ePay.bg servers.
  Registration:
    - Each registered application receives a secret key (SECRET) and a unique identifier (APPID).
    - APPID is sent with each request to ePay.bg servers.
  Functionality:
    - Enables payments from client bank cards to merchant accounts.
    - Allows availability checks for payment instruments (bank cards, ePay.bg accounts).
  Payment Methods:
    - No user profile in ePay.bg.
    - Via user profile in ePay.bg:
      - Customer authorizes connection between commercial application and ePay.bg profile.
      - Customer specifies payment account and card.
      - Payments can be made via ePay.bg website or mobile application.
```

--------------------------------

### ePay.bg API Methods

Source: https://kb.epay.bg/en/billing/protocol

Defines the available HTTP GET methods for interacting with the ePay.bg payment system, including payment initialization and confirmation.

```APIDOC
Method | Sample Request URL | Description
---|---|---
GET /pay/init | <https://example.com/pay/init> | Payment check
GET /pay/confirm | <https://example.com/pay/confirm> | Payment notification
```

--------------------------------

### ePay.bg GET /pay/confirm API Parameters

Source: https://kb.epay.bg/en/billing/protocol

Defines the input and output data for the GET /pay/confirm endpoint of the ePay.bg billing protocol. It details mandatory and optional parameters for confirming a transaction and the structure of the JSON output.

```APIDOC
GET /pay/confirm

Input data
Parameter | Description | Optional  
---|---|---  
IDN | Customer ID | Mandatory  
MERCHANTID | Merchant ID | Mandatory  
TID | Transaction ID | Mandatory  
DATE | Request execution date | Mandatory  
TOTAL | Amount in stotinki | Mandatory  
TYPE | May contain `BILLING` or `PARTIAL` | Mandatory  
INVOICES |  `IDN.INVOICE` - for more than one invoice, values are listed with commas | Optional  
CHECKSUM | HMAC-SHA-1 HEX of incoming data sorted by key | Mandatory  

Output data
JSON Object | Description  
---|---  
STATUS | All parameters except `STATUS` and its corresponding predefined value are ignored.  

Important
In the event of a problem occurring when confirming a transaction, the Operator automatically repeats it until receiving a correct response from the merchant. The identifier by which the merchant can understand that this is a repeat and not a new payment is the `TID` - it will always be the same for each repeat of the particular transaction.
```

--------------------------------

### ePay.bg Production and Demo Environment URLs

Source: https://kb.epay.bg/en/web/easypay

Provides the URLs for interacting with the ePay.bg EasyPay system in both production and demo environments. The GET method is used for accessing these endpoints.

```APIDOC
Production Environment:
GET | https://www.epay.bg/ezp/reg_bill.cgi

Demo Environment:
GET | https://demo.epay.bg/ezp/reg_bill.cgi
```

--------------------------------

### Example Merchant File with Pipeline Delimiter

Source: https://kb.epay.bg/en/billing/system/merchant-requirements

An example of a merchant-submitted file for billing obligations, using the pipeline symbol '|' as a delimiter. It includes header information and multiple subscriber records with their respective details.

```text
ANUM|NAME|ADDRESS|MONTH|YEAR|AMOUNT
202779050|Marin Marinov|city Sofia, gh. Mladost 1, bl. 388, app. 5|05|2015|430.25
131503520|Stefan Petrov Todorov|ul. Angel Kanchev N17, entrance A|06|2015|155.67
182703523|Ralitsa Borisova|6 Lyulin, bl. 513 entrance Ah, app. 24|10|2014|170.01
session=20151109114043

```

--------------------------------

### Epay Deposit Check API

Source: https://kb.epay.bg/en/billing/protocol

Details the GET /pay/init endpoint for checking deposit eligibility for a customer. Includes input parameters, output data, and important notes on merchant responses.

```APIDOC
GET /pay/init

Purpose: Checks if a deposit transaction (prepayment) can be made for a given customer.

Input Data:
  IDN: Customer ID (Mandatory)
  MERCHANTID: Merchant ID (Mandatory)
  CHECKSUM: HMAC-SHA-1 HEX of incoming data sorted by key (Mandatory)
  TYPE: Must be `DEPOSIT` (Mandatory)
  TID: Transaction ID (Mandatory)
  TOTAL: Amount in stotinki (Mandatory)

Output Data:
  STATUS: Status code. If not `00`, other fields are ignored (Mandatory).
  SHORTDESC: Short description (e.g., Customer Name) (Mandatory).
  LONGDESC: Detailed description, with carriage-encoded `\n` every 110 characters (Mandatory).

Important:
  - If STATUS is `00`, the Operator can start payment processing.
  - If payment cannot be made, return STATUS `96` or another relevant code.
```

--------------------------------

### Payment Notification Examples

Source: https://kb.epay.bg/en/web/notify

Provides examples of encoded data and their decoded content for various payment scenarios, including successful payments, expired payments, and payments with multiple invoices.

```APIDOC
Examples:

**Notification of payment made**
Encoded data: `encoded=SU5WT0lDRT0xNDAyOlNUQVRVUz1QQUlEOlBBWV9USU1FPTIwMjIwNjI5MTQ1MjU3OlNUQU49MDAwMDAwOkJDT0RFPTAwMDAwMAo%3D&checksum=46703be53c26149b0f28bcb1a38d1f8fdbb096de`
Decoded data: `INVOICE=1402:STATUS=PAID:PAY_TIME=20220629145257:STAN=000000:BCODE=000000`

**Notification with multiple INVOICEs**
`INVOICE=162319945:STATUS=PAID:PAY_TIME=20230626002551:STAN=036221:BCODE=036221     INVOICE=162322355:STATUS=PAID:PAY_TIME=20230626002551:STAN=036227:BCODE=036227`

**Notification for expired time**
Encoded data: `encoded=SU5WT0lDRT02MTY1NjQyOTc2MzpTVEFUVVM9RVhQSVJFRAo%3D&checksum=2cf0b859969c55c1ed2d16fcc4446d7455305010`
Decoded data: `INVOICE=61656429763:STATUS=EXPIRED`

**Other decoded values of `encoded`**
PAID: `INVOICE=123456:STATUS=PAID:PAY_TIME=YYYYMMDDhhmmss:STAN=[6 digits]:BCODE=[6 digits/letters]`
DENIED: `INVOICE=123457:STATUS=DENIED`
EXPIRED: `INVOICE=123457:STATUS=EXPIRED`
```

--------------------------------

### ePay One Touch API - Generate User Token

Source: https://kb.epay.bg/en/onetouch/onetouch

This section describes the process of generating a user token for the ePay One Touch API. It involves redirecting the user to ePay.bg for authorization and then retrieving the token. The `/api/start` endpoint is detailed, including its parameters, request example, and response handling.

```APIDOC
ePay One Touch API:
  Description: API for processing payments via One Touch.

  Endpoints:
    - GET /api/start: Redirects user for authorization to generate a token issuance key.
    - GET /api/code/get: Checks the result of the authorization.
    - GET /api/token/get: Retrieves the actual user token.
    - POST /payment/send/status: Endpoint for sending payment status updates.

  GET /api/start:
    Description: Redirects the user to ePay.bg hosted authorization page to generate a token issuance key. Users of ePay.bg can use their accounts for registration.
    Parameters:
      - APPID (string, Mandatory): Unique Application ID.
      - DEVICEID (string, Mandatory): Unique ID of the device (Vendor ID on iOS or ANDROID_ID on Android). For WEB, can use email or username.
      - KEY (int, Mandatory): A unique key against which the result of the query is checked.
      - UTYPE (int, Optional): Limits user type. 1 limits to ePay.bg registered users, 2 limits to payment card users.
      - DEVICE_NAME (string, Optional): Device Name.
      - BRAND (string, Optional): Device brand.
      - OS (string, Optional): Device Operating System.
      - MODEL (string, Optional): Device Model.
      - OS_VERSION (float, Optional): Operating system version.
      - PHONE (int, Optional): User's phone number.
    Important:
      - DEVICEID & KEY combination must be unique.
      - Recommended to send device data for convenient permission management.
    Request Example:
      https://demo.epay.bg/xdev/mobile/api/start?APPID=appid&DEVICEID=deviceid&KEY=uniq_key&UTYPE=2&DEVICE_NAME=myphone&BRAND=iPhone&OS=iOS&MODEL=iPhone5s&OS_VERSION=8.0&PHONE=1
    Response:
      User is redirected to specific URIs based on success or failure.
      For mobile apps:
        - REPLY_URI/authok: On success
        - REPLY_URI/authagain: On failure
      For web apps:
        - REPLY_ADDRESS/?ret=authok: On success
        - REPLY_ADDRESS/?ret=authagain: On failure
      Note: If REPLY_URI contains '://', response is 'authok|authagain=1'. Otherwise, 'reply_uri://authok|authagain ?msg=....'

  POST /payment/send/status:
    Description: Endpoint for sending payment status updates.
    (Further details for this endpoint are not provided in the input text.)
```

--------------------------------

### Session Format Example

Source: https://kb.epay.bg/en/billing/system/merchant-requirements

Illustrates the required format for the 'session' parameter, which is a date and time accurate to the second.

```text
session=20151109114043
```

--------------------------------

### ePay Payment Request via HTTP GET

Source: https://kb.epay.bg/en/web/easypay

Describes the process where a merchant sends an HTTP GET request to the ePay.bg URL to initiate a payment. ePay.bg then responds with a 10-digit payment code for the customer to use at an EasyPay checkout.

```APIDOC
Payment Request:
  Method: HTTP GET
  URL: ePay.bg URL (hidden from client)
  Response:
    - 10-digit payment code in EasyPay (for customer)
    - Sent in the same HTTP session.

Payment Notification:
  - ePay.bg monitors payment status.
  - Notifications sent to merchant regarding payment status.
  - Ports for notifications: 80 (HTTP), 443 (HTTPS).
  - Merchant must form a response to the notification.
  - If notification is repeated, the first response is repeated.
```

--------------------------------

### ePay.bg Decoded Notification Data Example

Source: https://kb.epay.bg/en/web/moneysend_easypay

Shows the decoded content of the 'encoded' parameter from an ePay.bg notification.

```APIDOC
INVOICE=123456:STATUS=PAID:PAY_TIME=20170715135123:STAN=000000:BCODE=000000
```

--------------------------------

### ePay.bg Parameter Details

Source: https://kb.epay.bg/en/billing/protocol

Explains specific ePay.bg API parameters like LONGDESC, INVOICE, TID, CHECKSUM, and TYPE, providing details on their formatting, content, and purpose within the system.

```APIDOC
`LONGDESC`:
A detailed description of the obligation. It is desirable to submit relevant information about the client - period of service, type of service, address, name, others. It is entered on a single line, with carriage-encoded `\n` every 110 characters. May contain the following substitutions:
  * `\t` eight spaces
  * `$` eight dashes
  * `\n` carriage return

`INVOICE`:
Invoices are a private term for protocol, they are not tied to actual legal data. They serve to distinguish accumulated more than one or different obligations of a given customer. Each individual obligation of this customer has a unique invoice.
`TID`:
A unique identifier for each individual transaction. In case of a problem with a given transaction, it is possible for the Operator to send more than one repetition until receiving a correct response from the merchant. The repetition is always the same. TID is formed by:
  * `DATE` Date and time, accurate to the second. The time can be from 00:00:00 to 23:59:59
  * `STAN` Service information of the Operator - not processed
  * `AID` Payment Source. They are divided into two types - 70002x and 7001xx are cash payments from Izipey.

All other sources can be accepted as ePay.bg electronic channels
`CHECKSUM`:
hmac_sha1_hex (`request_data`, `SECRET`)
  * `request_data` includes all incoming data, concatenated with NEWLINE (`\n`) lines containing a parameter and its corresponding value, concatenated. The data is sorted in ascending order.
  * `SECRET` is provided by the Operator.

`TYPE`:
The field can contain one of the following values, depending on the request type:
  * `CHECK` Obligation check only, no payment will follow
  * `BILLING` When checking or paying an obligation
  * `PARTIAL` When notification of partial payment of an obligation
  * `DEPOSIT` When prepaying a service
```

--------------------------------

### Response Examples - OK, ERR, NO

Source: https://kb.epay.bg/en/web/notify

Illustrates the merchant's response format for acknowledging payment notifications, indicating errors, or specifying non-existent invoices.

```APIDOC
Response Examples:
`INVOICE=123456:STATUS=OK`
`INVOICE=123457:STATUS=ERR`
`INVOICE=123458:STATUS=NO`

Error description example: `ERR=a description of the global error (e.g. invalid CHECKSUM)`
```

--------------------------------

### ePay.bg API Parameters

Source: https://kb.epay.bg/en/billing/protocol

Lists and describes the parameters used in ePay.bg API requests, including customer identification, merchant details, invoice information, descriptions, amounts, dates, transaction IDs, and request types.

```APIDOC
Parameter | Data Type | Description | Addition
---|---|---|---
IDN | varchar(64)n | Customer ID | Provided by merchant
MERCHANTID | varchar(8)n | Merchant ID | Provided by the Operator
INVOICE | varchar(64)ans | Invoice number | In case of split payment of liabilities
INVOICES | varchar(490)ans | Array of invoice numbers | On split payment of liabilities
SHORTDESC | varchar(40)Ans | Short Obligation Description | One line encoded in UTF-8
LONGDESC | varchar(4000)Ans | Command Detail | More than one line encoded in UTF-8
AMOUNT | int | Amount in stotinki | Output parameter on validation
VALIDTO | varchar(8)n | Date due | YYYYMMDD
STATUS | varchar(3)n | Commitment Status Code | Result or error code
TID | varchar(26)n | Transaction ID | DATE(14)n + STAN(6)n + AID(6)n
DATE | varchar(14)n | Query execution date | YYYYMMDDhhmmss
TOTAL | int | Amount in stotinki | Input parameter at checkout
TYPE | varchar(7)a | `CHECK`, `BILLING`, `PARTIAL`, `DEPOSIT` | Depending on the request type
CHECKSUM | HEX | On incoming data sorted by key | IDNxxxx\nMERCHANTIDxxxx\
```

--------------------------------

### Epay CHECKSUM Generation

Source: https://kb.epay.bg/en/billing/protocol

Explains the method for generating a CHECKSUM using HMAC-SHA-1, including the format of the request data and an example.

```APIDOC
CHECKSUM = hmac_sha1_hex (request_data, SECRET)

request_data: Must include all incoming data, sorted in ascending order before encoding.

Example request_data:
IDN12345
MERCHANTID0000334
TID20170317121650591535700020
TYPEBILLING

```

--------------------------------

### ePay API Registration Steps

Source: https://kb.epay.bg/en/index

Steps required to register and use the ePay API. This involves registering as a legal entity on the ePay.bg platform and submitting a 'Request to register as a merchant' through the 'Settings' menu.

```APIDOC
ePay API Registration:

1. Register as a Legal Entity:
   - Visit: <https://epay.bg/>

2. Submit Merchant Registration Request:
   - Navigate to the "Settings" menu within your ePay.bg profile.
   - Select and submit the "Request to register as a merchant" option.

Note: After registration, the ePay commercial team will contact you.
```

--------------------------------

### Get Authorization Code

Source: https://kb.epay.bg/en/onetouch/onetouch

Retrieves an authorization code required for subsequent token issuance. The request involves providing application and device identifiers, along with a key from a previous start request. It outlines minimum/maximum execution times and best practices for request frequency.

```APIDOC
GET /api/code/get

Parameters:
  APPID (string): Unique Application ID (Mandatory)
  DEVICEID (string): Unique device identifier (Mandatory)
  KEY (int): Unique key from previous request [/api/start](https://kb.epay.bg/en/onetouch/onetouch/#get-apistart) (Mandatory)

Request Example:
https://demo.epay.bg/xdev/api/api/code/get?APPID=appid&DEVICEID=deviceid&KEY=uniq_key

Response (Successful):
{
"status":"OK",
"code":"token_code"
}

Response (Failed):
{
"status":"ERR",
"err":"SOME_ERR",
"errm":"error to show to user"
}

Response Parameters:
  status (string): Request status
  code (string): Used in request to get token
```

--------------------------------

### Merchant Registration Process

Source: https://kb.epay.bg/en/billing/system/fileupload

Steps to register as a merchant on the ePay.bg platform. This involves accessing the registration portal, selecting the merchant registration option, and filling in the required details.

```APIDOC
Merchant registration:
  1. Register at the address https://mrcs.easypay.bg/ from the "New registration" option
  2. Press the "Registration" button
  3. Select the "New Merchant Registration" option
  4. Fill in all the data and press "View"
```

--------------------------------

### Simulate EasyPay Payment (Demo)

Source: https://kb.epay.bg/en/web/easypay

Demonstrates how to simulate a payment made with a 10-digit code at an EasyPay office using the demo environment. It specifies the ACTION and IDN parameters required for the simulation.

```APIDOC
https://demo.epay.bg/ezp/pay_bill.cgi?ACTION=PAY&IDN=1234567890

Parameters:
- ACTION (PAY): Simulates Payment (Mandatory)
- IDN (int): The resulting payment code (Mandatory)
```

--------------------------------

### ePay Online Payment - General Information

Source: https://kb.epay.bg/en/web/web

Provides general information about the ePay.bg online payment system, defining key terms like 'Client' and 'Merchant'. It also directs users to download demo packages for accessing cited files.

```APIDOC
Online Payment - General Information:
  - Client: The end user of the service.
  - Merchant: A legal entity that has concluded a contract with ePay.bg.
  - Demo Package: Files cited in the documentation can be downloaded from the "Demo package" link under the login button at https://demo.epay.bg/
```

--------------------------------

### Epay Deposit Payment Notification API

Source: https://kb.epay.bg/en/billing/protocol

Describes the GET /pay/confirm endpoint for notifying the merchant of a completed deposit payment. Specifies input parameters and the expected response format.

```APIDOC
GET /pay/confirm

Purpose: Notifies the merchant of a deposit payment made.
Note: Payment notifications cannot be declined. The merchant must respond with STATUS `00` or `94`.

Input Data:
  IDN: Customer ID (Mandatory)
  MERCHANTID: Merchant ID (Mandatory)
  TID: Transaction ID (Mandatory)
  DATE: Request execution date (Mandatory)
  CHECKSUM: HMAC-SHA-1 HEX of incoming data sorted by key (Mandatory)
  TYPE: Must be `DEPOSIT` (Mandatory)
  TOTAL: Amount in stotinki (Mandatory)

Output Data:
  STATUS: Status code. All other parameters are ignored (Mandatory).
```

--------------------------------

### ePay API FAQ - Commercial Questions

Source: https://kb.epay.bg/en/faq

Answers to frequently asked commercial questions about becoming a merchant, registration process, commission fees, account fees, contract requirements, and payment collection.

```APIDOC
ePay API FAQ - Commercial Questions:
  What do I need to become a merchant?: https://kb.epay.bg/en/faq/#what-do-i-need-to-become-a-merchant
  How do I register at ePay.bg?: https://kb.epay.bg/en/faq/#how-do-i-register-at-epaybg
  How do I register as a merchant? Where is the "Request to register as a merchant"?: https://kb.epay.bg/en/faq/#how-do-i-register-as-a-merchant-where-is-the-request-to-register-as-a-merchant
  What is your commission?: https://kb.epay.bg/en/faq/#what-is-your-commission
  Does the account I'm opening have monthly fees?: https://kb.epay.bg/en/faq/#does-the-account-im-opening-have-monthly-fees
  What are the additional documents to the contract?: https://kb.epay.bg/en/faq/#what-are-the-additional-documents-to-the-contract
  Where do I send the contract? Who should I address it to?: https://kb.epay.bg/en/faq/#where-do-i-send-the-contract-who-should-i-address-it-to
  How can I connect my site to your system?: https://kb.epay.bg/en/faq/#how-can-i-connect-my-site-to-your-system
  How can my customers pay their monthly bills through your system?: https://kb.epay.bg/en/faq/#how-can-my-customers-pay-their-monthly-bills-through-your-system
  How do I get the accumulated amount in my account?: https://kb.epay.bg/en/faq/#how-do-i-get-the-accumulated-amount-in-my-account
  To what period of time are the collected amounts transferred? Can it be changed?: https://kb.epay.bg/en/faq/#to-what-period-of-time-are-the-collected-amounts-transferred-can-it-be-changed
  Where do I download my invoices from?: https://kb.epay.bg/en/faq/#where-do-i-download-my-invoices-from
  How is your commission fee deducted?: https://kb.epay.bg/en/faq/#how-is-your-commission-fee-deducted
  How can I reverse a payment? Is it worth anything to me?: https://kb.epay.bg/en/faq/#how-can-i-reverse-a-payment-is-it-worth-anything-to-me
```

--------------------------------

### ePay Technical Documentation Links

Source: https://kb.epay.bg/en/index

Links to various ePay technical documentation resources for developers, including Web API, One Touch API, and Billing API.

```APIDOC
ePay Technical Documentation:

- ePay WEB API: https://kb.epay.bg/en/web/web/
- ePay One Touch API: https://kb.epay.bg/en/onetouch/onetouch/
- ePay Billing API: https://kb.epay.bg/en/billing/billing/
```

--------------------------------

### PHP Example for Request Encoding and Checksum Generation

Source: https://kb.epay.bg/en/web/expiration_time

Provides a PHP example for base64 encoding payment data and generating a checksum using HMAC-SHA1 for the epay.bg API request. The hmac function implementation is available in demo.php.

```PHP
# Encoding the request
$ENCODED=base64_encode('DATA');

# Generate checksum
$CHECKSUM=hmac('sha1',$ENCODED,$secret);

# hmac function code can be seen in demo.php
```

--------------------------------

### EasyPay Money Transfer API Endpoints

Source: https://kb.epay.bg/en/web/moneysend_easypay

Provides the URLs for sending money transfer requests via the EasyPay API in both production and demo environments.

```APIDOC
Production Environment:
  Method: GET
  URL: https://www.epay.bg/ezp/send.cgi

Demo Environment:
  Method: GET
  URL: https://demo.epay.bg/ezp/send.cgi
```

--------------------------------

### ePay.bg Sample Payment Request Generation

Source: https://kb.epay.bg/en/web/web

Provides a sample PHP code snippet demonstrating how to construct the payment request data, encode it, generate a checksum, and create an HTML form for submission to ePay.bg.

```PHP
# '' for EOL (def. is "\n")
DATA=
MIN=1000000000
EMAIL=a@merch.bg
INVOICE=123456
AMOUNT=22.80
CURRENCY=BGN
EXP_TIME=01.08.2020
DESCR=Test
ENCODING=utf-8

$ENCODED=base64_encode(DATA);

# Generate checksum
$CHECKSUM=hash_hmac('sha1', $ENCODED, $secret);

<form action="https://www.epay.bg/" method="post">
<input type="hidden" name="PAGE" value="credit_paydirect">
<input type="hidden" name="LANG" value="[LANG]">
<input type="hidden" name="ENCODED" value="[$ENCODED]">
<input type="hidden" name="CHECKSUM" value="[$CHECKSUM]">
<input type="hidden" name="URL_OK" value="http://...">
<input type="hidden" name="URL_CANCEL" value="http://...">
<input type="submit" value="Pay">
</form>
```

--------------------------------

### ePay.bg Communication Scheme - Production Environment

Source: https://kb.epay.bg/en/web/web

Details on how to communicate with the ePay.bg system in a production environment, including the POST addresses for Bulgarian and English versions and essential requirements for service activation.

```APIDOC
Method | Address | Description
---|---|---
POST | https://www.epay.bg/ | Bulgarian language version
POST | https://www.epay.bg/en/ | English language version
```

--------------------------------

### Amount Format Example

Source: https://kb.epay.bg/en/billing/system/merchant-requirements

Demonstrates the accepted formats for the payment amount, allowing either a period or a comma as a decimal separator.

```text
155.67
```

```text
155,67
```

--------------------------------

### Download Reference File

Source: https://kb.epay.bg/en/billing/system/fileupload

Instructions on how to download a reference file from the ePay system. This file may contain important data for reconciliation or reporting purposes.

```APIDOC
Download reference file
```

--------------------------------

### Regular File Submission Example

Source: https://kb.epay.bg/en/billing/system/merchant-requirements

Demonstrates the structure and content of a standard file submitted by a merchant, including subscriber details and a session identifier.

```csv
1001|Ivan Madzharov|Sofia, gh. Ovcha Cupel 3|50|Yoga course
1002|Petya Mihailova|ul. Ivan Vazov 17, Office Building 1|113.50|Yoga course
1003|Andrei Vassilev| Borovo, bl. 40A|17|Yoga course
session=20150301114043
```

--------------------------------

### ePay Billing API - File System Operations

Source: https://kb.epay.bg/en/web/web

Describes file system operations for the ePay Billing API, including loading/downloading files and technical requirements for merchants.

```APIDOC
ePay Billing API - File System:
  - Loading/downloading files
  - Technical Requirements
```

--------------------------------

### ePay API FAQ - Technical Questions

Source: https://kb.epay.bg/en/faq

Answers to frequently asked technical questions regarding the ePay API, such as tracking requests, locating secret keys and customer numbers, managing multiple websites, adding notification URLs, creating demo accounts, and previewing the payment page.

```APIDOC
ePay API FAQ - Technical Questions:
  How do I track requests from my website, which are paid and which are not?: https://kb.epay.bg/en/faq/#how-do-i-track-requests-from-my-website-which-are-paid-and-which-are-not
  Where is my secret key located?: https://kb.epay.bg/en/faq/#where-is-my-secret-key-located
  Where is my customer number?: https://kb.epay.bg/en/faq/#where-is-my-customer-number
  Can I receive payments from two different websites in one account?: https://kb.epay.bg/en/faq/#can-i-receive-payments-from-two-different-websites-in-one-account
  How do I add a notification URL?: https://kb.epay.bg/en/faq/#how-do-i-add-a-notification-url
  How do I create a Demo environment account?: https://kb.epay.bg/en/faq/#how-do-i-create-a-demo-environment-account
  How to preview the payment page in English?: https://kb.epay.bg/en/faq/#how-to-preview-the-payment-page-in-english
```

--------------------------------

### ePay API Changelog

Source: https://kb.epay.bg/en/faq

Link to the changelog for the ePay API.

```APIDOC
ePay API Changelog: https://kb.epay.bg/en/changelog/
```

--------------------------------

### Generate Bank Transfer Request - Perl

Source: https://kb.epay.bg/en/web/bank_transfer

Example code in Perl to encode the payment request data using base64 and generate a checksum using HMAC-SHA1.

```Perl
# Encoding the request
$ENCODED=encode_base64('DATA','');# '' for EOL (def. is "\n")   

# Generate checksum
$CHECKSUM=hmac_hex($ENCODED,$secret,&sha1);
```

--------------------------------

### Generate Bank Transfer Request - PHP

Source: https://kb.epay.bg/en/web/bank_transfer

Example code in PHP to encode the payment request data using base64 and generate a checksum using HMAC-SHA1.

```PHP
# Encoding the request
$ENCODED=base64_encode('DATA');

# Generate checksum
$CHECKSUM=hmac('sha1',$ENCODED,$secret);

# hmac function code can be found in demo.php
```

--------------------------------

### ePay.bg API Endpoints

Source: https://kb.epay.bg/en/web/vnbel

Lists the URLs for ePay.bg payment processing in both production and demo environments.

```APIDOC
Production environment
Method | URL  
---|---
GET | <https://www.epay.bg/ezp/reg_vnbel.cgi>

Demo environment
Method | URL  
---|---
GET | <https://demo.epay.bg/ezp/reg_bill.cgi>
```

--------------------------------

### Perl Example for Request Encoding and Checksum Generation

Source: https://kb.epay.bg/en/web/expiration_time

Demonstrates how to encode payment data using base64 and generate a checksum using HMAC-SHA1 in Perl for the epay.bg API request.

```Perl
# Encoding the request
$ENCODED=encode_base64('DATA','');# '' for EOL (default is "\n")

# Generate checksum
$CHECKSUM=hmac_hex($ENCODED,$secret,&sha1);
```

--------------------------------

### ePay.bg STATUS Codes

Source: https://kb.epay.bg/en/billing/protocol

Provides a list of status codes returned by the ePay.bg API, detailing their meaning and the methods they apply to, crucial for understanding transaction outcomes.

```APIDOC
STATUS | Description | Returnable method
---|---|---
00 | OK | pay_init and pay_confirm
13 | Invalid amount (on deposit) | pay_init
14 | Invalid subscriber number (IDN) | pay_init
62 | No Obligation | pay_init
80 | Temporarily unable to execute | pay_init
93 | Invalid checksum (CHECKSUM) | pay_init and pay_confirm
94 | Repeat of already received notification | pay_confirm
96 | General error | pay_init and pay_confirm
```

--------------------------------

### EasyPay Money Transfer Request Parameters

Source: https://kb.epay.bg/en/web/moneysend_easypay

Details the mandatory and optional parameters required for initiating a money transfer request through the EasyPay API, including encoding and checksum requirements.

```APIDOC
Request Parameters:
  ENCODED: Base64-encoded (RFC 3548) payment request. EOL=" ". Mandatory.
  CHECKSUM: Checksum on ENCODED, generated as HMAC with SHA-1 algorithm and merchant SECRET word. Mandatory.

Parameters within ENCODED:
  MIN (int): Customer Identification Number (CIN). Mandatory.
  INVOICE (int): Invoice ID; must be unique for each request. Mandatory.
  AMOUNT (float): Valid amount > 0.01. Mandatory.
  RCPT_NAME (string): Recipient name up to 100 characters. CP1251 characters if no other ENCODING is supplied. Mandatory.
  RCPT_PID (int): PID of recipient. Mandatory.
  RCPT_ID_NO (int): Recipient's personal document number (identity card/driver's license/passport). Mandatory.
  RCPT_ID_DATE (date): Issue date of recipient's personal document (DD.MM.YYYY). Mandatory.
  RCPT_ADDRESS (string): Recipient address up to 256 characters. CP1251 characters if no other ENCODING is supplied. Optional.
  RCPT_PHONE (int): Recipient phone up to 16 characters. Optional.
  CURRENCY (string): Accepted currencies are BGN, USD, or EUR. Defaults to BGN. Optional.
  DESCR (string): Transfer description up to 100 characters. CP1251 characters if no other ENCODING is supplied. Optional.
  ENCODING (string): utf-8 or CP1251. Defaults to CP1251. Optional.

Additional Information:
  INVOICE: Used to differentiate merchant requests.
  ENCODING: Determines character encoding for description fields. If not provided, CP1251 is assumed.
  Recipient data (Personal Identification Number and/or Personal Identification Document number) is mandatory. If a personal document is provided, its issue date is also required.
```

--------------------------------

### ePay.bg Merchant Integration

Source: https://kb.epay.bg/en/faq

To integrate your site with the ePay.bg system, you will receive a Secret Key and CIN after your request is activated. These credentials are required for integrating with the WEB API in a production environment.

```APIDOC
Site Integration:
  1. Activate your request with ePay.bg.
  2. Upon activation, you will receive a Secret Key and CIN.
  3. Use the Secret Key and CIN to integrate with the ePay.bg WEB API for production environment.
  Reference: https://kb.epay.bg/web/web/#production-environment
```
Tokens:
Raw