Разработчикам

Merchant API

^1.4

^OAS3

The API interface is used to make payment on products of the Beeline catalog. The REST API works over the HTTP protocol and is a set of methods by which requests are made and responses are returned for each operation. All responses come in the form of JSON structures.

To work with the API, get API-name и API-password from administrators

Note: Currently, the API is under development, methods and parameters are subject to change. On the possibility of testing the integration will be announced.

Use of protocols:

HTTPS

Work algorithm

1. The merchant performs a request to get the product catalog - the get-products method. The method is optional; the Merchant can manually assign identifiers to its products that correspond to the catalog.
2. The user selects the product on the Merchant portal and wants to pay using the mobile phone balance.
3. The merchant performs a request to create a payment - the create-payment method.
4. The platform performs the necessary actions (limits, calculation of commissions, etc.) and responds to the Merchant.
5. The merchant displays to the user the necessary information from paragraph 3 (commission, total amount).
5.1. If you need to confirm payment using OTP (the create-payment method returned the parameterotpConfirm = true) - the Merchant displays the OTP input field (5 digits) to the user.
5.2. The user may request to resend the OTP. To do this, the Merchant displays the button "Send OTP again" to the user - a call to the resend-otp method.
5.2.1. If the resend-otp method returns the parametercanResend = false - the user has exceeded the SMS sending limit, the OTP resubmission should be unavailable (for example, the button is inactive).
6. The user enters the OTP (if necessary) and agrees with the payment (for example, the button "Confirm") - call the method confirm-payment
6.1. If the user does not agree with the payment (for example, clicks the "Cancel" button), you must call the cancel-payment method. In this case, the operation in the Platform will be canceled.
7. The platform performs the necessary checks and transactions and responds to the Merchant, passing checks on the transaction.
7.1. If you haven't received the response or there is some error please check the operation status using the check-operation-status method.
8. Merchant can display checks to the user.

** If you need to make a refund (cancel the operation), you must call the refund-payment method. If the transaction is successful, the funds will be returned to the user's balance.

*** To get the history of operations by user, the Merchant should call the get-payment-history method. For example, to display the history of operations in the user's personal account or for their internal needs.

**** To receive checks for a particular operation, the Merchant must call the get-receipts method.

Preparing requests:

For each request must be formed a digital signature. To create a signature, you must use the encryption algorithm HMAC-SHA256.

Create a JSON request
Encrypt it with the HMAC-SHA256 algorithm using the provided password
Send the received signature in the field Signature request header

# PHP signature generation example:

$password = \'328378273892\';

$data = \'{\"example\":222,\"desc\":\"some text\"}\';

$sign = hash_hmac(\'sha256\', $data, $password);

Possible error codes (errorCode, errorMessage). Codes can be added during the development process.

Authorization
11001 Authorization parameters not set
11002 API with that name not found
11003 Invalid request signature
11004 System error during authorization
11005 API calls limit per minute exceeded
11006 API inactive
11007 Incorrect header Content-Type. It must be application/json
12008 Service under this api is not available
Payments
12001 Required parameter is missing in the request
12002 Invalid parameter type in request
12003 A system error occurred due to incorrect request data.
12004 The timestampEnd parameter must be greater than the timestampStart parameter
12005 In the amount parameter no more than 2 characters are allowed after the separator
12006 The amount parameter must be greater than zero.
12007 Phone number must begin with 7
12009 A payment with this merchantOrderId has already been created
12014 Incorrect channel name
13001 Agent is inactive
13002 Merchant is inactive
13003 Subscriber is inactive
13004 The payment provider must have an agent
14001 Merchant wallet is inactive
14002 Agent wallet is inactive
14003 Client wallet is inactive
15001 Product catalog category is inactive
15002 Product not found
15003 Product not available
15004 Product not available for payment provider
16001 Product not available for this Account Type
16002 The product is not available for this tariff plan.
17001 Insufficient funds on agent wallet
17002 Insufficient funds on the operator’s wallet
18001 The amount of merchant fees exceeds the amount of the transaction. Commission templates are not configured correctly.
18002 Unable to make a payment. Commission settings have been changed
18003 Amount of partial reversal greater then amount of original operation
19001 Failed to send SMS for confirmation request from the client
19002 Could not send SMS with OTP code
20001 Merchant's product availability check failed
20002 Merchant api receiver with ID {receiverId} not found
21001 Payment with this ID not found
21002 Payment with this ID not found
21003 Payment with this ID not found
21004 Payment with this ID not found
21011 Operation {id} is in the refund process now. Refund operation id: {refund_id}
22001 Invalid OTP
23001 CDB is not available
23002 CDB System Error
23003 Phone number not found
23004 CDB. User is not active
23005 Error. Your payment was canceled. For the payment availability from the balance it is important to spend at least {value} tenge on communication services
24001 MFS did not response in timeout
24002 MFS not available
24003 MFS payment failed
25001 Merchant product purchase confirmation failed
25002 Merchant product purchase failed on the merchant's side
25003 Payment rejected by Merchant
25004 Insufficient balance on the merchant's side
25005 Refund payment on the merchant's side
25006 Payment not found on the merchant's side
26001 System error during confirmation of purchase
27001 Failed to confirm purchase from merchant
28001 Payment cannot be canceled. Payment is already processed or already processed
29001 Unable to get checks. The operation is not in the status of "completed" and "reversed"
40001 Service provider is not available
40002 Service-provider. Check parameters failed.
40003 Subscriber don’t have Simply wallet.
40004 Simply payment provider not found.
40005 SIMPLY System Error.
40006 Return of the operation is prohibited.
30001 Subscriber data error
AML
Error code 2XYZ
X - where is the limit
- 0 wallets limit
- 1 user limit
- 2 limit by category
- 3 product limit
Y - operation
- 0 output template
- 1 input template
Z - Limit type
- 0 minimum amount limit
- 1 maximum amount limit
- 2 daily turnover limit
- 3 weekly turnover limit
- 4 monthly turnover limit
- 5 annual turnover limit
- 6 limit on the number of transactions per day
- 7 limit on the number of transactions per week
- 8 limit on the number of transactions per month
- 9 limit on the number of transactions per year

Servers

https://{domain}/merchant-api/v1

Service catalog

Methods for working with the product catalog

POST/get-products

Getting product catalog

The directory structure is provided for convenience and is not required when displaying products on the trading floor. To perform further financial transactions with products, you must use the product’s id.

Parameters

Try it out

Name	Description
Signature * string *(header)*	Digital signature request
Api-Name * string *(header)*	Api-Name, provided by admin
Content-Language string *(header)*	Content-Language, specify language

Request body

application/json

Example Value
Model

{

"is_active": true

}

Responses

Code	Description	Links
200	*Product catalog* application/json Controls Accept header. Example Value Model { "status": "ok", "categories": [ { "categoryId": 1, "categoryName": "Category name 1", "parentId": 0 } ], "products": [ { "id": 1, "name": "Product 1", "categoryId": 1, "isOwnProduct": false } ] }	No links
400	*Required parameter is missing in the request* application/json Example Value Model { "status": "error", "error": { "code": "12001", "message": "Required parameter is missing in the request" } }	No links
401	*Authorisation error* application/json Example Value Model { "status": "error", "error": { "code": "11003", "message": "Invalid request signature" } }	No links

POST/get-details

Getting fee pattern values

The method getting the value of the commission template by product id.

Parameters

Try it out

Name	Description
Signature * string *(header)*	Digital signature request
Api-Name * string *(header)*	Api-Name, provided by admin
Content-Language string *(header)*	Content-Language, specify language

Request body

application/json

Example Value
Model

{

"productId": 123

}

Responses

Code	Description	Links
200	*Product catalog* application/json Controls Accept header. Example Value Model { "status": "ok", "commission": [ { "percent": 1, "fixed": 1, "minValue": 1, "maxValue": 1, "minTransactionAmount": 1, "maxTransactionAmount": 1 } ] }	No links
400	*Required parameter is missing in the request* application/json Example Value Model { "status": "error", "error": { "code": "12001", "message": "Required parameter is missing in the request" } }	No links
401	*Authorisation error* application/json Example Value Model { "status": "error", "error": { "code": "11003", "message": "Invalid request signature" } }	No links

Payments

Methods for performing financial transactions

POST/create-payment

Create a product payment

Returns the identifier of the created payment, the amount of the commission, the total amount to be paid and the sign otpConfirm (true - OTP was sent to the client for payment confirmation, false - no confirmation via OTP is required). If otpConfirm = true - an OTP is sent to the client, you must confirm the payment using theconfirm-payment method by passing the entered OTP. If otpConfirm = false - it is necessary to confirm the payment using theconfirm-payment method without transferring OTP.

Parameters

Try it out

Name	Description
Signature * string *(header)*	Digital signature request
Api-Name * string *(header)*	Api-Name, provided by admin
Content-Language string *(header)*	Content-Language, specify language

Request body

application/json

Example Value
Model

{

"productId": 1,

"amount": 100,

"productReceiver": "7053031122",

"currencyFrom": "USD",

"payerPhone": "7053031133",

"sellerId": 50,

"merchantOrderId": 101,

"description": "A few words",

"channel": "api"

}

Responses

Code	Description	Links
200	*Payment created* application/json Controls Accept header. Example Value Model { "status": "ok", "paymentDetails": { "paymentId": 211, "commission": 0.11, "amount": 100, "totalAmount": 100.11, "otpConfirm": true, "cashbackAmount": 1.23 } }	No links
400	*Required parameter is missing in the request* application/json Example Value Model { "status": "error", "error": { "code": "12001", "message": "Required parameter is missing in the request" } }	No links
401	*Authorisation error* application/json Example Value Model { "status": "error", "error": { "code": "11003", "message": "Invalid request signature" } }	No links

POST/resend-otp

Resending OTP password to client

The method must be called if OTP re-sending is required. The method returns the status of sending SMS with OTP password. If in the answer the parameter canResend = true - the client may request to send the OTP again (for example, SMS did not arrive).

Parameters

Try it out

Name	Description
Signature * string *(header)*	Digital signature request
Api-Name * string *(header)*	Api-Name, provided by admin
Content-Language string *(header)*	Content-Language, specify language

Request body

application/json

Example Value
Model

{

"paymentId": 211

}

Responses

Code	Description	Links
200	*OTP sent* application/json Controls Accept header. Example Value Model { "status": "ok", "canResend": true }	No links
400	*Required parameter is missing in the request* application/json Example Value Model { "status": "error", "error": { "code": "12001", "message": "Required parameter is missing in the request" } }	No links
401	*Authorisation error* application/json Example Value Model { "status": "error", "error": { "code": "11003", "message": "Invalid request signature" } }	No links

POST/cancel-payment

Cancel payment

The method is used after createPayment if you need to cancel the payment (for example, the client clicked Cancel).

Parameters

Try it out

Name	Description
Signature * string *(header)*	Digital signature request
Api-Name * string *(header)*	Api-Name, provided by admin
Content-Language string *(header)*	Content-Language, specify language

Request body

application/json

Payment ID

Example Value
Model

{

"paymentId": 211

}

Responses

Code	Description	Links
200	*Payment canceled* application/json Controls Accept header. Example Value Model { "status": "ok" }	No links
400	*Required parameter is missing in the request* application/json Example Value Model { "status": "error", "error": { "code": "12001", "message": "Required parameter is missing in the request" } }	No links
401	*Authorisation error* application/json Example Value Model { "status": "error", "error": { "code": "11003", "message": "Invalid request signature" } }	No links

POST/confirm-payment

Confirm payment

Proof of payment. Returns the result of the payment and receipts

Parameters

Try it out

Name	Description
Signature * string *(header)*	Digital signature request
Api-Name * string *(header)*	Api-Name, provided by admin
Content-Language string *(header)*	Content-Language, specify language

Request body

application/json

Payment ID and OTP that the customer entered (if necessary)

Example Value
Model

{

"paymentId": 211,

"otp": 123456

}

Responses

Code	Description	Links
200	*Payment successful* application/json Controls Accept header. Example Value Model { "status": "ok", "receipts": { "emoneyReceipt": { "operatorName": "Beeline", "operatorAddress": "г. Астана, ул. Вишневая, д. 10", "operatorBin": "123456789123", "transactionType": "Purchase of EM", "walletNumber": 782354788345, "agentName": "EM Distribution Agent", "agentAddress": "г. Астана, ул. Вишневая, д. 11", "agentBin": "987564123654", "emoneyTransactionId": 654564, "emoneyTransactionTimestamp": 1522052661, "totalAmount": 100.11, "commission": 0.01 }, "paymentReceipt": { "operatorName": "Beeline", "operatorAddress": "г. Астана, ул. Вишневая, д. 10", "operatorBin": "123456789123", "transactionType": "Product payment", "walletNumber": 782354788345, "merchantName": "Merchant 1", "merchantAddress": "г. Астана, ул. Вишневая, д. 11", "merchantBin": "564789632541", "payerPhone": 7053031133, "paymentTransactionId": 654565, "paymentTransactionTimestamp": 1522052661, "amount": 100, "commission": 0.1, "totalAmount": 100.1, "productCode": 12, "productName": "SystemProduct", "productReceiver": "7053031133", "cashbackAmount": 1.23 } }, "isSmsSent": "true" }	No links
400	*Required parameter is missing in the request* application/json Example Value Model { "status": "error", "error": { "code": "12001", "message": "Required parameter is missing in the request" } }	No links
401	*Authorisation error* application/json Example Value Model { "status": "error", "error": { "code": "11003", "message": "Invalid request signature" } }	No links

POST/refund-payment

Return (cancellation) of payment. The implementation of the method will be later.

The method is used to return funds to the buyer for the transaction. The method is called for executed (confirmed) payments. The method returns the status of the execution of the operation.

Parameters

Try it out

Name	Description
Signature * string *(header)*	Digital signature request
Api-Name * string *(header)*	Api-Name, provided by admin
Content-Language string *(header)*	Content-Language, specify language

Request body

application/json

Payment ID

Example Value
Model

{

"paymentId": 211,

"amount": 543.58

}

Responses

Code	Description	Links
200	*Return successful* application/json Controls Accept header. Example Value Model { "status": "ok", "paymentDetails": { "paymentId": 2016 } }	No links
400	*Required parameter is missing in the request* application/json Example Value Model { "status": "error", "error": { "code": "12001", "message": "Required parameter is missing in the request" } }	No links
401	*Authorisation error* application/json Example Value Model { "status": "error", "error": { "code": "11003", "message": "Invalid request signature" } }	No links

POST/total-emoney

Get the total amount by product

Get the total amount by product filted by api id

Parameters

Try it out

Name	Description
Signature * string *(header)*	Digital signature request
Api-Name * string *(header)*	Api-Name, provided by admin
Content-Language string *(header)*	Content-Language, specify language

Request body

Responses

Code	Description	Links
200	*Emoney turnover* application/json Controls Accept header. Example Value Model { "status": "ok", "totalAmount": "100.0" }	No links
401	*Authorisation error* application/json Example Value Model { "status": "error", "error": { "code": "11003", "message": "Invalid request signature" } }	No links

Code

Description

Links

200

Emoney turnover

application/json

Controls Accept header.

Example Value
Model

{

"status": "ok",

"totalAmount": "100.0"

}

No links

401

Authorisation error

application/json

Example Value
Model

{

"status": "error",

"error": {

"code": "11003",

"message": "Invalid request signature"

}

No links

History

Methods for more information - transaction history and checks

POST/get-payment-history

Getting the history of operations by user for the period

The method returns an array of objects - operations for a specified period of time.

Parameters

Try it out

Name	Description
Signature * string *(header)*	Digital signature request
Api-Name * string *(header)*	Api-Name, provided by admin
Content-Language string *(header)*	Content-Language, specify language

Request body

application/json

User's phone number, time period

Example Value
Model

{

"payerPhone": "7053031133",

"timestampStart": 1522052661,

"timestampEnd": 2522052661

}

Responses

Code	Description	Links
200	*List of transactions (payments)* application/json Controls Accept header. Example Value Model { "status": "ok", "payments": [ { "paymentId": 211, "timestamp": 1522052661, "amountFrom": 100, "currencyFrom": "KZT", "amount": 100, "total_amount": 100.11, "product_id": 1, "name": "Product 1", "seller_id": 50, "front_order_id": 101, "payment_description": "Comment to order", "cashbackAmount": 0 }, { "paymentId": 212, "timestamp": 1522052661, "amountFrom": 100, "currencyFrom": "KZT", "amount": 100, "total_amount": 100.12, "product_id": 2, "name": "Product 2", "seller_id": 50, "front_order_id": 102, "payment_description": "Comment to order", "cashbackAmount": 0 } ] }	No links
400	*Required parameter is missing in the request* application/json Example Value Model { "status": "error", "error": { "code": "12001", "message": "Required parameter is missing in the request" } }	No links
401	*Authorisation error* application/json Example Value Model { "status": "error", "error": { "code": "11003", "message": "Invalid request signature" } }	No links

POST/get-receipts

Receipt of receipts by transaction ID

The method returns a list of checks for paymentId - receipt of electronic money from the agent, receipt of payment for the product, reversal check of the operation (if the operation was canceled), receipt of electronic money return to the agent (if the operation was canceled)

Parameters

Try it out

Name	Description
Signature * string *(header)*	Digital signature request
Api-Name * string *(header)*	Api-Name, provided by admin
Content-Language string *(header)*	Content-Language, specify language

Request body

application/json

ID of the payment for which you want to receive receipts.

Example Value
Model

{

"paymentId": 211

}

Responses

Code	Description	Links
200	*Receipts list* application/json Controls Accept header. Example Value Model { "status": "ok", "emoneyReceipt": { "operatorName": "Beeline", "operatorAddress": "г. Астана, ул. Вишневая, д. 10", "operatorBin": "123456789123", "transactionType": "Purchase of EM", "walletNumber": 782354788345, "agentName": "EM Distribution Agent", "agentAddress": "г. Астана, ул. Вишневая, д. 11", "agentBin": "987564123654", "emoneyTransactionId": 654564, "emoneyTransactionTimestamp": 1522052661, "totalAmount": 100.11, "commission": 0.01 }, "paymentReceipt": { "operatorName": "Beeline", "operatorAddress": "г. Астана, ул. Вишневая, д. 10", "operatorBin": "123456789123", "transactionType": "Product payment", "walletNumber": 782354788345, "merchantName": "Merchant 1", "merchantAddress": "г. Астана, ул. Вишневая, д. 11", "merchantBin": "564789632541", "payerPhone": 7053031133, "paymentTransactionId": 654565, "paymentTransactionTimestamp": 1522052661, "amount": 100, "commission": 0.1, "totalAmount": 100.1, "productCode": 12, "productName": "SystemProduct", "productReceiver": "7053031133", "cashbackAmount": 1.23 }, "refundPaymentReceipt": { "operatorName": "Beeline", "operatorAddress": "Operator address", "operatorBin": "123456789123", "transactionType": "Reversal of product payment", "walletNumber": 782354788345, "merchantName": "Merchant 1", "merchantAddress": "Merchant address", "merchantBin": "564789632541", "payerPhone": 7053031133, "paymentTransactionId": 654565, "paymentTransactionTimestamp": 1522052661, "refundPaymentTransactionId": 654578, "refundPaymentTransactionTimestamp": 1522052661, "amount": 100, "commission": 0.1, "totalAmount": 100.1 }, "refundEmoneyReceipt": { "operatorName": "Beeline", "operatorAddress": "Operator address", "operatorBin": "123456789123", "transactionType": "E-money purchase reversal", "walletNumber": 782354788345, "agentName": "EM distribution agent", "agentAddress": "Agent address", "agentBin": "987564123654", "emoneyTransactionId": 654564, "emoneyTransactionTimestamp": 1522052661, "refundEmoneyTransactionId": 654589, "refundEmoneyTransactionTimestamp": 1522052661, "amount": 100, "commission": 0.1, "totalAmount": 100.1 } }	No links
400	*Required parameter is missing in the request* application/json Example Value Model { "status": "error", "error": { "code": "12001", "message": "Required parameter is missing in the request" } }	No links
401	*Authorisation error* application/json Example Value Model { "status": "error", "error": { "code": "11003", "message": "Invalid request signature" } }	No links

Simply catalog

POST/get-simply-products

Getting products available for simply

Parameters

Try it out

Name	Description
Signature * string *(header)*	Digital signature request
Api-Name * string *(header)*	Api-Name, provided by admin
Content-Language string *(header)*	Content-Language, specify language

Request body

application/json

Example Value
Model

{

"is_active": true

}

Responses

Code	Description	Links
200	*Product catalog* application/json Controls Accept header. Example Value Model { "status": "ok", "categories": [ { "categoryId": 1, "categoryName": "Category name 1", "parentId": 0 } ], "products": [ { "id": 1, "name": "Product 1", "categoryId": 1, "isOwnProduct": false } ] }	No links
400	*Required parameter is missing in the request* application/json Example Value Model { "status": "error", "error": { "code": "12001", "message": "Required parameter is missing in the request" } }	No links
401	*Authorisation error* application/json Example Value Model { "status": "error", "error": { "code": "11003", "message": "Invalid request signature" } }	No links

Check operation status

POST/check-operation-status

Check operation status

Returns the status of an operation by its ID. Possible status values: new, processing, completed, declined, error, reversed.

Parameters

Try it out

Name	Description
Signature * string *(header)*	Digital signature request
Api-Name * string *(header)*	Api-Name, provided by admin
Content-Language string *(header)*	Content-Language, specify language

Request body

application/json

Example Value
Model

{

"operationId": 1479

}

Responses

Code	Description	Links
200	*A transaction with the specified ID exists and has the status:* application/json Controls Accept header. Example Value Model { "status": "ok", "operationDetails": { "operationId": 1479, "operationStatus": "new" } }	No links
400	*Required parameter is missing in the request* application/json Example Value Model { "status": "error", "error": { "code": "12001", "message": "Required parameter is missing in the request" } }	No links
401	*Authorisation error* application/json Example Value Model { "status": "error", "error": { "code": "11003", "message": "Invalid request signature" } }	No links

Subscriptions

POST/create-subscription

Create a subscription

The method creates subsciprtion record

Parameters

Try it out

Name	Description
Signature * string *(header)*	Digital signature request
Api-Name * string *(header)*	Api-Name, provided by admin
Content-Language string *(header)*	Content-Language, specify language

Request body

application/json

Example Value
Model

{

"productId": 1,

"amount": 100,

"currency": "USD",

"productReceiver": "7053031122",

"payerPhone": "7053031133",

"sellerId": 50,

"description": "this is sample desc",

"interval": "month",

"daysNumber": "10",

"dateFrom": "10",

"dateTo": "10",

"channel": "sms"

}

Responses

Code	Description	Links
200	*Subscription created* application/json Controls Accept header. Example Value Model { "status": "ok", "Subscription ID": "10234", "Subscription status": "disabled", "paymentDetails": { "currencyAmount": 20, "amount": 100, "currency": "KZT", "commission": 0.11, "totalAmount": 100.11 } }	No links
400	*Required parameter is missing in the request* application/json Example Value Model { "status": "error", "error": { "code": "12001", "message": "Required parameter is missing in the request" } }	No links
401	*Authorisation error* application/json Example Value Model { "status": "error", "error": { "code": "11003", "message": "Invalid request signature" } }	No links

POST/resend-subscription-otp

Rensend OTP to confirm subscription

Send OTP code one more time

Parameters

Try it out

Name	Description
Signature * string *(header)*	Digital signature request
Api-Name * string *(header)*	Api-Name, provided by admin
Content-Language string *(header)*	Content-Language, specify language

Request body

application/json

Example Value
Model

{

"subscriptionId": 1,

"action": "start"

}

Responses

Code	Description	Links
200	*Payment created* application/json Controls Accept header. Example Value Model { "status": "ok", "canResend": "true", "otp": "267449", "error": {} }	No links
400	*Required parameter is missing in the request* application/json Example Value Model { "status": "error", "error": { "code": "12001", "message": "Required parameter is missing in the request" } }	No links
401	*Authorisation error* application/json Example Value Model { "status": "error", "error": { "code": "11003", "message": "Invalid request signature" } }	No links

POST/start-subscription

Starts a subscription

The method activates subscription

Parameters

Try it out

Name	Description
Signature * string *(header)*	Digital signature request
Api-Name * string *(header)*	Api-Name, provided by admin
Content-Language string *(header)*	Content-Language, specify language

Request body

application/json

Example Value
Model

{

"subscriptionId": 1

}

Responses

Code	Description	Links
200	*subscription started* application/json Controls Accept header. Example Value Model { "status": "ok", "subscriptionId": "10234", "action": "start", "otpConfirm": "true", "error": { "erroCode": 300, "errorMessage": "" } }	No links
400	*Required parameter is missing in the request* application/json Example Value Model { "status": "error", "error": { "code": "12001", "message": "Required parameter is missing in the request" } }	No links
401	*Authorisation error* application/json Example Value Model { "status": "error", "error": { "code": "11003", "message": "Invalid request signature" } }	No links

POST/stop-subscription

Stops a subscription

The method stops subscription

Parameters

Try it out

Name	Description
Signature * string *(header)*	Digital signature request
Api-Name * string *(header)*	Api-Name, provided by admin
Content-Language string *(header)*	Content-Language, specify language

Request body

application/json

Example Value
Model

{

"subscriptionId": 1

}

Responses

Code	Description	Links
200	*subscription stopped* application/json Controls Accept header. Example Value Model { "status": "ok", "subscriptionId": "10234", "action": "stop", "otpConfirm": "true", "error": { "erroCode": 300, "errorMessage": "" } }	No links
400	*Required parameter is missing in the request* application/json Example Value Model { "status": "error", "error": { "code": "12001", "message": "Required parameter is missing in the request" } }	No links
401	*Authorisation error* application/json Example Value Model { "status": "error", "error": { "code": "11003", "message": "Invalid request signature" } }	No links

POST/confirm-subscription-action

Confirms subscription action

The method confirms subscription

Parameters

Try it out

Name	Description
Signature * string *(header)*	Digital signature request
Api-Name * string *(header)*	Api-Name, provided by admin
Content-Language string *(header)*	Content-Language, specify language

Request body

application/json

Example Value
Model

{

"subscriptionId": 1,

"action": "start",

"otp": "123456"

}

Responses

Code	Description	Links
200	*Payment created* application/json Controls Accept header. Example Value Model { "status": "ok", "error": { "erroCode": 300, "errorMessage": "" } }	No links
400	*Required parameter is missing in the request* application/json Example Value Model { "status": "error", "error": { "code": "12001", "message": "Required parameter is missing in the request" } }	No links
401	*Authorisation error* application/json Example Value Model { "status": "error", "error": { "code": "11003", "message": "Invalid request signature" } }	No links

POST/get-subscription-list

User's subscriptions

This method return list of subscritions by user

Parameters

Try it out

Name	Description
Signature * string *(header)*	Digital signature request
Api-Name * string *(header)*	Api-Name, provided by admin
Content-Language string *(header)*	Content-Language, specify language

Request body

application/json

Example Value
Model

{

"payerPhone": "7053031133"

}

Responses

Code	Description	Links
200	*Gets payer's subscriptions list* application/json Controls Accept header. Example Value Model { "status": "ok", "subscriptions": { "subscription": { "subscriptionId": 1, "creationdate": "", "productId": 1, "productName": 1, "amountOrigin": 1.11, "currencyOrigin": "KZT", "amount": 14.88, "productReceiver": 2, "description": "example value", "interval": "month", "dateFrom": "month", "dateTo": "month", "isPaymentNotification": "month", "subscriptionStatus": "month" } }, "error": { "erroCode": 300, "errorMessage": "" } }	No links
400	*Required parameter is missing in the request* application/json Example Value Model { "status": "error", "error": { "code": "12001", "message": "Required parameter is missing in the request" } }	No links
401	*Authorisation error* application/json Example Value Model { "status": "error", "error": { "code": "11003", "message": "Invalid request signature" } }	No links

Models

ErrorModel{

success

string
example: false

Request Processing Status

error

{...}

}

CancelPaymentRequest{

paymentId*

integer
example: 211

Payment ID

}

CancelPaymentResponse{

status

string
example: ok

Cancellation status

}

Category{

categoryId

integer
example: 1

Category ID

categoryName

string
example: Category name 1

Category name

parentId

integer
example: 0

Parent category ID. 0 - paernt category

}

CheckOperationStatusRequest{

operationId*

integer
example: 1479

Operation ID

}

CheckOperationStatusResponse{

status

string
example: ok

Operation status

operationDetails

{...}

}

Commission{

percent	string example: 1 Percent fee
fixed	string example: 1 Fixed fee
minValue	string example: 1 Minimum fee value
maxValue	string example: 1 Maximum fee value
minTransactionAmount	string example: 1 Minimum transaction amount for which a fee applies
maxTransactionAmount	string example: 1 Maximum amount of transaction for which the fee applies

}

ConfirmPaymentRequest{

paymentId*

integer
example: 211

Payment ID

otp

integer
example: 123456

'OTP that the client entered'. Required if the method createPayment returned parameter * otpConfirm = true

}

ConfirmPaymentResponse{

status

string
example: ok

Payment status

receipts

{...}

isSmsSent

boolean
example: true

sms was sent or not

}

ConfirmPaymentSimplyRequest{

paymentId*

integer
example: 211

Payment ID

procardId

string
example: 211

Procard ID

}

ConfirmSubscriptionActionRequest{

subscriptionId*

integer
example: 1

Subscription ID

action*

string
example: start

action

otp

string
example: 123456

OTP code

}

ConfirmSubscriptionActionResponse{

status

string
example: ok

Subscription confirmation status

error

{...}

}

CreatePaymentRequest{

productId*	integer example: 1 Product ID
amount*	number example: 100 Payment amount
productReceiver*	string maxLength: 14 example: 7053031122 Recipient's phone number/contract number
currencyFrom	string maxLength: 3 minLength: 3 example: USD Payment currency from, if not set defaults to main system currency
payerPhone*	string example: 7053031133 Payer's phone number
sellerId	string example: 50 Point of Sale ID
merchantOrderId*	integer example: 101 Dealer's Order (Operation) ID
description	string example: A few words Payment comment
channel	string example: api Channel

}

CreatePaymentResponse{

status

string
example: ok

Payment creation status

paymentDetails

{...}

}

CreateSubscriptionRequest{

productId*	integer example: 1 Product ID
amount*	number example: 100 Payment amount
currency*	string maxLength: 3 minLength: 3 example: USD Payment currency from, if not set defaults to main system currency
productReceiver*	string maxLength: 14 example: 7053031122 Recipient's phone number/contract number
payerPhone*	string example: 7053031133 Payer's phone number
sellerId	string example: 50 Point of Sale ID
description	string example: this is sample desc Payment comment
interval*	string example: month Payment interval
daysNumber	integer example: 10 Payment interval if interval is set to days
dateFrom*	string example: 10 Date when subscription starts to work
dateTo*	string example: 10 Date when subscription stops to work
channel	string example: sms Channel

}

CreateSubscriptionResponse{

status	string example: ok Subscription creation status
Subscription ID	integer example: 10234 Subscription ID
Subscription status	boolean example: disabled Subscription creation status
paymentDetails	{...}

}

EmoneyReceiptModel{

description:	*Emoney purchase receipt*
operatorName	string example: Beeline Name of the operator of e-money
operatorAddress	string example: г. Астана, ул. Вишневая, д. 10 The address of the operator of e-money
operatorBin	string example: 123456789123 BIN of the operator of e-money
transactionType	string example: Purchase of EM Transaction type
walletNumber	integer example: 782354788345 User's e-wallet number
agentName	string example: EM Distribution Agent Agent name
agentAddress	string example: г. Астана, ул. Вишневая, д. 11 Agent address
agentBin	string example: 987564123654 BIN of the agent
emoneyTransactionId	integer example: 654564 E-money purchase transaction ID
emoneyTransactionTimestamp	integer example: 1522052661 E-money purchase transaction date and time in milliseconds
totalAmount	number example: 100.11 Transaction amount
commission	number example: 0.01 Transaction fee amount

}

Response 400{

description:	*Required parameter is missing in the request*
status	string *example: error*
error	{...}

}

Response 401{

description:	*Authorisation error*
status	string *example: error*
error	{...}

}

GetDetailsRequest{

productId

integer
example: 123

Product id

}

GetDetailsResponse{

status	string *example: ok*
commission	[...]

}

GetPaymentHistoryRequest{

payerPhone*

string
example: 7053031133

Payer's phone number

timestampStart*

integer
example: 1522052661

'Date from' in milliseconds

timestampEnd*

integer
example: 2522052661

'Date on' in milliseconds

}

GetPaymentHistoryResponse{

status

string
example: ok

Status of receipt of operations history

payments

[...]

}

GetProductsRequest{

is_active

boolean
example: true

Parameter for the correct formation of the signature, the value of the parameter is not important.

}

GetProductsResponse{

status	string *example: ok*
categories	[...]
products	[...]

}

GetReceiptsRequest{

paymentId*

integer
example: 211

Payment ID

}

GetReceiptsResponse{

status	string example: ok Check receipt status
emoneyReceipt	#/components/schemas/EmoneyReceiptModelEmoneyReceiptModel{...}
paymentReceipt	#/components/schemas/PaymentReceiptModelPaymentReceiptModel{...}
refundPaymentReceipt	#/components/schemas/RefundPaymentReceiptModelRefundPaymentReceiptModel{...}
refundEmoneyReceipt	#/components/schemas/RefundEmoneyReceiptModelRefundEmoneyReceiptModel{...}

}

GetSubscriptionListRequest{

payerPhone*

string
example: 7053031133

Payer's phone number

}

GetSubscriptionListResponse{

status

string
example: ok

Subscription creation status

subscriptions

{...}

error

{...}

}

MerchantTotalEmoneyReponse{

status

string
example: ok

status

totalAmount

float
example: 100.0

total amount

}

PaymentObj{

description:	*Operation*
paymentId	integer example: 211 Payment ID
timestamp	integer example: 1522052661 Date and time of payment in milliseconds
amount	number example: 100 Payment amount
totalAmount	number example: 100.11 Total commission
productId	integer example: 1 Product ID
productName	string example: Product 1 Product name
sellerId	integer example: 50 Point of sale ID
merchantOrderId	integer example: 101 Dealer's Order (Operation) ID
description	string example: Comment Payment comment

}

PaymentReceiptModel{

description:	*Product payment receipt*
operatorName	string example: Beeline Name of the operator of e-money
operatorAddress	string example: г. Астана, ул. Вишневая, д. 10 The address of the operator of e-money
operatorBin	string example: 123456789123 BIN code of the operator of e-money
transactionType	string example: Product payment Transaction type
walletNumber	integer example: 782354788345 User's e-wallet number
merchantName	string example: Merchant 1 Name of the supplier (merchant)
merchantAddress	string example: г. Астана, ул. Вишневая, д. 11 Supplier Address (Merchant)
merchantBin	string example: 564789632541 BIN code of the supplier (merchant)
payerPhone	integer example: 7053031133 Payer's phone number
paymentTransactionId	integer example: 654565 Product payment transaction ID
paymentTransactionTimestamp	integer example: 1522052661 Date and time of the product payment transaction in milliseconds
amount	number example: 100 Amount per product
commission	number example: 0.1 Commission amount
totalAmount	number example: 100.1 Total amount
productCode	integer example: 12 Product code
productName	string example: SystemProduct Product name
productReceiver	string example: 7053031133 Product receiver
cashbackAmount	number example: 1.23 Cashback amount

}

Product{

id	integer example: 1 Product ID
name	string example: Product 1 Product name
categoryId	integer example: 1 Product category ID
isOwnProduct	boolean example: false true - Merchant is the owner of the product, false - Merchant is not the owner of the product

}

RefundEmoneyReceiptModel{

description:	*E-money purchase reversal receipt*
operatorName	string example: Beeline Name of the operator of e-money
operatorAddress	string example: Operator address The address of the operator of e-money
operatorBin	string example: 123456789123 BIN code of the operator of e-money
transactionType	string example: E-money purchase reversal Transaction type
walletNumber	integer example: 782354788345 User's e-wallet number
agentName	string example: EM distribution agent Agent name
agentAddress	string example: Agent address Address of the distributor of EM
agentBin	string example: 987564123654 BIN code of the agent
emoneyTransactionId	integer example: 654564 E-money purchase transaction ID
emoneyTransactionTimestamp	integer example: 1522052661 E-money purchase transaction date and time in milliseconds
refundEmoneyTransactionId	integer example: 654589 E-money reversal transaction ID
refundEmoneyTransactionTimestamp	integer example: 1522052661 The date and time of the e-money purchase reversal transaction in milliseconds
amount	number example: 100 Payment amount
commission	number example: 0.1 Commission amount
totalAmount	number example: 100.1 Total amount

}

RefundPaymentReceiptModel{

description:	*Product reversal receipt*
operatorName	string example: Beeline Name of the operator of e-money
operatorAddress	string example: Operator address The address of the operator of e-money
operatorBin	string example: 123456789123 BIN code of the operator of e-money
transactionType	string example: Reversal of product payment Transaction type
walletNumber	integer example: 782354788345 User's e-wallet number
merchantName	string example: Merchant 1 Name of the supplier (merchant)
merchantAddress	string example: Merchant address Supplier address (Merchant)
merchantBin	string example: 564789632541 BIN code of the supplier (merchant)
payerPhone	integer example: 7053031133 Payer's phone number
paymentTransactionId	integer example: 654565 Product payment transaction ID
paymentTransactionTimestamp	integer example: 1522052661 Date and time of the product payment transaction in milliseconds
refundPaymentTransactionId	integer example: 654578 Transaction ID of the payment reversal of the product
refundPaymentTransactionTimestamp	integer example: 1522052661 Date and time of the transaction to reverse the product payment in milliseconds
amount	number example: 100 Payment amount
commission	number example: 0.1 Commission amount
totalAmount	number example: 100.1 Total amount

}

RefundPaymentRequest{

paymentId*

integer
example: 211

Payment ID

amount

float
example: 543.58

Optional parameter. Amount for partial refund. Can`t be grater then original payment amount.

}

RefundPaymentResponse{

status

string
example: ok

Status of payment refund

paymentDetails

{...}

}

ResendOtpRequest{

paymentId*

integer
example: 211

Payment ID

}

ResendOtpResponse{

status

string
example: ok

OTP send status

canResend

boolean
example: true

true - OTP resubmission is available, false - OTP resubmission is not available (limit is exceeded)

}

ResendSubscriptionOtpRequest{

subscriptionId*

integer
example: 1

Subscription ID

action*

string
example: start

action

}

ResendSubscriptionOtpResponse{

status	string example: ok Subscription creation status
canResend	boolean example: true true = OTP sent, false = no need to send OTP
otp	integer example: 267449 OTP code
error	{...}

}

StartSubscriptionRequest{

subscriptionId*

integer
example: 1

Subscription ID

}

StartSubscriptionResponse{

status	string example: ok Subscription creation status
subscriptionId	integer example: 10234 Subscription ID
action	string example: start Subscription action
otpConfirm	boolean example: true true = OTP sent, false = no need to send OTP
error	{...}

}

StopSubscriptionRequest{

subscriptionId*

integer
example: 1

Subscription ID

}

StopSubscriptionResponse{

status	string example: ok Subscription creation status
subscriptionId	integer example: 10234 Subscription ID
action	string example: stop Subscription action
otpConfirm	boolean example: true true = OTP sent, false = no need to send OTP
error	{...}

}