Exchange batch messages via HTTP GET¶

Before you continue

Use of HTTPS and TLS 1.2 is mandatory

Types of methods¶

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

Note

All sample requests will be encrypted with SECRET: 3EA1ABD845C3D684

Types of parameters¶

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\n

More information¶

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

List of STATUS codes¶

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

On response other than 00 all parameters except STATUS are ignored.

Only the meaning of the status predefined by the Operator will be visualized to the client. Field information such as LONGDESC and SHORTDESC will be ignored.

More information¶

96:

General error. When the Operator has not received a response from the merchant within the stipulated time of 60 seconds, it is also interpreted as 96. Also, invalid or missing required fields from the output. The Operator will send a repetition of the notification until receiving a correct status from the merchant.

94:

It has the meaning of 00. If the merchant's system accepted the payment request and returned a status of 00, but no response was received in our system - then, as a rule, the source should continue to send the same message until it receives a correct response. When receiving the same message again, the merchant can return 94, which means status 00 - the request has been processed and its repetition can be stopped.

80:

Temporarily Cannot Fulfill - the merchant is temporarily unable to process payments. It is usually returned when the merchant has temporarily stopped payments due to updating the obligations of its customers, or some other feature.

Obligation check¶

Serves to check for current obligations of a customer, payment will not follow. If the merchant has developed split payment by invoices, it must return an INVOICES parameter with the relevant data, if there is more than one obligation. When working under general obligation, this parameter is not submitted.

Important

If upon request to receive an obligation with TYPE=BILLING, the merchant has returned STATUS: 00 and an amount greater than 0 in the outgoing data, this is a signal to the Operator that payment can begin and will be processed accordingly. The merchant should be able to process a subsequent payment notification of type pay_confirm. If a payment will not be able to be made, the merchant must also return the STATUS : 96 method or another relevant to the situation to the pay_init method.

GET /pay/init¶

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	The field does not appear in a request with parameter `TYPE=CHECK`	Optional

Output data

JSON Object	Description	Optional
STATUS	On response other than `00`, all parameters except `STATUS` are ignored	Mandatory
IDN	Customer ID	Mandatory
AMOUNT	Amount in stotinki. When paying by invoices, their total value is submitted.	Mandatory
VALIDTO	Date to which obligation is currently	Mandatory
SHORTDESC	Entered on one line. Brief information about the customer - name, address, other information	Mandatory
LONGDESC	When splitting by invoices, synthesized information must be submitted for all invoices	Mandatory
INVOICES	If the merchant does not allow payment by invoices, do not submit this field	Optional

Output data of array INVOICES (supplied when payments of individual obligations-invoices are developed)

Data in INVOICES	Description	Optional
IDN	Subscriber number and invoice of the specific obligation concatenated with a dot (`IDN.INVOICE`)	Mandatory
AMOUNT	Amount for the specific invoice	Mandatory
VALIDTO	Date to which the specific invoice is currently	Mandatory
SHORTDESC	Short description for the specific invoice	Mandatory
LONGDESC	Full description for the specific invoice	Mandatory

Each individual invoice is fed into an array of INVOICES objects with the parameters described above. The invoice is formed from the customer's subscriber number, concatenated with a dot, and the invoice number (IDN.INVOICE) of the specific obligation.

Good practice

It is recommended that each invoice have its own description of the service or period it is associated with.

Examples¶

Request

Check only, payment will not follow:

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

Payment may follow:

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

Response

In case of general obligation:

{
    "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",
}

With two invoices:

{
    "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"} ]
}

Payment notification¶

Serves to notify the merchant of a payment made by the customer. Notification will be received only after a correct response to a pay_init type liability retrieval request that includes a TID field.

When paying under general obligation:

If the merchant has not developed invoice payment and only submits a general obligation, he will receive incoming data without the INVOICES field.

When paying by invoice:

Upon full repayment of all invoices, the merchant will receive a notification without the INVOICES parameter. The TOTAL parameter will contain the sum of all invoices submitted by the merchant to pay_init.
When paying a smaller number of invoices submitted by the merchant on pay_init, the Operator will also send an INVOICES parameter in the notification. Its value is formed by the subscriber number of the customer, concatenated with a dot, and the invoice number of the specific obligation (IDN.INVOICE). For more than one invoice, the values are separated by commas (IDN.INVOICE,IDN.INVOICE,IDN.INVOICE).

For partial payment:

In this case, the merchant will receive a value of TYPE=PARTIAL and the amount selected by the customer. It is possible that it is less than the one submitted by the merchant on pay_init. The field `INVOICES' does not appear in this notification.

Payment notifications cannot be declined.

The merchant will receive this message at set intervals until it responds with STATUS : 00 or STATUS : 94.

The merchant must be able to handle multiple notification messages. That is, it can receive one notification message several times in a row, or if it is delayed in responding to the first one (over 30 sec), it can receive a second one while processing the first one. In all cases, only one payment message should be reflected, and the rest should be answered with a status of 00 or 94.

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.

Examples¶

Request

Check on full repayment:

https://example.com/pay/confirm?DATE=20170316181226&TYPE=BILLING&MERCHANTID=0000334&IDN=12345&CHECKSUM=823383f09ab489fe172762703f8c047ce4428530&TOTAL=16600&TID=20170317121650509015053

Check when paying an invoice:

https://example.com/pay/confirm?DATE=20170316181226&TYPE=BILLING&MERCHANTID=0000334&IDN=12345&TOTAL=7800&CHECKSUM=06c5786385a673bfcc25a10a6d59722769bca25f&TID=2017031712165050901535&VOICES=5040101535.

Partial repayment check:

https://example.com/pay/confirm?DATE=20170316181226&TYPE=PARTIAL&MERCHANTID=0000334&IDN=12345&CHECKSUM=70514b288b2167b5bcf6324eaddc1a8179cebd57&TOTAL=100&TID=2017031712165059152305700

Response

{

    "STATUS" : "00"

}

Note

All parameters except STATUS and its corresponding predefined value are ignored.

Check for deposit¶

Used to check whether a deposit transaction (prepayment) can be made for a given customer. The request also contains an amount that the Merchant can validate or not. The amount can also be in predefined denominations.

GET /pay/init¶

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	`DEPOSIT`	Mandatory
TID	Transaction ID	Mandatory
TOTAL	Amount in stotinki	Mandatory

Output data

JSON Object	Description	Optional
STATUS	If the value of `STATUS` is not `00`, all other fields are ignored	Mandatory
SHORTDESC	Short description. Name, Email or Other - Customer Relevant Identifier	Mandatory
LONGDESC	Detailed description. Entered on a single line, with carriage-encoded `\n` every 110 characters	Mandatory

Important

If the merchant has returned STATUS : 00 to a deposit verification request, this is a signal to the Operator that payment can start and will be processed accordingly. The merchant should be able to process a subsequent payment notification (pay_confirm method). If payment cannot be made, the merchant must return the STATUS : 96 method or another relevant to the situation to the pay_init method.

Examples¶

Request

Deposit Check:

https://example.com/pay/init?IDN=12345&MERCHANTID=0000334&CHECKSUM=123c13322543764d4af33d87a4a8dd0965777ed6&TYPE=DEPOSIT&TID=20170317121650591535700020&TOTAL=2000

Response

{
    "STATUS" : "00",
    "SHORTDESC" : "Customer Name: Ivan Ivanov",
    "LONGDESC" : "Prepayment of service for 1 month\nCustomer name: Ivan Ivanov"
}

Notification of completed deposit¶

Serves to notify the merchant of a deposit payment made.

Payment notifications cannot be declined.

The merchant will receive this message at set intervals until it responds with STATUS : 00 or STATUS : 94.

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
CHECKSUM	HMAC-SHA-1 HEX of incoming data sorted by key	Mandatory
TYPE	`DEPOSIT`	Mandatory
TOTAL	Amount in stotinki	Mandatory

Output data

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

Examples¶

Request

Deposit payment:

https://example.com/pay/confirm?DATE=20170317121950&IDN=12345&MERCHANTID=0000334&CHECKSUM=123c13322543764d4af33d87a4a8dd0965777ed6&TYPE=DEPOSIT&TID=20170317121850591535700020&TOTAL=2000

Response

{
    "STATUS" : "00"
}

Generate CHECKSUM¶

CHECKSUM = hmac_sha1_hex (request_data, SECRET)

Note

request_data must include all incoming data.

Example of request_data value sorted in ascending order before being encoded. A newline \n character also appears on the last line:

IDN12345
MERCHANTID0000334
TID20170317121650591535700020
TYPEBILLING