Skip to content

ePay One Touch API

Before you continue:

  1. You must have contacted our Commercial Department
  2. You must have received an APPID

Generate user Token

A unique user token is required to execute the requests.

Its generation requires the user to enter their payment card number (bank, credit, debit) on the tokenization page hosted at ePay.bg.

Info

Users of https://epay.bg/ have a wider range of possibilities that can be performed by the application and need to authorize it by logging in with a username and password on the tokenization page.

ePay One Touch token

The sequence for generating a user token is as follows:

Step Request
1. The user is redirected to a browser for registration or authorization GET API_BASE_WEB/api/start
2. Checking the result of the authorization GET API_BASE_WEB/api/code/get
3. Actual receipt of token GET API_BASE_WEB/api/token/get

GET /api/start

Method System
GET API_BASE_WEB

Redirects the user to ePay.bg hosted authorization page and entered the card data to generate a token issuance key. Users of ePay.bg can use their accounts for registration.

Parameter Type Description Optionality
APPID string Unique Application ID Mandatory
DEVICEID string Unique ID of the device.
Vendor ID on iOS or ANDROID_ID on Android.
If the application is WEB, you can use email or username.		 Mandatory
KEY int A unique key against which the result of the query is checked Mandatory
UTYPE int When not passed as a parameter, there is no restriction on the user type.
UTYPE=1 - Limits the application to work only with users registered in ePay.bg
UTYPE=2 - Limits the application to work only with a payment card (credit, debit, bank)		 Optional
DEVICE_NAME string Device Name Optional
BRAND string Device brand Optional
OS string Device Operating System Optional
MODEL string Device Model Optional
OS_VERSION float Operating system version Optional
PHONE int User's phone number Optional

Important

DEVICEID & KEY combination must be unique.

It is recommended to also send device data to the user, for more convenient permission management later.

Request

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

Depending on the authorization result, the user will be redirected to links to open your mobile application or lead to your WEB page.

The response is the same for test and production environments.

Address Description
REPLY_URI/authok On success
REPLY_URI/authagain On failure

More information about REPLY_URI in mobile applications

If the address you set for reply contains :// you will recieve authok|authagain=1

If the address does not contain :// - we will return reply_uri://authok|authagain ?msg=....

Address Description
REPLY_ADDRESS/?ret=authok On success
REPLY_ADDRESS/?ret=authagain On failure

GET /api/code/get

Method System
GET API_BASE

The authorization output is checked and a token issuance code is obtained.

Minimum/Maximum time to execute /code/get request

  • You don't need to wait for the user to return to the application/page to submit the request.

  • In the absence of a response containing code within the 15-minute session, you must run the request for an additional 15 minutes - 30 minutes in total. In cases where there is a delay in processing by the financial institutions, this way you will ensure that your users will not be charged 1 BGN without being able to get the token generation code.

  • It is a good practice to spread requests to 20-30 seconds.

Parameter Type Description Optionality
APPID string Unique Application ID Mandatory
DEVICEID string Unique device identifier Mandatory
KEY int Unique key from previous request /api/start Mandatory

Request

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

Response

1
2
3
4
{
    "status": "OK",
    "code": "token_code"
}
Parameter Type Description
status string Request status
code string Used in request to get token 
1
2
3
4
5
{
    "status":"ERR",
    "err":"SOME_ERR",
    "errm":"error to show to user"
}

The authorization failed. It may be rejected or incomplete.

GET /api/token/get

Method System
GET API_BASE

Actual receipt of token.

Parameter Type Description Optionality
APPID string Unique Application ID Mandatory
DEVICEID string Unique device identifier Mandatory
CODE string Parameter code from request response /api/code/get Mandatory

Request

https://demo.epay.bg/xdev/api/api/token/get?APPID=appid&DEVICEID=deviceid&CODE=token_code

Response

1
2
3
4
5
6
7
8
{
    "status": "OK",
    "TOKEN": "token_string",
    "EXPIRES": 1720188520,
    "KIN": "client uniq number",
    "USERNAME": "client username",
    "REALNAME": "client real name"
}
Parameter Type Description
status string Request status
TOKEN string Unique access user ID
EXPIRES int unixtime Token validity
KIN string Customer identification number (for ePay.bg users)
USERNAME string Username (for ePay.bg users)
REALNAME string User names (for ePay.bg users)

Token Validity

The token is valid until explicitly invalidated by submitting a request to the One Touch API.

All subsequent requests must contain APPID, DEVICEID, and TOKEN.

Deactivate Token

What happens after token deactivation

After this request, the token is disabled and the user will not be able to use the application.

GET /api/token/invalidate

Method System
GET API_BASE
Parameter Type Description Optionality
APPID string Unique Application ID Mandatory
DEVICEID string Unique device identifier Mandatory
TOKEN string Unique access user ID Mandatory

Request

https://demo.epay.bg/xdev/api/api/token/invalidate?APPID=appid&DEVICEID=deviceid&TOKEN=token

1
2
3
{
    "status": "OK"
}

1
2
3
4
5
{
    "status":"ERR",
    "errm":"You need to authorize your device again",
    "err":"EBADTEN"
}

One Touch API

Checksum (Optional)

If you wish to use a checksum to validate the request, you can use the APPCHECK parameter.

The checksum is generated as follows:

  • hmac_sha1_hex (request_data, SECRET)

request_data represents newline (/n) concatenated lines containing concatenated PARAM_NAME and param_value sorted in ascending order by PARAM_NAME.

If the request requires a token

The user's CIN with a concatenated newline (/n) must be added to request_data.

User Information

GET /user/info

Method System
GET API_BASE

Shows general information about a user

Parameter Type Description Optionality
APPID string Unique Application ID Mandatory
DEVICEID string Unique device identifier Mandatory
TOKEN string Unique identifier of the access user Mandatory
PINS int 0|1 To obtain information about the user's payment instruments PINS = 1 Optional

Request

https://demo.epay.bg/xdev/api/user/info?APPID=appid&DEVICEID=deviceid&TOKEN=token&PINS=1

Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
{
    "status": "OK",
    "userinfo": {
        "GSM":"",
        "PIC": "user picture address",
        "REAL_NAME": "the name with which it is registered in ePay.bg",
        "ID": "user ID",
        "KIN": "Customer Identification Number",
        "EMAIL": "user@email.com"
    },
    "payment_instruments":[
            {
                "ID": "identifier of the payment instrument, submitted when paying with it",
                "VERIFIED": 1,
                "BALANCE": "21015",
                "PIC": "",
                "TYPE": 2,
                "NAME": "MicroAccount",
                "EXPIRES": ""
            },
            {
                "ID": "UsYGw8-pTlZU4DJOAYT914hLVte6sRaUsdWXuK1wELs",
                "VERIFIED": 1,
                "BALANCE": "",
                "PIC": "",
                "TYPE": 1,
                "NAME": "what the user named their card",
                "EXPIRES": "03/2017"
            },
        ],
}

1
2
3
4
5
{
    "status": "ERR",
    "err": "EBADT",
    "errm": "Login failed, check your code or contact support."
    }

Description of response parameters

userinfo

Parameter Type Description
GSM string Mobile number of the recipient with which he is registered in ePay.bg
PIC string User photo URL
REAL_NAME string The name with which the user is registered in ePay.bg
ID string User ID
KIN string Client ID
EMAIL string User email

payment_instruments

Parameter Type Description
ID string Payment instrument identifier (submitted when paying with it)
VERIFIED int 0|1 Is the payment instrument verified
0 - no
1 - yes
BALANCE string Amount in stotinki
For bank cards, it is called separately for each of them by the user, because usually banks charge for this operation
PIC string Image by type of payment instrument
Microaccount, VISA, or MasterCard
TYPE int 1|2 Type of payment instrument
1 - Bank card
2 - Microaccount
NAME string Name of the payment instrument (entered by the user)
EXPIRES string MM/YYYY Payment instrument expiration date
Microaccounts do not have an expiration date

GET /user/info/pins

Method System
GET API_BASE

Information about payment instruments

Request

https://demo.epay.bg/xdev/api/user/info/pins?APPID=appid&DEVICEID=deviceid&TOKEN=token

Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
{
    "status":"OK",
    "payment_instruments":[
        {
            "ID":"UsYGw8-pTlZU4DJOAYT919QVd1EXm2KQ8iD9-2Mr-dQ",
            "VERIFIED":1,
            "BALANCE":"9808668",
            "PIC":"",
            "TYPE":2,
            "NAME":"MicroAccount",
            "EXPIRES":"",
            "CARD_TYPE":"",
            "CARD_TYPE_COUNTRY":"",
            "CARD_TYPE_DESCR":"",
        },
        {
            "ID":"UsYGw8-pTlZU4DJOAYT91xPUP8YqpocJScram3nKxVs",
            "VERIFIED":1,
            "BALANCE":"",
            "PIC":"",
            "TYPE":1,
            "NAME":"PIB Maestro",
            "EXPIRES":"12/2015",
            "CARD_TYPE":"6",
            "CARD_TYPE_COUNTRY":"",
            "CARD_TYPE_DESCR":""
        },
        {
            "ID":"UsYGw8-pTlZU4DJOAYT914wtfCccfrIbeMWwUDFeuOM",
            "VERIFIED":1,
            "BALANCE":"",
            "PIC":"",
            "TYPE":1,
            "NAME":"CCB MC 3",
            "EXPIRES":"12/2015",
            "CARD_TYPE":"5",
            "CARD_TYPE_COUNTRY":"",
            "CARD_TYPE_DESCR":"MasterCard"
        },
    ]
}

Description of response parameters

payment_instruments

Parameter Type Description
ID string Identifier of the payment instrument (submitted when paying with it)
VERIFIED int 0|1 Is the payment instrument verified
0 - no
1 - yes
BALANCE string Amount in stotinki
PIC string Image by type of payment instrument
Microaccount, VISA, or MasterCard
TYPE int 1|2 Type of payment instrument
1 - Bank card
2 - Microaccount
NAME string Name of the payment instrument (entered by the user)
EXPIRES string MM/YYYY Payment instrument expiration date
Microaccounts do not have an expiration date
CARD_TYPE string The first digit of the card number if it is a bank card
CARD_TYPE_COUNTRY string Card issuing country
CARD_TYPE_DESCR string Information about the payment instrument

GET /user/info/pins/balance

Method System
GET API_BASE

Information on the availability of payment instruments

Microaccount

Microaccount availability check is done with one request.

Parameter Type Description Optionality
APPID string Unique Application ID Mandatory
DEVICEID string Unique Device ID Mandatory
TOKEN string Unique access user identifier Mandatory
PINS string Microaccount ID Mandatory

Request

GET API_BASE/user/info/pins/balance?PINS=microaccount_id&APPID=appid&DEVICEID=deviceid&TOKEN=token

Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
{
    "status":"OK",
    "payment_instruments":[
        {
            "STATUS":"OK",
            "ID":"UsYGw8-pTlZU4DJOAYT919QVd1EXm2KQ8iD9-2Mr-dQ",
            "BALANCE":"9808668",
            "TYPE":2,
            "NAME":"MicroAccount",
            "EXPIRES":""
        }
    ]
}

Description of response parameters

Parameter Type Description
STATUS string Request status
ID string Payment instrument identifier (submitted when paying with it)
BALANCE string Amount in stotinki
Microaccount balance is returned immediately
TYPE int 1|2 Type of payment instrument
1 - Bank card
2 - Microaccount
NAME string Name of the payment instrument (entered by the user)
EXPIRES string It's always blank text because microaccounts don't have an expiration date

Payment request

This request is used to order a transfer from the registered card or from the user's account to the merchant's account.

Payment can be made both with a payment instrument already added to the application and with a new card on the mobile page of ePay.bg.

ePay One Touch order transfer

Payment is made in four steps:

Step Request
1. Get a payment code POST API_BASE/payment/init
2. Checking the parameters POST API_BASE/payment/check
3. Payment Request POST API_BASE/payment/send/user
4. Check the result POST API_BASE/payment/send/status

POST /payment/init

Method System
POST API_BASE

Used to get an identifier for the payment ID.

The identifier obtained from this request is used for the following:

  • check fees
  • the payment
  • payment status check

Query parameters

Parameter Type Description Optionality
APPID string Unique Application ID Mandatory
DEVICEID string Unique Device ID Mandatory
TOKEN string Unique Access User ID Mandatory
TYPE string send Mandatory
EXP int UnixTime When adding an EXP=Unix Time parameter, the validity time of the returned ID Optional

Request

https://demo.epay.bg/xdev/api/payment/init?APPID=appid&DEVICEID=deviceid&TOKEN=token&TYPE=send

Response

1
2
3
4
5
6
{
    "payment": {
        "ID":"UsYGw8-pTlZU4DJOAYT91_v-l30SMjADFA6AYPWYbJI"
    },
    "status":"OK"
}

Description of response parameters

payment

Parameter Type Description
ID string Payment ID (used in subsequent requests)

POST /payment/check

Method System
POST API_BASE

It is used to obtain information about the fees due for the payment.

If the payment amount changes or the user selects a different payment instrument, the request must be executed to obtain the current charges for the payment.

Query parameters

Parameter Type Description Optionality
ID string Payment ID (from /payment/init) Mandatory
TYPE string send Mandatory
AMOUNT int The amount in stotinki Mandatory
RCPT string Recipient's CIN Mandatory
RCPT_TYPE string It's always KIN Mandatory
DESCRIPTION string Payment description Mandatory
REASON string Described reason for the transfer Mandatory
PINS string Identifier of a payment instrument through which the payment is to be made. If none is submitted, the fees for all Mandatory
SHOW List What the payee should see.
For sender can be one or more of the:
- GSM;KIN;EMAIL;NAME separated by comma ,
- KIN - Customer number in ePay.bg (by default)
- GSM - Mobile number of the recipient with which it is registered in ePay.bg
- EMAIL - E-mail of the recipient with which it is registered in ePay.bg		 Mandatory

Request

https://demo.epay.bg/xdev/api/payment/check?APPID=appid&DEVICEID=deviceid&TOKEN=token&TYPE=send&ID=id&AMOUNT=amount&RCPT=merchant_kin&RCPT_TYPE=KIN&DESCRIPTION=descr&REASON=reason&PINS=microid_pin&SHOW=KIN

Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
{
    "payment":{
        "ID":"UsYGw8-pTlZU4DJOAYT91_v-l30SMjADFA6AYPWYbJI",
        "PAYMENT_INSTRUMENTS":[
            {
                "ID":"UsYGw8-pTlZU4DJOAYT91xPUP8YqpocJScram3nKxVs",
                "NAME":"PIB Maestro",
                "TAX":1,
                "TOTAL":35,
                "STATUS":"OK"
            }
        ],
        "AMOUNT":34,
        "DATA":{
            "RCPT_TYPE":"KIN",
            "RCPT":"3894711478"
        }
    },
    "status":"OK"
}

Description of response parameters

``payment''

Parameter Type Description
ID string Payment ID (from /payment/init)
PAYMENT_INSTRUMENTS Array Array with the payment instruments
AMOUNT int Amount in stotinki
DATA List RCPT_TYPE = "KIN", RCPT = "Recipient's KIN"

PAYMENT_INSTRUMENTS

Parameter Type Description
ID string Payment instrument identifier
NAME string Merchant Name
TAX int Payment fee
TOTAL int Payment amount
STATUS string Status

DATA

Parameter Type Description
RCPT_TYPE string It's always KIN
RCPT string Recipient's CIN

POST /payment/send/user

Method System
POST API_BASE

Fulfillment of the payment from the customer to the merchant

Query parameters

Parameter Type Description Optionality
ID string Identifier of the payment instrument (submitted when paying with it) Mandatory
AMOUNT int Amount in stotinki Mandatory
RCPT string CIN of Recipient Mandatory
RCPT_TYPE string It's always KIN Mandatory
DESCRIPTION string Payment Description Mandatory
REASON string Described reason for transfer Mandatory
PINS string Identifier of the payment instrument through which the payment is to be made. If none is submitted, fees are returned for all Mandatory
SHOW List What the payee should see.
For sender can be one or more of the:
- GSM;KIN;EMAIL;NAME separated by comma ,
- KIN - Customer number in ePay.bg (default)
- GSM - Mobile number of the recipient with which it is registered in ePay.bg
- EMAIL - Email of the recipient with which it is registered in ePay.bg		 Mandatory

Request

https://demo.epay.bg/xdev/api/payment/send/user?APPID=appid&DEVICEID=deviceid&TOKEN=token&TYPE=send&ID=payment_id&AMOUNT=amount&RCPT=merchant_kin&RCPT_TYPE=KIN&DESCRIPTION=descr&REASON=reason&PINS=pins_id&SHOW=KIN

Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
    "payment": {
        "ID":"UsYGw8-pTlZU4DJOAYT91_v-l30SMjADFA6AYPWYbJI",
        "AMOUNT":34,
        "TAX":1,
        "TOTAL":35,
        "RCPT":"3894711478",
        "RCPT_TYPE":"KIN",
        "DESCRIPTION":"",
        "REASON":"",
        "STATE":2,
        "STATE.TEXT":"Processing",
        "PINS":"UsYGw8-pTlZU4DJOAYT918PwRo4yHpe9i2EP4MXhQYVswVNAZdgJUljcrW22_Z9D9frQUAwOWHst\nN924CNqh3A",
        "SHOW":"6051143866",
        "SHOW.KIN":1,
        "SHOW.NAME":0,
        "SHOW.GSM":0,
        "SHOW.EMAIL":0,
        "SHOW.PIC":0,
        "NO":"",

    },
    "status":"OK"
}

Description of response parameters

payment

Parameter Type Description
ID string Payment ID (from /payment/init)
AMOUNT int The amount of the transfer in stotinki
TAX int The fee for the transfer is in cents
TOTAL int AMOUNT + TAX in stotinki
RCPT string Customer Identification Number (CIN) of the recipient of the transfer
RCPT_TYPE string It's always KIN
DESCRIPTION string Description of the payment
REASON string Described reason for transfer
STATE int Payment result 2|3|4
2 - Processing
3 - Payment successful
4 - Payment failed
STATE.TEXT string An error that can be displayed to the user
PINS string Identifier of the payment instrument through which the payment is to be made. If none is submitted, the fees for all
SHOW string Displays the result depending on the setting of SHOW.X
SHOW.KIN int User's CIN
SHOW.NAME int User names (for ePay.bg users)
SHOW.GSM int Mobile number of the user (for ePay.bg users)
SHOW.EMAIL int User email (for ePay.bg users)
SHOW.PIC int User photo (for ePay.bg users)
NO string Payment system code

POST /payment/send/status

Method System
POST API_BASE

Checking the result of the payment request

Query parameters

Parameter Type Description Optionality
ID string Identifier of the payment instrument (submitted when paying with it) Mandatory
AMOUNT int Amount in stotinki Mandatory
RCPT string CIN of Recipient Mandatory
RCPT_TYPE string It's always KIN Mandatory
DESCRIPTION string Payment Description Mandatory
REASON string Described reason for transfer Mandatory
PINS string Identifier of the payment instrument through which the payment is to be made. If none is submitted, fees are returned for all Mandatory
SHOW List What the payee should see.
For sender can be one or more of the:
- GSM;KIN;EMAIL;NAME separated by comma ,
- KIN - Customer number in ePay.bg (default)
- GSM - Mobile number of the recipient with which it is registered in ePay.bg
- EMAIL - Email of the recipient with which it is registered in ePay.bg		 Mandatory

Request

https://demo.epay.bg/xdev/api/payment/send/status?APPID=appid&DEVICEID=deviceid&TOKEN=token&TYPE=send&ID=payment_id&AMOUNT=amount&RCPT=merchant_kin&RCPT_TYPE=KIN&DESCRIPTION=descr&REASON=reason&PINS=pins_id&SHOW=KIN

Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
    "status":"OK",
    "payment":{
        "ID":"UsYGw8-pTlZU4DJOAYT91_v-l30SMjADFA6AYPWYbJI",
        "AMOUNT":34,
        "TAX":1,
        "TOTAL":35,
        "RCPT":"3894711478",
        "RCPT_TYPE":"KIN",
        "DESCRIPTION":"",
        "REASON":"",
        "STATE":4,
        "STATE.TEXT": "Payment made",
        "PINS":"UsYGw8-pTlZU4DJOAYT918PwRo4yHpe9i2EP4MXhQYVswVNAZdgJUljcrW22_Z9D9frQUAwOWHst\nN924CNqh3A",
        "SHOW":"6051143866",
        "SHOW.KIN":"6051143866",
        "SHOW.NAME":"",
        "SHOW.GSM":"",
        "SHOW.EMAIL":"",
        "NO":"2000000000032229",
    },
    "savecard": 1
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
{
    "status": "OK",
    "payment": {
        "ID":"UsYGw8-pTlZU4DJOAYT915SmHpAR07b9BTHwjlZMrIM",
        "AMOUNT":50,
        "TAX":102,
        "TOTAL":152,
        "RCPT":"4470411058",
        "RCPT_TYPE":"KIN",
        "DESCRIPTION":"DESCR",
        "REASON":"reason",
        "STATE":3,
        "STATE.TEXT":"Payment made",
        "SHOW":"4303137865",
        "SHOW.KIN":"4303137865",
        "SHOW.NAME":"",
        "SHOW.GSM":"",
        "SHOW.EMAIL":"",
        "NO":"2000000000032229"
    },
    "paid_with": {
        "CARD_TYPE_COUNTRY":"",
        "CARD_TYPE_DESCR":"Visa",
        "CARD_TYPE":"4",
        "TYPE": 1
    },
    "savecard": 0
}

Description of response parameters

payment

Parameter Type Description
ID string Payment ID (from /payment/init)
AMOUNT int The amount of the transfer in stotinki
TAX int The fee for the transfer is in cents
TOTAL int AMOUNT + TAX in stotinki
RCPT string Customer Identification Number (CIN) of the recipient of the transfer
RCPT_TYPE string It's always CIN
DESCRIPTION string Description of the payment
REASON string Described reason for transfer
STATE int Payment result 2|3|4
2 - Processing
3 - Payment successful
4 - Payment failed
STATE.TEXT string An error that can be displayed to the user
PINS string Identifier of the payment instrument through which the payment is to be made. If none is submitted, the fees for all
SHOW string Displays the result depending on the setting of SHOW.X
SHOW.KIN int User's CIN
SHOW.NAME int User names (for ePay.bg users)
SHOW.GSM int Mobile number of the user (for ePay.bg users)
SHOW.EMAIL int User email (for ePay.bg users)
NO string Payment system code

paid_with

Description of payment card when not saved "savecard": 0

Parameter Type Description
CARD_TYPE_COUNTRY string Issuing country of the card
CARD_TYPE_DESCR string Information about the payment instrument
CARD_TYPE string The first digit of the card number if it is a bank card
TYPE int 1 (bank card)