Jeton Voucher

Overview

Jeton Voucher is a payment method to pay by using vouchers. You can perform purchases through this method by using Payment Page and Gate, payouts by using Gate.

General information

Payment method type Payments by using vouchers
Countries and regions All countries
Payment currencies Refer to your key account manager ECommPay
Currency conversion
Purchases +
Payouts +
Stored credentials payments
Full refunds
Partial refunds
Chargebacks
Notes Each voucher has its unique identifiers: number, security code, expire date
Onboarding and access fee Refer to your key account manager ECommPay

Interaction diagram

Payment processing by using the Jeton Voucher payment method requires merchant's web service, one of ECommPay interfaces, and the ECommPay payment platform, as well as provider's the technical facilities.



Operations support

  Interfaces Amounts* Times**
Payment Page CMS Plug-ins Gate Dashboard (Old Dashboard) minimum maximum basic threshold
Purchases + + 10.00    
Payouts + 10.00    

* The minimum nominal value of a voucher is 10.00, the maximum — 500.00 in any of supported currencies. If a payout amount exceeds the maximum allowable value of the voucher, the payout is made for several vouchers. For example, if the payout amount is 1250.00 EUR the payout is made for two vouchers with a value of 500.00 EUR and one voucher with a value of 250.00 EUR.

** The basic and threshold times are defined as follows:
  • The basic time is the average estimated time between the moment a payment is initiated in the payment platform to the moment the payment result is sent to the initiator. The basic time evaluation is made on the assumption of normal operation of all technical facilities and communication channels and typical customer behaviour (if any input from customer is required). Use the basic time to estimate when to react to the absence of payment result notifications or when to check payment status.
  • The threshold time is the maximum possible time between the moment a payment is initiated in the payment platform to the moment the initiator receives the callback with the payment result. A payment is automatically declined, if its waiting time exceeds the threshold time. For individual setting of the threshold time limit, contact ECommPay technical support.

Processing scenarios

In the Jeton Voucher method, customer needs to enter requester voucher data (number, security code, and expire date). To initiate a payout, you need to send data of the issued voucher to customer via merchant's web service .

Figure: Purchase by using Payment Page procedure diagram



Figure: Purchase by using Gate procedure diagram



Figure: Payout by using Gate procedure diagram



The sections that follow provide detailed information about what you need to perform payments and how you can analyse the information on payments and operations.

Purchases by using Payment Page

General information

In the Jeton Voucher methods, when processing a purchase by using Payment Page, the merchant web service should send a request with all the required parameters and signature to the ECommPay URL and get the callback with the payment result from the payment platform. When opening Payment Page, you can have Payment Page opened with one of the Jeton Voucher methods selected. For more information about preselecting payment methods, see in Preselecting payment method. The full sequence and particularities of the purchase process are provided below.



Figure: Purchase sequence by using Payment Page

  1. A customer initiates a purchase on the merchant's web service.
  2. The web service sends the request for Payment Page opening to the specified ECommPay URL.
  3. The request for opening is redirected to the payment platform.
  4. The payment platform performs the initial request processing that involves validation of the required parameters and signature.
  5. Requested Payment Page is generated into the ECommPay payment platform as specified in the project settings and the request parameters.
  6. Payment Page is displayed to the customer.
  7. The customer selects the Jeton Voucher method.
  8. The form for entering voucher data is displayed to the customer.
  9. The customers enters requested data (number, security code, expire date of the voucher).
  10. The payment platform receives the purchase request for payment processing from Payment Page.
  11. The payment platform performs the internal purchase request processing and sends it to the Jeton Voucher service.
  12. The payment is processed on the Jeton Voucher side.
  13. The Jeton Voucher service sends the result notification to the payment platform.
  14. The payment platform sends a callback with the payment result to the web service.
  15. The payment platform sends the result to Payment Page.
  16. A page with the payment result information is displayed to the customer on Payment Page.

The sections that follow discuss in more details the request format and the Payment Page parameters to use in the Jeton Voucher payment method and provide the information on the format of callbacks with payment results. For the general information on how to use the API, see Payment Page API Description.

Request format

There are several things you need to consider when using the Jeton Voucher method:

  1. You must provide values for the basic minimum of parameters. Listed below are the parameters that are mandatory for any payment method:
    • customer_id—the unique ID of the customer within your project
    • project_id—the project ID obtained from ECommPay
    • payment_id—payment ID unique within the project
    • payment_currency—payment currency in ISO-4217 alpha-3 format
    • payment_amount—payment amount in minor units
  2. If you need to have payment form displayed with the Jeton Voucher method selected, set the force_payment_method parameter to jetonVoucher.
  3. If required, you can also add any other additional parameters Payment Page supports.
  4. After you specify all the parameters you need, you must create the signature for the request. For instructions on how to sign a payment request, see Signature generation and verification.

Thus, a correct payment request in the Jeton Voucher method must include project, customer and payment IDs, the currency and the amount of a payment in the appropriate currency, as shown in the following example:

EPayWidget.run(
    { payment_id: 'test8690', 
      payment_amount: 10000, 
      payment_currency: 'USD', 
      customer_id: '123',
      project_id: 150, 
      signature: "jm5mb8dKHAVNU0FYldJrxh4yo+52Kt8KU+Y1Y4HASCQ9vySO\/RLCvhtT
                                         4DqtVUkDJrOcZzUCwX6R\/ekpZhkIQg=="
    }
)

For information about all parameters available in the Jeton Voucher method , see Payment Page invocation parameters.

Callback format

The Jeton Voucher method uses the standard format for callbacks to deliver purchase results. For more information, see Callbacks.

The following is the example of a callback with an information about successful 10.00 EUR purchase on account 8400772805885304235 made by the test-439027 customer in the 239 project.

Figure: Example of a successful purchase callback

{
        "project_id": 239,
        "payment": {
            "id": "5a5cc4ddae974bf7c2ed9b331fa190cc",
            "type": "purchase",
            "status": "success",
            "date": "2019-04-28T18:05:49+0000",
            "method": "Jeton Voucher",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "test payment"
        },
        "account": {
            "number": "8400772805885304235"
        },
        "customer": {
            "id": "test-439027"
        },
        "operation": {
            "id": 36821000001669,
            "type": "sale",
            "status": "success",
            "date": "2019-04-28T18:05:49+0000",
            "created_date": "2019-04-28T18:05:47+0000",
            "request_id": "182dbd5f5ab4871fee0dace68fd00c4171f190311b8d7e93",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "provider": {
                "id": 1084,
                "payment_id": "",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "hWvmXPJXJDqHIRKUEmzOC03v0VT9D3Ge/zHFuzsNFS/1Wif2hn6nLwvH/1iFk46
                                                           KM1nIwWl0yy1UJrBn092EUg=="
    }
}

The following is the example of a callback for a purchase declined due to time-out.

Figure: Example of a declined purchase callback

{
        "project_id": 35,
        "payment": {
            "id": "ECT_TEST_1568960683171",
            "type": "purchase",
            "status": "decline",
            "date": "2019-09-20T06:29:26+0000",
            "method": "Jeton Voucher",
            "sum": {
                "amount": 10000,
                "currency": "EUR"
            },
            "description": "ECT_TEST_1568960683171"
        },
        "account": {
            "number": "5635996349986598973"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 48215000003011,
            "type": "sale",
            "status": "decline",
            "date": "2019-09-20T06:29:26+0000",
            "created_date": "2019-09-20T06:29:25+0000",
            "request_id": "9ec787ad3527d63294723ad5f13e7d0e68cc65a7da6c8",
            "sum_initial": {
                "amount": 10000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "EUR"
            },
            "provider": {
                "id": 1084,
                "payment_id": "",
                "auth_code": ""
            },
            "code": "20602",
            "message": "Time-out"
        },
        "signature": "jdrCwc4xEkOxzHBK8QnnlIiXp9PByR837P8AdSbyxJRKaia2HY/BATGybRWfMJ
                                                        kWz4wIHkUknnm/z8PYsRQP9w=="
    }
}

Related topics

The following topics might be useful when implementing payments by using Payment Page:

Purchases by using Gate

General information

In the Jeton Voucher methods, when processing a purchase by using Gate, the merchant web service is required to do the following:

  1. Send a request with all the required parameters and signature to the ECommPay URL.
  2. Get the callback with the payment result from the payment platform.

The following diagram provides the detailed picture of the payment processing procedure.



Figure: Purchase by using Gate

  1. A customer initiates a purchase through Jeton Voucher on the merchant's web service side.
  2. The web service sends the request for processing the purchase by using Gate to the specified ECommPay URL.
  3. The payment platform receives the request for processing the purchase from Gate.
  4. The payment platform performs the initial request processing that includes validation of the required parameters and signature.
  5. The payment platform sends the response with request receipt confirmation and correctness check result to the web service. For more information, see Response format.
  6. The payment platform performs the internal payment request processing and redirects the request to the Jeton Voucher service.
  7. The payment is processed on the Jeton Voucher side.
  8. The Jeton Voucher service sends the payment result notification to the payment platform.
  9. The payment platform sends a callback to the web service.
  10. The customer receives the payment result on the web service.

The sections that follow discuss in more details the request format and the Gate parameters to use in the Jeton Voucher payment method and provide the information on the format of callbacks with purchase results.

Request format

There are several things you must consider when using purchase requests in the Jeton Voucher method:
  1. You send purchase requests by sending the v2/payment/voucher/jeton/sale request by using HTTP method POST. This is the voucher payment group /v2/payment/voucher/{payment_method}/sale.
  2. The following objects and parameters must be specified in any request:
    • Object general—general purchase information:
      • project_id—project identifier
      • payment_id—unique purchase identifier
      • signature—signature created after you specify all the required parameters. For more information about signature generation, see Signature generation and verification
    • Object customer—customer information:
      • id—the unique ID of the customer within your project
      • ip_address—customer IP address
    • Object account—voucher information:
      • number—number
      • expiration—expiration date in the MM/YYYY format
      • security_code—security code
    • Object payment—purchase information:
      • amount—purchase amount
      • currency—payout currency in the ISO-4217 alpha-3 format
  3. If required, you can also add any other additional parameters Gate supports.

Thus, a correct payment request in the Jeton Voucher method must include project, customer and payment IDs, signature, customer and account information, currency and amount of the purchase, as shown in the following example:

Figure: Example of a purchase request

"general": {
    "project_id": 35,
    "payment_id": "Payment 12",
    "signature": "2tlMuYxLW9Yu6RETr8pdCfmi0UPE8euD+2AbrQgJguu0BQjXWH6
                              naCA9Ts6o4EVPjLyfbOQ+9ajAteg5lPk96Q=="
  },
  "customer": {
    "id": "123",
    "ip_address": "1.1.1.1"
  }, 
  "account": {
    "number": "461948963268890076",    
    "expiration": "07/2019",
    "security_code": "5459"
  },
  "payment": {
    "amount": 10000,
    "currency": "EUR"
}

Callback format

The Jeton Voucher method uses the standard format for callbacks to deliver purchase results. For more information, see Callbacks.

The following is the example of a callback with an information about successful 10.00 EUR purchase on account 8400772805885304235 made by the test-439027 customer in the 239 project.

Figure: Example of a successful purchase callback

{
        "project_id": 239,
        "payment": {
            "id": "5a5cc4ddae974bf7c2ed9b331fa190cc",
            "type": "purchase",
            "status": "success",
            "date": "2019-04-28T18:05:49+0000",
            "method": "Jeton Voucher",
            "sum": {
                "amount": 1000,
                "currency": "EUR"
            },
            "description": "test payment"
        },
        "account": {
            "number": "8400772805885304235"
        },
        "customer": {
            "id": "test-439027"
        },
        "operation": {
            "id": 36821000001669,
            "type": "sale",
            "status": "success",
            "date": "2019-04-28T18:05:49+0000",
            "created_date": "2019-04-28T18:05:47+0000",
            "request_id": "182dbd5f5ab4871fee0dace68fd00c4171f190311b8d7e93",
            "sum_initial": {
                "amount": 1000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "EUR"
            },
            "provider": {
                "id": 1084,
                "payment_id": "",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "hWvmXPJXJDqHIRKUEmzOC03v0VT9D3Ge/zHFuzsNFS/1Wif2hn6nLwvH/1iFk46
                                                           KM1nIwWl0yy1UJrBn092EUg=="
    }
}

The following is the example of a callback for a purchase declined due to time-out.

Figure: Example of a declined purchase callback

{
        "project_id": 35,
        "payment": {
            "id": "ECT_TEST_1568960683171",
            "type": "purchase",
            "status": "decline",
            "date": "2019-09-20T06:29:26+0000",
            "method": "Jeton Voucher",
            "sum": {
                "amount": 10000,
                "currency": "EUR"
            },
            "description": "ECT_TEST_1568960683171"
        },
        "account": {
            "number": "5635996349986598973"
        },
        "customer": {
            "id": "1"
        },
        "operation": {
            "id": 48215000003011,
            "type": "sale",
            "status": "decline",
            "date": "2019-09-20T06:29:26+0000",
            "created_date": "2019-09-20T06:29:25+0000",
            "request_id": "9ec787ad3527d63294723ad5f13e7d0e68cc65a7da6c8",
            "sum_initial": {
                "amount": 10000,
                "currency": "EUR"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "EUR"
            },
            "provider": {
                "id": 1084,
                "payment_id": "",
                "auth_code": ""
            },
            "code": "20602",
            "message": "Time-out"
        },
        "signature": "jdrCwc4xEkOxzHBK8QnnlIiXp9PByR837P8AdSbyxJRKaia2HY/BATGybRWfMJ
                                                        kWz4wIHkUknnm/z8PYsRQP9w=="
    }
}

Related topics

The following topics might be useful when implementing payments through Gate:

Payout by using Gate

General information

To perform a payout through the Jeton Voucher method, merchant's web service sends a request with all the required parameters and signature to ECommPay URL, and receives a callback with the payment result. The full sequence of the payout process is provided below.



Figure: Payout by using Gate

  1. A customer orders a payout through the Jeton Voucher system.
  2. Merchant's web service sends the request for the payout processing by using Gate to the appropriate ECommPay URL.
  3. Gate redirects the request to the ECommPay payment platform.
  4. The payment platform performs all the necessary checks and processes the request.
  5. The reply with the request processing results is sent to the merchant's web service. For more information, see Response format.
  6. The payment platform redirects the payout request to the Jeton Voucher service.
  7. The payout is processed on the Jeton Voucher side.
  8. Jeton Voucher sends the result notification to the payment platform.
  9. The payment platform sends a callback with the payment result to the web service.
  10. The customer receives the notification about the payout result with the issued voucher data from the web service.

The sections that follow discuss in more details the request format and the Gate parameters to use in the Jeton Voucher payment method and provide the information on the format of callbacks with payout results.

Request format

There are several things you must consider when using payout requests in the Jeton Voucher method:
  1. You send payout requests by sending the v2/payment/voucher/jeton/payout request by using HTTP method POST. This is voucher payment request group /v2/payment/voucher/{payment_method}/payout.
  2. The following objects and parameters must be specified in any request:
    • Object general—general payout information:
      • project_id—project identifier
      • payment_id—unique payout identifier
      • signature—signature created after you specify all the required parameters. For more information about signature generation, see Signature generation and verification
    • Object customer—customer information:
      • id—identifier,
      • ip_address—customer IP address
    • Object payment—payout information:
      • amount—payout amount
      • currency—payout currency in the ISO-4217 alpha-3 format.
  3. If required, you can also add any other additional parameters Gate supports.

Thus, a correct payment request in the Jeton Voucher method must include project and payment IDs, customer identifier and IP address, currency and amount of the payout, as shown in the following example:

Figure: Example of a payout request

"general": {
    "project_id": 35,
    "payment_id": "Payment 12",
    "signature": "2tlMuYxLW9Yu6RETr8pdCfmi0UPE8euD+2AbrQgJguu0BQjXWH6naC
                                    A9Ts6o4EVPjLyfbOQ+9ajAteg5lPk96Q=="
  },
  "customer": {
    "id": "123"
    "ip_address": "1.1.1.1",
  },
  "payment": {
    "amount": 10000,
    "currency": "EUR"
  }

Callback format

The Jeton Voucher method uses the standard format for callbacks to deliver payout results. For more information, see Callbacks.

The following is the example of a callback with an information about successful 540.00 EUR payout in the 199 project.

Figure: Example of a successful payout callback

{
        "request_id": "321b4f17cce71489321c5ade74b353e1f5d50f57090a93aa80ff75",
        "transaction": {
            "id": 17569000000764,
            "date": "2018-07-31T11:29:14+0000",
            "type": "payout"
        },
        "payment": {
            "id": "payoutvoucher5215",
            "method": "Jeton Voucher",
            "date": "2018-07-31T11:29:14+0000",
            "result_code": "0",
            "result_message": "Success",
            "status": "success",
            "is_new_attempts_available": false,
            "attempts_timeout": 0,
            "provider_id": 1084
        },
        "sum_real": {
            "amount": 54000,
            "currency": "EUR"
        },
        "general": {
            "project_id": 199,
            "payment_id": "payoutvoucher5215",
            "signature": "+D3YziB/jfIdGHJuoaE4Gh1qLWH5ZENyY+z06eCAB2VUfyg8IWqfKoGlj
                                                   nfydoHTsD/xS7LiV+Rw6a4ZiNsX1w=="
        },
        "description": "payoutvoucher",
        "sum_request": {
            "amount": 54000,
            "currency": "EUR"
        },
        "operations": [
            {
                "id": 17569000000885,
                "type": "payout",
                "status": "success",
                "date": "2018-07-31T11:29:14+0000",
                "processing_time": "2018-07-31T11:29:14+0000",
                "sum": {
                    "amount": 54000,
                    "currency": "EUR"
                },
                "code": "0",
                "message": "Success"
            }

The following is the example of the payout made for several vouchers in the 35 project.

Figure: Example of a successful payout callback for several vouchers

{
"project_id":35,
"payment":
{"id":"voucherpayout3",
"type":"payout",
"status":"success",
"date":"2018-07-10T11:48:15+0000",
"method":"JetonVoucher",
"sum":{"amount":10,"currency":"EUR"},
"description":"voucherpayout"},
"provider_extra_fields":
{"vouchers":[
{"voucherNumber":"4619483153895636584","expiration":"2019-07-10T11:48:14+00:00", 
                  "securityCode":"6666","createDate":"2018-07-10T11:48:14+0000"}
{"voucherNumber":"4619483153895636677","expiration":"2019-07-10T11:48:14+00:00",
                  "securityCode":"7777","createDate":"2018-07-12T11:48:14+0000"}
{"voucherNumber":"4619483153895636790","expiration":"2019-07-10T11:48:14+00:00",
                  "securityCode":"8888","createDate":"2018-07-13T11:48:14+0000"}
]},
"operation":{"id":11751000000566,
"type":"payout",
"status":"success",
"date":"2018-07-10T11:48:15+0000",
"created_date":"2018-07-10T11:48:13+0000",
"request_id":"d6648",
"sum_initial":{"amount":10,"currency":"EUR"},
"sum_converted":{"amount":10,"currency":"EUR"},
"provider":{"id":1084,"payment_id":"","date":"2018-07-10T11:48:14+0000","auth_code":""},
                                                        "code":"0","message":"Success"},
"signature":"kRQkDgdVc+Liiz4LNbbVezjj29EiRKMuRVrJRe0juhAsB0S8fT764aTcnkUtY6\/UOSc2xnXdHbvp+w=="
}

The following is the example of a callback for a payout declined due to insufficient funds on merchant balance.

Figure: Example of a declined payout callback

 {
        "request_id": "ee9d35692b14bd57495be9b736ddabf77e612ea5f51422f51e1e",
        "transaction": {
            "id": 12453000000760,
            "date": "2018-07-31T10:55:50+0000",
            "type": "payout"
        },
        "payment": {
            "id": "payoutvoucher5214",
            "method": "Jeton Voucher",
            "date": "2018-07-31T10:55:50+0000",
            "result_code": "20000",
            "result_message": "General decline",
            "status": "decline",
            "is_new_attempts_available": false,
            "attempts_timeout": 0,
            "provider_id": 1084
        },
        "sum_real": {
            "amount": 54000,
            "currency": "EUR"
        },
        "general": {
            "project_id": 199,
            "payment_id": "payoutvoucher5214",
            "signature": "Im3fkaa38MDoXBgftchG7MrEjNXcK34s/0Quh2w8BcJio2XAvBKhQkYovx
                                                     oTgEUJ14cpO1rBX3wqfo4eAA9VfQ=="
        },
        "description": "payoutvoucher",
        "sum_request": {
            "amount": 54000,
            "currency": "EUR"
        },
        "operations": [
            {
                "id": 12453000000861,
                "type": "payout",
                "status": "decline",
                "date": "2018-07-31T10:55:50+0000",
                "processing_time": null,
                "sum": {
                    "amount": 54000,
                    "currency": "EUR"
                },
                "code": "3028",
                "message": "Insufficient funds on merchant balance"
                }
]

Related topics

The following topics might be useful when implementing payments through Gate:

Analysis of payments results

As with other payment methods ECommPay offers, when using the Jeton Voucher method, you have several options to analyse the information about payments and operations performed by using the method—alone or in conjunction with other methods.

You can load and analyse all the necessary information in Dashboard, for instance you can use the analytic panels on the Analytics tab to this end.

Also, you can export the information for further analysis by using third party analytical tools. The following options are available:

  • Dashboard allows you to download reports in CSV and XLS formats—by using the tools on the Payments tab. You can perform export as a one-time download to your local computer or have payment data regularly exported and delivered to email addresses you specify.
  • Data API allows you to have payment information exported in JSON format and delivered to a URL you specify. The payment information is exported by using the /operations/get queries.

If you have any further questions regarding payment data analysis, contact ECommPay technical support.