Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Deposit of funds (API)

Warning
titleWarning!

This integration method is NOT recommended if you have not previously integrated similar payment solutions that require activationRecommended integration method

When choosing integration via API, we recommend that you additionally make the following improvements:

  1. Add hints in text form for each payment system (PS) to explain to a user all payment steps.
  2. Add a visual explanation of the payment process - gifs showing the process and screenshots of the payment steps.
  3. Screenshots and all the necessary minimum text information can be obtained directly from Paykassma TS.

Access to the shared API is implemented using a whitelist of IP addresses and a secret key. Before starting to work with the API for deposit, it is necessary to send to the Paykassma TS the Access to the shared API is implemented using a whitelist of IP addresses and a secret key. Before starting to work with the API for deposit, it is necessary to send to the Paykassma TS the IP address from which requests will be sent.

PLUGINAPI_SECRET - secret key string. It will need to be added to all requests in the form of the secret get parameter.
    For example: https://api.{URL_Paykassma_Server}/api/v1/deposit-info?secret=pluginapi_secret

When you send a request without using these parameters, the error 404 'Not found' will be displayed

Attention: Before starting to work with the API for deposit, it is necessary to send the IP address from which requests will be sent to the Paykassma TS.

When integrating via the API, we recommend that you make the following improvements on the client side:

  • Add tips for a user in the form of a text under each PS, specify a detailed description of the payment in them at each step.
  • Also add a visual explanation of the payment process, it can be .gif or screenshots
  • without using these parameters, the error 404 'Not found' will be displayed

    Attention: Before starting to work with the API for deposit, it is necessary to send the IP address from which requests will be sent to the Paykassma TS.

    This and all necessary information can be obtained directly from the Paykassma TS

    Obtaining available PSs

    Code Block
    themeRDark
    titleAPI url
    https://api.{URL_Paykassma_Server}/api/v1/payment-systems/available

    Request method: GET

    Format: JSON

    Parameters:

    Parameter

    Type

    Required

    Description

    currency_code

    string[] (3)

    YES

    An array consisting of currency codes. PS that work with the specified currencies will be displayed

    label

    string (190)

    YES

    Unique identifier (ID) of the user making the payment

    Code Block
    themeDJango
    titleRequest
    {
        "currency_code": [ "USD", "INR" ],
        "label": "55"
    }


    Code Block
    themeDJango
    titleResponse Success
    collapsetrue
    {
      "status": "ok",
      "params": {
        "gif_guide": {
          "upi": "http:\/\/api.pay.test\/storage\/guide-image\/upi.mp4?cache=1587635151",
          "phonePe": "http:\/\/api.pay.test\/storage\/guide-image\/phonePe.gif?cache=1589958899",
          "bkash": "http:\/\/api.pay.test\/storage\/guide-image\/bkash.mpg?cache=1611553163"
        },
        "currency_data": [
          {
            "code": "INR",
            "symbol": "₹"
          }
        ],
        "wallets": [
          {
            "type": "paytm",
            "currency_code": "INR",
            "order": 5,
            "logo": "http:\/\/api.pay.test\/storage\/payment_system\/logos\/paytm_default.svg",
            "name": "PayTM"
          },
          {
            "type": "paytm",
            "currency_code": "INR",
            "order": 5,
            "logo": "http:\/\/api.pay.test\/storage\/payment_system\/logos\/paytm_34.svg",
            "name": "paytm",
            "hints": [
              {
                "type": "requisites_hint",
                "text": null
              },
              {
                "type": "payment_hint",
                "text": null
              },
              true
            ],
            "show_limits": true
          }
        ],
          "imps": {
            "INR": {
              "min": "8000",
              "max": "560000"
            }
          },
          "bkash": {
            "BDT": {
              "min": "100",
              "max": "1000000"
            }
          },
          "upi": {
            "INR": {
              "min": "20000",
              "max": "50000"
            }
          },
          "paytm": {
            "INR": {
              "min": "100000",
              "max": "20000000"
            }
          },
          "phone_pe": {
            "INR": {
              "min": "100",
              "max": "800000"
            }
          }
        }
      }
    }


    Code Block
    themeDJango
    titleResponse Fail
    {
        "status": "fail"
        "message": "MESSAGE"
    }

    Creating a payment

    Currently, there are two types of requests for creating a payment, depending on the PS.

    Info

    Attention! To get a complete list of available PSs, you need to contact Paykassma TS. TS will provide complete examples of requests for currently available PSs. They will also determine the correct request, depending on the selected PS.


    For PS that require payment activation

    1. Payment creation request:

    Code Block
    themeRDark
    titleAPI url
    https://api.{URL_Paykassma_Server}/api/v1/transaction/create/{wallet_type}
    Example of request for PS PayTM
    Code Block
    themeRDark
    titleAPI url
    https://api.{URL_Paykassma_Server}/api/v1/transaction/create/paytm

    Request method: POST

    Format: JSON

    Parameters:

    Parameter

    Type

    Required

    Description

    currency

    string (3)

    YES

    Currency code

    label

    string (190)

    YES

    Unique identifier of the user making the payment

    Code Block
    themeDJango
    titleRequest
    {
        "currency": "INR",
        "label": "eligendi"
    }


    Code Block
    themeDJango
    titleResponse Success
    {
        "status": "ok",
        "params":  {
            "identifier": "6234234234"
                          }
    }


    Code Block
    themeDJango
    titleResponse Fail
    {
        "status": "fail"
        "message": "MESSAGE"
    }

    2. Activation request: 

    Code Block
    themeRDark
    titleAPI url
    https://api.{URL_Paykassma_Server}/api/v1/transaction/activate

    Request method: POST

    Format: JSON

    Parameters:

    Parameter

    Type

    Required

    Description

    currency_code

    string (3)

    YES

    Currency code

    wallet_type

    string (190)

    YES

    Value from the list of available PSs.
    Attention: To get a complete available list, contact Paykassma TS.

    label

    string (190)

    YES

    Unique identifier of the user making the payment

    key1

    string (190)

    YES

    A code on which activation is performed (Transiction_ID), received from the user

    amountnumeric*required ifTransaction amount 

    custom_transaction_id

    string (190)

    NO

    Transaction ID in the Client’s system

    Code Block
    themeDJango
    titleRequest
    {
        "currency_code": "USD",
        "wallet_type": "paytm",
        "label": "55",
        "key1": "123-ABC-456-DEF"
        "custom_transaction_id": "123465477897"
    }


    Code Block
    themeDJango
    titleResponse Success
    {
        "status": "ok"
    }


    Code Block
    themeDJango
    titleResponse Fail
    {
        "status": "fail"
        "message": "MESSAGE"
    }

    *For some PS, it is also necessary to send the amount field in the request:

    Payment systemcurrency_codewallet_typelabelkey1amountcustom_transaction_id
    IMPS/UPIrequiredrequiredrequiredrequiredrequired-
    Paytmrequiredrequiredrequiredrequired--
    PhonePerequiredrequiredrequiredrequiredrequired-
    bKashrequiredrequiredrequiredrequired--
    Nagadrequiredrequiredrequiredrequired--

    For PS that do not require payment activation

    Payment creation request:

    Code Block
    themeRDark
    titleAPI url
    https://api.{URL_Paykassma_Server}/api/v1/payment/create/{payment_system}

    Request method: POST

    Format: JSON

    Parameters:

    Parameter

    Type

    Required

    Description

    language

    string (2)

    YES

    Interface language

    currency

    string (3)

    YES

    Currency code

    bank

    string (3)

    YES

    The bank via which the payment is performed

    amount

    numeric 

    (ограничена max.
    депозитом)

    YES

    Payment amount

    label

    string (190)

    YES

    Unique identifier of the user making the payment

    redirect_url

    url 

    YES

    URL of the page for redirecting after payment

    custom_transaction_id

    string (190)

    NO

    Transaction ID in the Client’s system

    Code Block
    themeDJango
    titleRequest
    {
       "language": "en",
       "currency": "USD",
       "bank": "MBB",
       "amount": "1000",
       "label": "55",
       "redirect_url": "https:\/\/google.com"
       "custom_transaction_id": "123465477897"
    }


    Code Block
    themeDJango
    titleResponse Success
    {
        "status": "ok"
    }


    Code Block
    themeDJango
    titleResponse Fail
    {
        "status": "fail"
        "message": "MESSAGE"
    }

    Information about savings

    To save information about transactions, the amount of which does not exceed the minimum deposit amount for a particular payment system, the functionality of savings has been implemented. The user's transactions (selected by the label parameter) are accumulated in the system and are not credited to the user's account until their amount reaches the minimum deposit amount of this payment system. The postback will be sent to the client's server only after the minimum deposit amount is reached. Until the postback is sent, the transaction is not considered credited to the account.

    In the postback of deposit transactions, you can see the Stockpiling field, it contains the amount of transactions involved in the accumulation (one or more transactions) converted to all currencies. Conversion is carried out on the basis of open data on exchange rates. All currencies are transmitted with an accuracy of up to hundredths, cryptocurrencies have 8 digits in the fractional part (one hundred millionth accuracy). And in field transactions Information about completed transactions participating in the accumulation (one or more) is transmittedPassed as an list.

    Request to provide information about savings of a certain user

    Code Block
    themeRDark
    titleAPI url
    https://api.{URL_Paykassma_Server}/api/v1/deposit-info

    Request method: GET

    Format: JSON

    Parameters:

    Parameter

    Type

    Required

    Description

    label

    string (190) 

    YES

    Unique identifier of the user making the payment

    wallet_type

    url 

    YES

    Value from the list of available PSs.
    Attention: To get a complete available list, contact Paykassma TS.

    currency

    string (3)

    YES

    Currency code

    code

    string (190) 
    or “null”

    NO

    Name of the manual payment system.
    It’s filled in when wallet_type = manual

    Code Block
    themeDJango
    titleRequest
    {
       "label": "55",
       "wallet_type": "paytm",
       "currency": "UDS"
    }


    Code Block
    themeDJango
    titleResponse Success
    {
        "status": "ok"
        "stockpiling_sum": 0,
        "lacks_sum": 0,
        "minimum_deposit": 148
    }


    Code Block
    themeDJango
    titleResponse Fail
    {
        "status": "fail"
        "message": "MESSAGE"
    }

        < Home

    Withdrawal of funds (API, actual version)

    To withdraw funds by the user via payment systems available to the Client, it is necessary to:

    1. Once send Paykassma TS the URL of the server where postbacks with the withdrawal status will be sent.
    2. Send withdrawal requests (POST) to the URL, without using "secret = pluginapi_secret":

      Code Block
      themeRDark
      titleAPI url
      https://api.{URL_Paykassma_Server}/v2/withdrawal/create
    Warning

    Attention: When transmitting data, there should be no spaces at the beginning and end

    Each withdrawal request is signed by signature, it is formed as follows:

    Signature generation algorithm

    1. Your private key is initialized.
    2. An array with data that will be hashed is formed. The array can be multidimensional.
    3. The array elements are recursively concatenated with each other via ":" string.
    4. Then md5 hash of the resulting string is allocated.
    5. The private key is concatenated with a hash string.
    6. Then sha1 hash is allocated from the resulting string.


    Code Block
    languagephp
    themeDJango
    titleAn example of forming a signature in php
    $data = [
        ...
    ];
     
    $data['signature'] = generateSignature($data); // return fa0ee1e2acf7f898635ec417491381c0a4f9d35c
     
    //send $data like json ...
     
    function generateSignature(array $data) {
        $privateKey = 'yourprivatekey';
        ksort($data);
        $implode = self::multiImplode( ':', $data);
        return sha1($privateKey . md5($implode));
    }
     
     
    function multiImplode($glue, $array): string
        {
            $finArray = [];
        foreach ($array as $val) {
            $finArray[] = is_array($val) ? self::multiImplode($glue, $val) : $val;
        }
        return implode($glue, $finArray);
    }

    Required parameters for transmission in POST request:

    Parameter

    Type

    Required

    Description

    withdrawal_idstring(1-36) optional Withdrawal ID, if the parameter is not passed, then the system generates withdrawal _id
    payment_systemstring requiredPayment system
    amountintrequired
    Additional requirements:
    1. amount >= The value of the set minimum value
    2. amount <=The value of the set maximum value
    Note
    titleMultiplicity

    For PS PayTM: amount is a multiple of "10".

    currency_codestring(3) requiredCurrency code
    labelstring required

    Unique identifier of the user making the payment

    account_numberstring 

    *required_if
    PS = bkash,imps,
    upi,paytm,....

    Number of the bank account

    Note
    titleInput mask

    For PS PayTM: Numbers (10) (without international code +91) For PS UPI / IMPS: Numbers

    account_namestring *required_if
    PS = imps,
    upi,....

    Name of the bank account holder

    account_emailstring *required_if
    PS = bkash,...

    Email of the person who is being paid

    payments_details.payments_methodstring *required_if
    Payment method
    payments_details.payments_providerstring optionalSupplier who makes electronic payment using the selected payment method
    bank_details.bank_codestring*required_if

    Unique ID assigned by the country's central bank

    Note
    titleInput mask

    For PS UPI / IMPS: IFSC code Alphabetic(4)Figures(7). Details: https://en.wikipedia.org/wiki/Indian_Financial_System_Code

    bank_details.branch_codestring*required_ifBank branch code
    bank_details.bank_code_in_payments_systemstring*required_if

    Bank code in payments system, with which data is exchanged

    account_typestring*required_ifAccount type
    document_typestring*required_ifDocument type
    document_idstring*required_if
    Recipient document ID
    account_digitstring*required_ifAccount digit
    ibanstring*required_ifIBAN
    Info
    *The withdrawal request contains fields that are required only for some payment systems (required_if), to get a complete list of required fields for a specific payment system, you need to contact Paykassma technical support.

    Required fields for PS Bkash, PayTm, IMPS/UPI:

    Payment systemaccount_numberaccount_nameaccount_emailpayments_detailsbank_details
    payments_methodpayments_providerbank_codebranch_codebank_code_in_payment_system

    Bkash

    required-required-----
    IMPS/UPIrequiredrequired---required--
    Paytmrequired-------

    Request:

    Code Block
    themeDJango
    titleПример тела запроса
    {
    	'withdrawal_id': '1234567',
        'payment_system': 'paytm',
    	'amount' : '1000',  
        'currency_code': 'INR',
    	'label': '55',        
    	'comment': 'withdrawal',       
    	'account_number': '11111111'
    }
    Code Block
    languagephp
    titleResponse Success
    {
        'status': 'ok'
    }
    Code Block
    languagephp
    titleResponse Fail
    {
        'status': 'fail'
        'message': 'MESSAGE'
    }

    After processing the withdrawal, Paykassma will send a postback about the result of the withdrawal with a status, signed with a signature.

    Withdrawal status

    StatusDescription
    PROCESSED (1)

    Uccessful

    REJECTED (5)Unsuccessful

    Withdrawal of funds (API, the outdated version is not longer supported)

    API url:

    Code Block
    themeDJango
    https://api.{URL_Paykassma_Server}/withdrawal/manual/create


    Required parameters for transmission in POST request:

    Parameter

    Type

    Description

    wallet_type

    text(191)

    Selection from the available list

    Type of the payment system

    wallet_recipient

    string(191)

    The recipient's wallet, to whose account the payment will be made

    Attention! wallet_recipient (For the Paytm method) must contain the Paytm wallet number without the international code +91

    wallet_sender

    string(191)

    The sender's wallet, from whose account money will be withdrawn. The final choice of the sender is left to Paykassma.

    Attention: it is necessary to fill in the field with arbitrary four digits

    account_name

    string(191)

    Name of the bank account holder

    account_number

    string(191)

    Number of the bank account

    email

    string(191)

    Email of the person who is being paid

    amount

    Double

    Withdrawal amount

    withdrawal_id

    Integer

    Client side withdrawal ID (returned in postback ).

    Request:

    Code Block
    themeDJango
    {
        "wallet_type":"paytm",
        "wallet_recipient":"123123232",
        "wallet_sender":1111,
        "email":"[email protected]",
        "amount":1000,
        "withdrawal_id":"13",
        "signature":"fae51673a8a9c85f724317214bd0bcc665ebc799"
    }
    When sending a withdrawal request to Paykassma, the first response received the generated data on the request, without a signature:

    Example first response:

    Code Block
    themeDJango
    {
        "id":1,
        "wallet_type":"paytm",
        "wallet_recipient":"123123232",
        "wallet_sender":"1111",
        "email":"[email protected]",
        "amount":1000,
        "status":1,
        "created_at":"2020-07-08 07:06:06",
        "updated_at":"2020-07-08 09:40:39"
    }
    StatusDescription
    NEW (0)

    In processing

    CANCELED (2)

    Unsuccessful

    PROCESSED (1)

    Uccessful


    The second response will already come a postback about the withdrawal, signed by the signature.

        < Home

    Table of Contents