Menu

JETON MERCHANT INTEGRATION GUIDE

Version 1.5.1

Initial Version History

Version Release date Description
2.0.0 20-10-2017 New endpoints
1.5.1 04-02-2017 Payment Steps (Response)
1.5.0 04-02-2017 Payment Details
1.4.0 03-02-2017 Payment Status
See All History

1. Merchant Sign-up

New merchant will need to provide the information listed below:

  • Merchant logo (image type and size will be provided in detail)
  • Merchant name (will be displayed on the payment page)
  • Mobile number with country code (an SMS will be sent to this phone number)
  • Email Address

Our team will provide the test credentials to you to start the integration.

2. Merchant Integration

After securing further validations, an application key (apiKey) will be created for secure payment initialization, which will be provided by Jeton Technical Team.

2.1 Back-end Integration

A. Payment Flow
  • InitiatePayment - service should be called in a secure way, then Jeton Pay will provide a payment token and payment URL in relation to the request. We kindly recommend users to store unique Jeton payment IDs and create an Authorization Token to access details and statuses of each payment. Each payment token expires in 15 minutes. If you want to query your payment status or details after expiration time, you have to generate new Authorization Token and use the same Jeton paymentId.


    Parameter Description Example Type *
    orderId Merchant's transaction identifier ABC123DEF String Required
    paymentAmount It's the amount of the transaction 15 String Required
    currencyCode It's the currency of the transaction EUR String Required
    customerNumber To allow customer to login with requested id only 11223344 String Optional
    successRedirectUrl Your customer will be redirected, after successful purchase http://yourdomain.com?a=success String ?
    cancelRedirectUrl Customer will be redirected, if the purchase is cancelled http://yourdomain.com?b=cancel String ?
    failRedirectUrl Customer will be redirected, if the purchase fails http://yourdomain.com?c=fail String ?
    paymentItems Customer will be redirected, if the purchase fails Please check the Request Example below List Optional

    Request :
    URL: https://sandbox-walletapi.jeton.com/api/v2/integration/merchant/initiate-payment
    Request Type: POST
    
    Headers:
    {
       "X-PAY-API-KEY: apiKey"
       "Content-Type: application/json"
    }
    
    Parameters:
    {
      "paymentAmount":"15",
      "currencyCode":"EUR",
      "orderId": "ABC123DEF",
      "successRedirectUrl":"http://www.yourdomain.com?a=success",
      "cancelRedirectUrl": "http://www.yourdomain.com?b=cancel",
      "failRedirectUrl": "http://www.yourdomain.com?c=fail",
      "customerNumber":"11223344"
      "paymentItems":[
      {
        "amount":10.45,
        "count":1,
        "description":"First Pay Transaction Item"
      },
      {
        "amount":3.15,
        "count":1,
        "description":"Second Pay Transaction Item"
      }
      ]
    }
    
    Response :
    {
      "token": "eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIzIiwibWVyY2hhbnRJZCI6MywicGF5bWVudElkIjoyODAzLCJleHAiOjE0ODA1NDI0ODIsImlhdCI6MTQ4MDUzODg4Mn0.QkHg7gZRcs-TznU_gHJCOMgHeIVYqjlDL7gkH4hDzg4eB0JiLMA3o2zmRtNBW_aOt-quHHU8yJJQor9qgD2K_g",
      "redirectUrl": "https://sandbox-wallet.jeton.com/pay?token=eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIzIiwibWVyY2hhbnRJZCI6MywicGF5bWVudElkIjoyODAzLCJleHAiOjE0ODA1NDI0ODIsImlhdCI6MTQ4MDUzODg4Mn0.QkHg7gZRcs-TznU_gHJCOMgHeIVYqjlDL7gkH4hDzg4eB0JiLMA3o2zmRtNBW_aOt-quHHU8yJJQor9qgD2K_g",
      "paymentId":1234
    }
    
  • Trigger Checkout page - The URL, which will be provided in the previous response, should be opened in a page, tab or any other method that you prefer.

    Sample URL: https://sandbox.jeton.com/pay?token=myToken


    img
    img



  • Back to Merchant - After Individual Jeton Pay user’s payment is successfully completed, Jeton Pay will return to you a success URL in the initiatePayment request. If the payment fails or is canceled due to a customer action, then Jeton Pay will redirect customer to the given fail URL or cancel URL. These will also be included in initiatePayment response.
    Response :
    http://www.yourdomain.com?a=success&paymentId=1234&customerNumber=11223344
B. Authentication of Merchant - for other requests, such as payment statuses etc., you can use the token that is returned in the response header.
Parameter Description Example Type *
apiKey Your provided apiKey from Jeton's technical team ABCDEF123456 String Required

Request :
URL: https://sandbox-walletapi.jeton.com/api/v2/integration/merchant/authorize
Request Type: POST

Headers :
{
   "Content-Type: application/json"
}

Parameters:
{
  "apiKey": "myApiKey"
}
Response (Header) :
Authorization→eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJudWxsIiwibWVyY2hhbnRJZCI6bnVsbCwiZXhwIjoxNDgwNjAyMDkxLCJpYXQiOjE0ODA1OTg0OTF9.Z5_ZaPHZ6D1P4xvWBwWGdN1VVgLZK6FyEyStMnRS_s5pc7NU62ar_mttqlwSontKkStUn1Poy4ToWFxSfO35FA
C. Payment Status

This service allows you to check your transaction status. To use this service you have to send one of the required parameters which is either paymentId or merchantOrderId with Authentication Token.

Parameter Description Example Type *
paymentId Jeton's transaction identifier 1234 Int Required
merchantOrderId Merchant's transaction identifier ABC123DEF String Required

Request :
URL: https://sandbox-walletapi.jeton.com/api/v2/integration/merchant/payment-status
Request Type: POST

Headers :
{
   "Authorization: myToken"
   "Content-Type: application/json"
}

Parameters:
{
   "paymentId":1234
}

    or

{
   "merchantOrderId":"ABC123DEF"
}
Response :
{
  "paymentId": 1234,
  "merchantOrderId": "ABC123DEF",
  "customerNumber": "11223344",
  "currencyCode": "EUR",
  "amount": 100,
  "status": "PROCESSING",
  "paymentJourneyStatus": "COMPLETE_YOUR_PROFILE_STEP",
  "errorCode": null,
  "errorMessage": null
}
D. Payment Details

This service allows you to see full details of your transactions. To use this service you have to send one of the required parameters which is either paymentId or merchantOrderId with Authentication Token.

Parameter Description Example Type *
paymentId Jeton's transaction identifier 1234 Int Required
merchantOrderId Merchant's transaction identifier ABC123DEF String Required

Request :
URL: https://sandbox-walletapi.jeton.com/api/v2/integration/merchant/payment/details
Request Type: POST

Headers:
{
   "Authorization: myToken"
   "Content-Type: application/json"
}

Parameters:
{
   "paymentId":1234
}

    or

{
   "merchantOrderId":"ABC123DEF"
}
Response :
{
  "paymentId": 1234,
  "merchantOrderId": ABC123DEF,
  "customerNumber": 11223344,
  "paymentAmount": 15,
  "currencyCode": "EUR",
  "paymentItems": [
    {
      "id": 1235,
      "amount": 2.55,
      "count": 1,
      "description": "First Pay Transaction Item",
      "creationDate": 1486402122337,
      "lastModificationDate": 1486402122337,
      "deleted": false
    },
    {
      "id": 1236,
      "amount": 12.45,
      "count": 1,
      "description": "First Pay Transaction Item",
      "creationDate": 1486402122338,
      "lastModificationDate": 1486402122338,
      "deleted": false
    }
  ],
  "paymentType": null,
  "status": "INITIALIZED",
  "successRedirectUrl": "http://www.yourdomain.com?a=success",
    "cancelRedirectUrl": "http://www.yourdomain.com?a=cancel",
    "failRedirectUrl": "http://www.yourdomain.com?a=fail",
}


E. Pay Out Service

Service for creating a new money transfer directly to the customer's account without holding it as pending. Response will be return as Approved straight away unless something goes wrong.

Parameter Description Example Type *
createPendingWalletTransfer Parameter listing - List Required
receiverCustomerNumber Payment receiver 11223344 String Required
amount The amount of the transaction 100 Int Required
currencyCode The currency of the transaction EUR String Required
note The description or reference of the payment Gift String Required

Request :
URL: https://sandbox-walletapi.jeton.com/api/v2/integration/merchant/pay-out-transfer
Request Type: POST

Headers:
{
   "Authorization : myToken"
   "Content-Type : application/json"
}

Parameters:
{
  "createPendingWalletTransfer": {
    "receiverCustomerNumber": "11223344",
    "amount": "100",
    "currencyCode": "EUR",
    "note":"Payment description"
  }
}

Response:
{
  "header":
   {
     "statusCode": 200,
     "errors": null,
     "errorParameters": null
   }
}

3. Appendices

A. Currency Code Format

The alphabetic code is based on another ISO standard, ISO 3166, which lists the codes for the country names. The first two letters of the three-letter ISO 4217 code are the same as the code for the country’s name, and where possible, the third letter corresponds to the first letter of the currency’s name.

For example:

  • The “US dollar” is represented as USD - the US comes from the ISO 3166 country code and the D from “dollar”.
  • The Swiss franc is represented by CHF - the CH being the code for Switzerland in the ISO 3166 code and F for franc.
You can reach the full list at:
http://www.nationsonline.org/oneworld/currencies.htm
B. Country Format

(ISO) under its standard ISO 3166 has established two-letter (2-alpha) and three-letter (3-alpha) codes for the various countries of the world, including independent states, dependent areas, and certain areas of contested jurisdiction or special status. The two-letter code version is preferred by JetonPay.

You can reach the full list at:
http://www.nationsonline.org/oneworld/country_code_list.htm
C. Phone Format

Country calling codes or country dial in codes are telephone dialing prefixes for the member countries of the International Telecommunication Union (ITU).

You can reach the full list at:
http://www.nationsonline.org/oneworld/international-calling-codes.htm

4. Server Side

A. Security Notes

For our Server informations and security notes is being updated time to time. Please check all information before start to integrate.

  • Currently, our servers support only TLSv1.2 with the ciphers listed below. Please make sure that the clients and/or libraries you're using on your applications have support for TLSv1.2 accordingly
    TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 (secp256r1)
    TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 (secp256r1)
    TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA (secp256r1)
    TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (secp256r1)
    TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 (secp256r1)
    TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA (secp256r1)
    TLS_RSA_WITH_AES_128_GCM_SHA256 (rsa2048)
    TLS_RSA_WITH_AES_128_CBC_SHA256 (rsa2048)
    TLS_RSA_WITH_AES_128_CBC_SHA (rsa2048)
    TLS_RSA_WITH_AES_256_GCM_SHA384 (rsa2048)
    TLS_RSA_WITH_AES_256_CBC_SHA256 (rsa2048)
    TLS_RSA_WITH_AES_256_CBC_SHA (rsa2048)

5. Plugin

WordPress WooCommerce

WooCommerce is a free eCommerce plugin that allows you to sell anything, beautifully. Built to integrate seamlessly with WordPress, WooCommerce is the world’s favorite eCommerce solution that gives both store owners and developers complete control.

Jeton Wallet plugin for WooCommerce allows you to accept payments directly on your store.

Download Plugin

Change Logs

Version Release date Description
1.5.1 04-02-2017 Payment Steps (Response)
1.5.0 04-02-2017 Payment Details
1.4.0 03-02-2017 Payment Status
1.3.1 02-02-2017 Initiate Payment : paymentId (Response)
1.3.0 02-02-2017 Initiate Payment : customerNumber (Request)
1.2.0 01-02-2017 Security Notes
1.1.1 01-02-2017 currencyId changed to currencyCode
1.1.0 31-01-2017 Direct Payout Service
1.0.0 30-11-2016 Initial Release: Pay with Jeton Wallet