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": "fail"
"message": "MESSAGE"
}
Getting mediahints
To receive mediahints on how to make a deposit using the payment system, you need to send a request:
https://api.{URL_server_Paykassma}/wallet-type/images/
Request method: GET
Format: JSON
{
"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
Depending on the value of the is_manual parameter, there are two types of requests for payment activation:
1) if is_manual = false
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 | float | *required if | Transaction amount |
custom_transaction_id | string (64) | YES | Unique transaction identifier in the Client's system It is necessary to pass a non-repeating parameter value |
{
"currency_code": "USD",
"wallet_type": "paytm",
"label": "55",
"key1": "123-ABC-456-DEF"
"custom_transaction_id": "123465477897"
}
{
"status": "ok"
}
{
"status": "fail"
"message": "MESSAGE"
}
2) if is_manual = true
https://api.{URL_server_Paykassma}/api/v1/possible-transaction
Request method: POST
Format: JSON
Parameters:
| Name | Type | Required | Description |
| secret | string | yes | Ключ доступа |
Body:
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 | float | YES | Transaction amount |
| screenshot | string (190) | NO | Upload payment screenshot |
custom_id | string (190) | YES | Transaction ID in the Client’s system |
{
"status": "success",
"message": "",
"code": 20000,
"data": [],
"paginate": {
"offset": 0,
"total": 1,
"limit": 1
}
}
{
"status": "fail",
"message": {
"key1": [
"Transaction field has wrong length"
]
}
}
{
"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 |
|---|---|---|---|---|---|---|
| UPI P2P | required | required | required | required | required | required |
| PhonePe | required | required | required | required | required | required |
| bKash | required | required | required | required | - | required |
| Nagad | required | required | required | required | - | required |
***If you try to activate a suspicious transaction, you will see error 400 'Check of deposit status started. The operation may take longer than expected. Once checked the funds will credit to you account'.
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 | float | 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 (64) | YES | Unique transaction identifier in the Client's system It is necessary to pass a non-repeating parameter value |
{
"language": "en",
"currency": "USD",
"bank": "MBB",
"amount": 1000.00,
"label": "55",
"redirect_url": "https:\/\/google.com"
"custom_transaction_id": "123465477897"
}
{
"status": "ok"
}
{
"status": "fail"
"message": "MESSAGE"
}
Example of request for PS Bkash API
http://api.{ URL_server_Paykassma }/api/v1/payment/create/bkash_api
Request method: POST
Format: JSON
Params:
| Name | Type | Required | Description |
| secret | string | YES | Access key |
Body:
Name | Type | Required | Description |
amount | float (limited by min and max. deposit) | YES | Payment amount |
| account_number | string (11) | YES | The eleven digit account number of the Costumer’s user in Bkash, in the format 01ХХХХХХХХХ Validation:
|
| currency | string (3) | YES | Currency code |
| label | string (190) | YES | Unique ID of the user making the payment |
| custom_transaction_id | string (64) | YES | Unique transaction identifier in the Client's system It is necessary to pass a non-repeating parameter value |
| success_url | string (unlimited) | YES | Link to redirect the user from the Bkash page in case of successful payment |
| failure_url | string (unlimited) | YES | Link to redirect the user from the Bkash page in case of a payment error |
| cancel_url | string (unlimited) | YES | Link to redirect the user from the Bkash page in case of payment cancellation |
{
"amount": 1.00,
"account_number": "01770618575",
"currency": "BDT",
"label": "test",
"custom_transaction_id": "01abc0095689",
"success_url": "https://static5.depositphotos.com/1029663/395/i/600/depositphotos_3955476-stock-photo-green-check-mark.jpg?status=success",
"failure_url": "https://top-fon.com/uploads/posts/2021-07/1626870875_29-p-krasnii-krest-fon-32.png?status=failure",
"cancel_url": "https://yandex.ru/"
}
{
"status": "ok",
"data": {
"orderId": "1cb4627a420a6e69",
"bkashUrl": "https://sandbox.payment.bkash.com/redirect/tokenized/?paymentID=TR00114E1661778153815&hash=dcRq9geuCtjkN6rFpaGxdLAMrmyxIxL*kEN-p41SLL2M!xXy9m2OTUTLwlAGMVWDKyE8xkOHj_N_AHaTxNGT*(V2LXyC5y4zpUsG1661778154005&mode=0011&apiVersion=v1.2.0-beta",
"message": "Successful"
}
}
{
'status': 'fail'
'message': 'MESSAGE'
}
Example of request for PS Nagad API
http://api.{ URL_server_Paykassma }/api/v1/payment/create/nagad_api
Request method: POST
Format: JSON
Params:
| Name | Type | Required | Description |
| secret | string | YES | Access key |
Body:
Name | Type | Required | Description |
amount | float (limited by min and max. deposit) | YES | Payment amount |
| currency | string (3) | YES | Currency code |
| label | string (190) | YES | Unique ID of the user making the payment |
| custom_transaction_id | string (64) | YES | Unique transaction identifier in the Client's system It is necessary to pass a non-repeating parameter value |
| success_url | string (unlimited) | YES | Link to redirect the user from the Nagad page in case of successful payment |
| fail_url | string (unlimited) | YES | Link to redirect the user from the Nagad page in case of a payment error |
| cancel_url | string (unlimited) | YES | Link to redirect the user from the Nagad page in case of payment cancellation |
{
"custom_transaction_id": "custom_transaction_1",
"amount": 100.00,
"currency": "BDT",
"label": "test_user",
"success_url": "https://success_url.com",
"fail_url": "https://fail_url.com",
"cancel_url": "https://cancel_url.com"
}
{
"status": "ok",
"payment_url": "callBackUrl"//link to the Nagad payment page, where the user must enter all the necessary details and make a payment
}
{
'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 (
access to the API is implemented using a secret key):
https://api.{URL_server_Paykassma}/payment-plugin/hash-url?secret=pluginapi_secret
Request method: POST
Format: JSON
Parameters:
Parameter | Type | Required | Description | |
| success_urls | array | YES | The list of redirect addresses when the payment is successful. | |
| order | integer | *YES | The redirect address number in the list. | |
| url | string | *YES | The redirect address when the payment is successful. | |
| fail_urls | array | YES | The list of redirect addresses when the payment is failed. | |
| order | integer | *YES | The redirect address number in the list. | |
| url | string | *YES | The redirect address when the payment is failed. | |
| pending_urls | array | YES | The list of redirect addresses while waiting for payment confirmation. | |
| order | integer | If one of the properties is specified, then the second is required. | The redirect address number in the list. | |
| url | string | The redirect addresses while waiting for payment confirmation. | ||
*One of the success_urls or fail_urls arrays can be empty.
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 For PS Bkash / Nagad: Numbers(11) in the format 01xxxxxxxxx For PS Rocket: Numbers(11-12) in the format 01xxxxxxxxxх |
| 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",
"payments_details": {
"payments_provider": "56",
"payments_method": "MOBILE_MONEY"
},
"bank_details": {
"bank_code": "MAHB0001821",
"branch_code": "000254",
"bank_code_in_payments_system": "9393"
},
"signature":"fae51673a8a9c85f724317214bd0bcc665ebc799"
}
{
"status": "ok"
}
{
"status": "fail"
"message": "MESSAGE"
}
*If, when trying to create a withdrawal request, the amount of account balances in the currency of the request is less than the total amount of new and still incomplete applications, the error message"Insufficient balance" will be displayed (to configure this functionality, contact the TP Paykassma).
{
"status": "fail",
"message": {
"withdrawals_sum_amount": [
"Insufficient balance"
]
}
}
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 |
Accounts' balance
A request to provide the information about the balance of the Client's accounts (except for the Settlement balance) is formed as follows:
https://api.{URL_server_Paykassma}/api/v1/accounts-balance?secret={{pluginapi.secret}}
Request method: GET
Format: JSON
Parameters:
| Name | Type | Required | Description |
| secret | string | yes | Access key |
{
"status": "success",
"message": "",
"code": 20000,
"data": {
"balances": [
{
"wallet_type": "paytm",
"currency_code": "IDR",
"amount": -324324.00
},
{
"wallet_type": "paytm",
"currency_code": "USD",
"amount": -10800.00
},
{
"wallet_type": "bkash",
"currency_code": "VND",
"amount": 155.00
},
{
"wallet_type": "bkash",
"currency_code": "BRL",
"amount": 187239.195
},
{
"wallet_type": "bkash",
"currency_code": "EUR",
"amount": 23.9375
},
{
"wallet_type": "nagad",
"currency_code": "CUC",
"amount": 471.00
},
{
"wallet_type": "upi_ib",
"currency_code": "SAR",
"amount": 499.00
}
]
}
{
"status": "error",
"code": 30228,
"errors": {
"target": "secret",
"code": 36205,
"message": "Wrong secret"
},
"error_message": "Data validation error"
}
Order statuses
A request to provide the information about the statuses of the Client's orders is formed as follows:
https://api.{URL_server_Paykassma}/api/v1/pullpostbacks?secret={{pluginapi.secret}}
Request method: GET
Format: JSON
Parameters:
| Name | Type | Required | Description |
| secret | string | yes | Access key |
| Name | Type | Required | Description |
|---|---|---|---|
| type | string | YES | Possible values:
|
| plugin_custom_order_id | array | YES if type = withdrawal | User transaction ID/Order ID |
withdrawal_id | array | YES if type = plugin_custom_order_id | Withdrawal ID |
Response body:
| Name | Type | Required | Description | |||||
|---|---|---|---|---|---|---|---|---|
status | string | YES | Request status | |||||
| massage | string | To be filled in if the response is successfu | Message on successful response | |||||
| code | int | YES | Response code | |||||
| data | array/object | To be filled in if the response is successful | ||||||
| transactions | array | YES if type = deposit | Deposit information | |||||
| plugin_custom_order_id | string | YES | User transaction ID/Order ID | |||||
message | string | YES if the transaction is not found | A message if the transaction was not found | |||||
| postback | array | YES if a transaction is found | Postback information | |||||
| withdrawals | array | YES if type = withdrawal | Withdrawal information | |||||
| withdrawal_id | string | YES | Withdrawal ID | |||||
| message | string | YES if the withdrawal is not found | A message if the transaction was not found | |||||
| postback | array | YES if the withdrawal is not found | Postback information | |||||