Smart Payments

Smart Payments

Merchants API

1. Web service

Implements the following methods:

  • Login/Auth
  • Create voucher
  • Get voucher status
  • IPN - Instant Payment Notification

For simplicity, the Auth method should always be called before any other method.

The field ADDRESS should be replaced by one of the following values.


Production server:
https://app.smart-payments.eu/merchant/
Test server:
https://dev.app.smart-payments.eu/merchant/

1.1. Login/Auth

request
POST ADDRESS /auth
    Content-Type: application/json; charset=utf-8
    {"api_key":"username", "api_secret":"secret" }
response
    { "success" : true, "message" : "Success.", "serviceToken" : "##token##" }
or 
    { "success" : false, "message" : "Wrong credentials." }

If success==true, login was successful. I case of unsuccessful login response is sent with code 401 Unauthorized and a message describing the error.

1.2. Create a voucher

request v. 1
POST ADDRESS/merchant/vouchers/add
    Authorization: Bearer ##token##
    {
        "amount" : 50,
        "merchant_order" : "order-123456",
        "description" : "Customer Name"
    }

merchant_order - Optional order identifier on merchant's side description - Optional order descriptoin, e.g. customer's name or product information.

response v. 1
    { "success" : true, "message" : "Descriptive message",
        "data" : [
            { "code" : "1234567890", merchant_order : "order-123456", "amount" : 50, "status_id" : 1, "status" : "New", "valid_until" : "2023-01-10T00:00:00+00:00", "currency" : "BGN"}
        ]
    }

code - Voucher code to show to client
amount - The voucher amount
status_id:
1 - New, not yet paid
2 - Expired, validity has expired
3 - Paid, there is payment already registered
status - Text representation of status
valid_until - Voucher expiration datetime
currency - Voucher currency. Now only BGN is supported

request v. 2 - Create withdrawal voucher
POST ADDRESS/merchant/vouchers/add
    Authorization: Bearer ##token##
    {
        "amount" : 50,
        "customer_pin" : "1234567890",
        "customer_name" : "Customer Name",
        "customer_address" : "Customer Address",
        "document_number" : "123456",
        "document_date" : "2024-07-15",
        "merchant_order" : "order-123456",
        "description" : "Customer Name"
    }

customer_pin - Required. Personal Identification Number for the customer
customer_name - Required. Customer name is used for customer verification at the cash desk
customer_address - Optional. Customer address. Can also contain username or email
document_number - Required. Unique. Payment request identified on merchat's side
document_date - Required. Payment request date on merchat's side
merchant_order - Optional order identifier on merchant's side
description - Optional order descriptoin, e.g. customer's name or product information.

response v. 2
    { "success" : true, "message" : "Descriptive message",
        "data" : [
            { "customer_pin" : "1234567890", "customer_name" : "Customer Name", "document_number" : "123456" , "document_date" : "2024-07-15", "merchant_order" : "order-123456", "amount" : 50, "status_id" : 1, "status" : "New", "valid_until" : "2023-01-10T00:00:00+00:00", "currency" : "BGN"}
        ]
    }

Smart Payments keeps track of available balance for every merchant account.
If the requested amount is greated than the available balance the following response is returned and no voucher is created: 

    { "success" : false, "message" : "Error creating the voucher: Balance depleted; Please contact Smart Payments. accounting@smart-payments.eu" }

1.3. Get voucher status

request v. 1
GET ADDRESS/merchant/vouchers/view/{VoucherCode}
    Authorization: Bearer ##token##
response v. 1
    { "success" : true, "message" : "Voucher found",
        "data" : [
            { "code" : "1234567890", merchant_order : "order-123456", "amount" : 50, "status_id" : 1, "status" : "New", "valid_until" : "2023-01-10T00:00:00+00:00", "currency" : "BGN"}
        ]
    }
or 
    { "success" : false, "message" : "Voucher not found" }
request v. 2
GET ADDRESS/merchant/vouchers/view/{DocumentNumber}/{DocumentDate}
    Authorization: Bearer ##token##
response v. 2
    { "success" : true, "message" : "Voucher found",
        "data" : [
            { "customer_pin" : "1234567890", "customer_name" : "Customer Name", "document_number" : "123456" , "document_date" : "2024-07-15", "merchant_order" : "order-123456", "amount" : 50, "status_id" : 1, "status" : "New", "valid_until" : "2023-01-10T00:00:00+00:00", "currency" : "BGN"}
        ]
    }
or 
    { "success" : false, "message" : "Voucher not found" }

1.4. IPN

If you have registerd a IPN Return Url in our system will make a GET request once the voucher was paid.

request v. 1
GET IPN_URL?v=1&code={code}&status_id={status_id}&status=Paid&date={transaction_datetime}&merchant_order={merchant_order}&signature={signature}

v - IPN version
code - Voucher code to show to client
status_id: 3 - Paid, Voucher was paid
status: Paid - Text representation of the status_id
date - Voucher payment transaction datetime
merchant_order - order id in your system
signature - signature to validate the request comes from Smart Payments

Calculation of signature:

    <?php
    $toSign = $code . $status_id . $status . $date . $merchant_order; // String to sign
    $key = $api_key.$code; // $api_key - The key used in the login method, $code - The voucher code
    $signature = hash_hmac("sha256", $toSign, $key);
    ?>
If signature is not equal to the one provided in the query string, the rest of the data should be discarded.

response v. 1

We look for 200 response code as successful IPN.
If other responce is returned, we will retry the IPN a total of 3 times in the next minutes.
After this we will not send IPN for this voucher and you shoud check its status with the Get voucher status method.

request v. 2
GET IPN_URL?v=2&document_number={document_number}&document_date={document_date}&status_id={status_id}&status=Paid&date={transaction_datetime}&merchant_order={merchant_order}&signature={signature}

v - IPN version
document_number - Payment request identified on merchat's side
document_date - Payment request date on merchat's side
status_id: 3 - Paid, Voucher was paid
status: Paid - Text representation of the status_id
date - Voucher payment transaction datetime
merchant_order - order id in your system
signature - signature to validate the request comes from Smart Payments

Calculation of signature:

    <?php
    $toSign = $document_number . $document_date . $status_id . $status . $date . $merchant_order; // String to sign
    $key = $api_key . $document_number . $document_date; // $api_key - The key used in the login method, $document_number, $document_date
    $signature = hash_hmac("sha256", $toSign, $key);
    ?>
If signature is not equal to the one provided in the query string, the rest of the data should be discarded.

response v. 2

We look for 200 response code as successful IPN.
If other responce is returned, we will retry the IPN a total of 3 times in the next minutes.
After this we will not send IPN for this voucher and you shoud check its status with the Get voucher status method.