Deposit of funds (API)
Warning!
This integration method is NOT recommended if you have not previously integrated similar payment solutions that require activation. Recommended integration method
When choosing integration via API, we recommend that you additionally make the following improvements:
- Add hints in text form for each payment system (PS) to explain to a user all payment steps.
- Add a visual explanation of the payment process - gifs showing the process and screenshots of the payment steps.
- Screenshots and all the necessary minimum text information can be obtained directly from Paykassma TS.
Access to the shared API is implemented using a secret key. 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.
Obtaining available PSs
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 |
{
"currency_code": [ "USD", "INR" ],
"label": "55"
}
{
"status": "ok",
"params": {
"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_ib": {
"INR": {
"min": "8000",
"max": "560000"
}
},
"bkash": {
"BDT": {
"min": "100",
"max": "1000000"
}
},
"upi_ib": {
"INR": {
"min": "20000",
"max": "50000"
}
},
"paytm": {
"INR": {
"min": "100000",
"max": "20000000"
}
},
"phone_pe": {
"INR": {
"min": "100",
"max": "800000"
}
}
}
}
}
{
"status": "fail"
"message": "MESSAGE"
}
Creating a payment
Currently, there are two types of requests for creating a payment, depending on the PS.
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:
https://api.{URL_Paykassma_Server}/api/v1/transaction/create/{wallet_type}
Example of request for PS PayTM
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 |
{
"currency": "INR",
"label": "eligendi"
}
{
"status": "ok",
"params": {
"identifier": "6234234234"
}
}
{
"status": "fail"
"message": "MESSAGE"
}
2. Activation request:
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. |
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 |
| amount | numeric | *required if | Transaction amount |
custom_transaction_id | string (190) | NO | Transaction ID in the Client’s system |
{
"currency_code": "USD",
"wallet_type": "paytm",
"label": "55",
"key1": "123-ABC-456-DEF"
"custom_transaction_id": "123465477897"
}
{
"status": "ok"
}
{
"status": "fail"
"message": "MESSAGE"
}
{
"status": "possible_transaction_created",
"message": "Transaction not found. Possible transaction created"
}
**For some PS, it is also necessary to send the amount field in the request:
| Payment system | currency_code | wallet_type | label | key1 | amount | custom_transaction_id |
|---|---|---|---|---|---|---|
| IMPS IB/UPI IB | required | required | required | required | required | - |
| Paytm | required | required | required | required | - | - |
| PhonePe | required | required | required | required | required | - |
| bKash | required | required | required | required | - | - |
| Nagad | required | required | required | required | - | - |
For PS that do not require payment activation
Payment creation request:
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 | 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 |
{
"language": "en",
"currency": "USD",
"bank": "MBB",
"amount": "1000",
"label": "55",
"redirect_url": "https:\/\/google.com"
"custom_transaction_id": "123465477897"
}
{
"status": "ok"
}
{
"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 transmitted. Passed as an list.
Request to provide information about savings of a certain user
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. |
currency | string (3) | YES | Currency code |
code | string (190) | NO | Name of the manual payment system. |
{
"label": "55",
"wallet_type": "paytm",
"currency": "UDS"
}
{
"status": "ok"
"stockpiling_sum": 0,
"lacks_sum": 0,
"minimum_deposit": 148
}
{
"status": "fail"
"message": "MESSAGE"
}
Redirect addresses hashing
The widget code contains parameters for specifying redirect addresses. Addresses must be specified in hashed form. To hash addresses send the request:
https://api.{URL_server_Paykassma}/payment-plugin/hash-url
Request method: POST
Format: JSON
Parameters:
Parameter | Type | Required | Description | |
| success_urls | array | YES | List of redirect addresses when the payment is successful. | |
| order | integer | *YES | Redirect address number in the list. | |
| url | string | *YES | Redirect address when the payment is successful. | |
| fail_urls | array | YES | List of redirect addresses when the payment is failed. | |
| order | integer | *YES | Redirect address number in the list. | |
| url | string | *YES | Redirect address when the payment is failed. | |
*One of the success_urls or fail_urls arrays can be empty.
{
"success_urls": [
{
"order": 2,
"url": "https://test.com/success2.jpg"
},
{
"order": 1,
"url": "https://test.com/success1.jpg"
}
],
"fail_urls": [
{
"order": 1,
"url": "https://test.com/fail1.jpg"
},
{
"order": 2,
"url": "https://test.com/fail2.jpg"
}
]
}
{
"status": "ok",
"urls": {
"success_url": [
{
"order": 1,
"url": "a93558ba9e4f04eef3b1f759ae4281305776559ce86ae2af5f6e6498d84b99be"
},
{
"order": 2,
"url": "7c51f9d6b35a80a8fcce9cf3f4f0ae56b818c2e375a8b3297cb3fafb41a921eb"
}
],
"fail_url": [
{
"order": 1,
"url": "8b99db57e0bda63400b0e852d7fe73d8c6da52b8e32894987a8bd00bcadf8c66"
},
{
"order": 2,
"url": "e72ed31e2f3814563a3bc446f6a59f43c946c3a4339c7b2f5c29d12e8066b37c"
}
]
}
}
{
"status": "fail"
"message": "MESSAGE"
}
The received address hashes must be specified in the parameters of the widget code.
Attention!
The hash lifetime is 1 day. After the expiration date resend the request to get hash for the address if necessary.
Withdrawal of funds
To withdraw funds by the user via payment systems available to the Client, it is necessary to:
- Once send Paykassma TS the URL of the server where postbacks with the withdrawal status will be sent.
Send withdrawal requests (POST) to the URL, without using "secret = pluginapi_secret":
API urlhttps://api.{URL_Paykassma_Server}/v2/withdrawal/create
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
- Your private key is initialized.
- An array with data that will be hashed is formed. The array can be multidimensional.
Array elements are sorted by key using the ksort() function
- The array elements are recursively concatenated with each other via ":" string.
- Then md5 hash of the resulting string is allocated.
- The private key is concatenated with a hash string.
- Then sha1 hash is allocated from the resulting string.
$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_id | string(1-36) | optional | Withdrawal ID, if the parameter is not passed, then the system generates withdrawal _id |
| payment_system | string | required | Payment system |
| amount | int | required | Additional requirements:
Multiplicity For PS PayTM: amount is a multiple of "10". |
| currency_code | string(3) | required | Currency code |
| label | string | required | Unique identifier of the user making the payment |
is_test | boolean | required | The is_test parameter possible values: true - if Withdrawal is test |
| account_number | string | *required_if | Number of the bank account Input mask For PS PayTM: Numbers (10) (without international code +91) For PS UPI IB/ IMPS IB: Numbers |
| account_name | string | *required_if PS = imps_ib, upi_ib,.... | Name of the bank account holder |
| account_email | string | *required_if PS = bkash,... | Email of the person who is being paid |
| payments_details.payments_method | string | *required_if | Payment method |
| payments_details.payments_provider | string | optional | Supplier who makes electronic payment using the selected payment method |
| bank_details.bank_code | string | *required_if | Unique ID assigned by the country's central bank Input mask For PS IMPS IB: IFSC code - the length should be 11 characters, contain letters and numbers without spaces and dashes.. Details: https://en.wikipedia.org/wiki/Indian_Financial_System_Code |
| bank_details.branch_code | string | *required_if | Bank branch code |
| bank_details.bank_code_in_payments_system | string | *required_if | Bank code in payments system, with which data is exchanged |
| account_type | string | *required_if | Account type |
| document_type | string | *required_if | Document type |
| document_id | string | *required_if | Recipient document ID |
| account_digit | string | *required_if | Account digit |
| iban | string | *required_if | IBAN |
Information
Required fields for PS Bkash, PayTm, IMPS IB/UPI IB:
| Payment system | account_number | account_name | account_email | payments_details | bank_details | |||
|---|---|---|---|---|---|---|---|---|
| payments_method | payments_provider | bank_code | branch_code | bank_code_in_payment_system | ||||
Bkash | required | - | required | - | - | - | - | - |
| IMPS IB | required | required | - | - | - | required | - | - |
| Paytm | required | - | - | - | - | - | - | - |
Request:
{
"withdrawal_id": "1234567",
"payment_system": "paytm",
"amount" : 1000,
"currency_code": "INR",
"label": "55",
"is_test": false,
"comment: "withdrawal",
"account_number": "11111111",
"signature":"fae51673a8a9c85f724317214bd0bcc665ebc799"
}
{
"status": "ok"
}
{
"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
| Status | Description |
|---|---|
| PROCESSED (1) | Uccessful |
| REJECTED (5) | Unsuccessful |
Information about the postback that was sent earlier
Request to provide information about the postback that was sent earlier.
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}/api/v1/postback?secret=pluginapi_secret
https://api.{URL_server_Paykassma}/api/v1/postback
Request method: GET
Format: JSON
Parameters:
Parameter | Type | Required | Description |
type | string | required | Type of postback. Possible values:
|
transaction_id | string | One of the parameters is required if type = deposit | Transaction number |
| custom_id | string | Order ID If Paykassma contains several transactions with the same Order ID, only one of them will be selected. For this reason, the uniqueness of custom_id must be controlled on the Client's system. | |
| withdrawal_id | string | Is required if type = withdrawal | Withdrawal ID |
{
"status": "ok",
"postback": {
"transaction_id": "453535345",
"label": "435",
"stockpiling": {
"USD": 4610062.05,
"INR": 345345345,
"EUR": 3983190.43,
"IDR": 65837909699.54,
"MYR": 19134062.55,
"VND": 104893839449.17,
"SGD": 6221984.08,
"THB": 153749990.51,
"NGN": 1898193050.29,
"TRY": 43873352.03,
"AED": 16933679.93,
"CAD": 5706403.96,
"AUD": 6134591.13,
"BDT": 394891290.79,
"AFN": 418156964.72,
"ALL": 488772456.91,
"AMD": 2202143869.02,
"AOA": 2752207045.6,
"ARS": 459519460.28,
"AWG": 8300416.73,
"AZN": 7840816.59,
"BAM": 7789732.49,
"BBD": 9220124.11,
"BGN": 7790566.91,
"BHD": 1737744.45,
"BIF": 9169348711.83,
"BMD": 4610062.05,
"BND": 6216396.68,
"BOB": 31801277.58,
"BRL": 26023403.82,
"BSD": 4610062.05,
"BTC": 74.54470339,
"BTN": 345299119.91,
"BWP": 52763690.74,
"BYN": 11244314.76,
"BZD": 9240952.37,
"CDF": 9143497429.28,
"CHF": 4208184.5,
"CLF": 135913.85,
"CLP": 3750285480.05,
"CNH": 29495130.91,
"CNY": 29495177.01,
"COP": 17331717342.01,
"CRC": 2939207744.86,
"CUC": 4610062.05,
"CUP": 118709097.86,
"CVE": 436572876.41,
"CZK": 102052399.68,
"DJF": 820509207.6,
"DKK": 29632944.11,
"DOP": 260174176.58,
"DZD": 634030335.09,
"EGP": 72425457.87,
"ERN": 69153789.03,
"ETB": 218717216.23,
"FJD": 9542828.45,
"FKP": 3369190.09,
"GBP": 3369190.09,
"GEL": 14521695.47,
"GGP": 3369190.09,
"GHS": 28121143.41,
"GIP": 3369190.09,
"GMD": 239723226.75,
"GNF": 44360498102.61,
"GTQ": 35672982.87,
"GYD": 964839822.52,
"HKD": 35879882.45,
"HNL": 111443474.11,
"HRK": 29978196.27,
"HTG": 452476986.58,
"HUF": 1435716207.54,
"ILS": 14476908.71,
"IMP": 3369190.09,
"IQD": 6725977357.42,
"IRR": 194775122390.71,
"ISK": 598293853.23,
"JEP": 3369190.09,
"JMD": 712559367.6,
"JOD": 3268534,
"JPY": 526637353.71,
"KES": 513053805.87,
"KGS": 390935115.33,
"KHR": 18835091650.05,
"KMF": 1942681734.96,
"KPW": 4149055847.63,
"KRW": 5430630260.1,
"KWD": 1391132.33,
"KYD": 3840638.09,
"KZT": 1971237418.21,
"LAK": 47201661108.42,
"LBP": 6965551762.15,
"LKR": 930998873.7,
"LRD": 698424377.97,
"LSL": 70723847.09,
"LYD": 21015783.85,
"MAD": 41858708.81,
"MDL": 80357078.85,
"MGA": 18336748035.86,
"MKD": 245401836.65,
"MMK": 8326080171.86,
"MNT": 13147861127.1,
"MOP": 36946291.23,
"MRO": 1645791359.96,
"MRU": 166749005.54,
"MUR": 198463171.38,
"MVR": 71225458.72,
"MWK": 3763215975.72,
"MXN": 95382589.56,
"MZN": 294260260.84,
"NAD": 69704138.24,
"NIO": 162371876.09,
"NOK": 38796622.62,
"NPR": 552477876.37,
"NZD": 6414537.15,
"OMR": 1774767.86,
"PAB": 4610062.05,
"PEN": 18422162.94,
"PGK": 16182622.45,
"PHP": 233052471.57,
"PKR": 792501444.06,
"PLN": 18414837.55,
"PYG": 31817465481.06,
"QAR": 16780842.55,
"RON": 19712487.04,
"RSD": 468340620.4,
"RUB": 327660160.41,
"RWF": 4695797248.61,
"SAR": 17293947.06,
"SBD": 37028825.17,
"SCR": 63024218.26,
"SDG": 2030732334.31,
"SEK": 39500786.54,
"SHP": 3369190.09,
"SLL": 49746487532.16,
"SOS": 2666103446.02,
"SRD": 99148604.57,
"SSP": 600506683.01,
"STD": 96610491131.87,
"STN": 98424824.83,
"SVC": 40330104.44,
"SYP": 5794559138.65,
"SZL": 70735399.9,
"TJS": 51758475.93,
"TMT": 16158267.5,
"TND": 12965799.52,
"TOP": 10312565.9,
"TTD": 31286296.76,
"TWD": 128400374.92,
"TZS": 10616972907.89,
"UAH": 121246397.65,
"UGX": 16393718610.02,
"UYU": 202666561.42,
"UZS": 49202252751,
"VEF": 1145543450116.04,
"VES": 19910627.5,
"VUV": 512750542.16,
"WST": 11839063.48,
"XAF": 2612802535.54,
"XAG": 192248.81,
"XAU": 2577.02,
"XCD": 12458923.2,
"XDR": 3272982.71,
"XOF": 2612802535.54,
"XPD": 2235.88,
"XPF": 475321217.85,
"XPT": 4398,
"YER": 1153668019.52,
"ZAR": 70640049.99,
"ZMW": 79757295.95,
"ZWL": 1484439981.04,
"ETH": 1054.27509088,
"LTC": 110641.4892702,
"DOGE": 16950326.08316667,
"DASH": 65854.73642603,
"BCH": 18901.25441699,
"ZEC": 126163.56820239,
"ETC": 878106.17959294,
"XRP": 24711011.35819838,
"TRX": 45776463.64719361,
"XLM": 98741900.28788687,
"WAVES": 172375.10682464
},
"stockpiling_id": 1585,
"transactions": [
{
"amount": 345345345,
"currency_code": "INR",
"wallet_type": "phone_pe",
"transaction_id": "453535345",
"transaction_type": 0,
"from": null,
"created_datetime": "2021-10-21 13:34:12",
"activated_datetime": "2021-11-01 14:16:51",
"custom_id": null
}
]
}
}
{
"status": "ok",
"postback": {
"withdrawal_id": "2298635",
"status": 1,
"comment": "test",
"payment_system": "paytm",
"amount": 500,
"currency_code": "INR",
"label": "55",
"account_number": "5422222225",
"account_name": "5645646",
"account_email": null,
"payments_details": {
"payments_provider": null
},
"bank_details": {
"bank_code": null,
"branch_code": null
}
}
}
{
"status": "fail"
"message": "MESSAGE"
}