sovamoney - Developer - Api Documentation

Introduction

This section describes the sovamoney payment gateway API.

sovamoney API is easy to implement in your business software. Our API is well formatted URLs, accepts cURL requests, returns JSON responses.

You can use the API in test mode, which does not affect your live data. The API key is use to authenticate the request and determines the request is valid payment or not. For test mode just use the sandbox URL and In case of live mode use the live URL from section Initiate Payment .

Get The Api Key

This section describes how you can get your api key.

Login to your sovamoney merchant account. If you don't have any ? Click Here

Next step is to find the Api Key menu in your dashboard sidebar. Click the menu.

The api keys can be found there which is Public key and Secret key. Use these keys to initiate the API request. Every time you can generate new API key by clicking Generate Api Key button. Remember do not share these keys with anyone.

Initiate Payment

This section describes the process of initaiing the payment.

To initiate the payment follow the example code and be careful with the perameters. You will need to make request with these following API end points.

Live End Point: https://sovamoney.com/payment/initiate

Test End Point: https://sovamoney.com/sandbox/payment/initiate

Test Mode Mail: test_mode@mail.com

Test Mode Verification Code: 222666

Request Method: POST

Request to the end point with the following parameters below.

Param Name	Param Type	Description
public_key	string (50)	Required Your Public API key
identifier	string (20)	Required Identifier is basically for identify payment at your end
currency	string (4)	Required Currency Code, Must be in Upper Case. e.g. USD,EUR
amount	decimal	Required Payment amount.
details	string (100)	Required Details of your payment or transaction.
ipn_url	string	Required The url of instant payment notification.
success_url	string	Required Payment success redirect url.
cancel_url	string	Required Payment cancel redirect url.
site_logo	string/url	Required Your business site logo.
checkout_theme	string	Optional Checkout form theme dark/light. Default theme is light
customer_name	string (30)	Required Customer name.
customer_email	string (30)	Required Customer valid email.

Example PHP code

<?php
    $parameters = [
        'identifier' => 'DFU80XZIKS',
        'currency' => 'USD',
        'amount' => 100.00,
        'details' => 'Purchase T-shirt',
        'ipn_url' => 'http://example.com/ipn_url.php',
        'cancel_url' => 'http://example.com/cancel_url.php',
        'success_url' => 'http://example.com/success_url.php',
        'public_key' => 'your_public_key',
        'site_logo' => 'https://sovamoney.com/assets/images/logoIcon/logo.png',
        'checkout_theme' => 'dark',
        'customer_name' => 'John Doe',
        'customer_email' => 'john@mail.com',

    ];

    //live end point
    $url = "https://sovamoney.com/payment/initiate";

    //test end point
    $url = "https://sovamoney.com/sandbox/payment/initiate";

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_POSTFIELDS,  $parameters);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    $result = curl_exec($ch);
    curl_close($ch);

    //$result contains the response back.
?>

Example Responses

//Error Response.
{
    "error": "true",
    "message": "Invalid api key"
}

//Success Response.
{
    "success": "ok",
    "message": "Payment Initiated. Redirect to url.",
    "url":"http://example.com/initiate/payment/checkout?payment_id=eJSAASDxdrt4DASDASVNASJA7893232432cvmdsamnvASF"
}

Validate The Payment and IPN

This section describes the process to get your instant payment notification.

To initiate the payment follow the example code and be careful with the perameters. You will need to make request with these following API end points.

End Point: Your business application ipn url.

Request Method: POST

You will get following parameters below.

Param Name	Description
status	Payment success status.
identifier	Identifier is basically for identify payment at your end.
signature	A hash signature to verify your payment at your end.
data	Data contains some basic information with charges, amount, currency, payment transaction id etc.

Example PHP code

<?php
    //Receive the response parameter
    $status = $_POST['status'];
    $signature = $_POST['signature'];
    $identifier = $_POST['identifier'];
    $data = $_POST['data'];

    // Generate your signature
    $customKey = $data['amount'].$identifier;
    $secret = 'YOUR_SECRET_KEY';
    $mySignature = strtoupper(hash_hmac('sha256', $customKey , $secret));

    $myIdentifier = 'YOUR_GIVEN_IDENTIFIER';

    if($status == "success" && $signature == $mySignature &&  $identifier ==  $myIdentifier){
        //your operation logic
    }
?>

Get Merchant Withdrawal Methods

This section describes the process of retrieving the available withdrawal methods.

To retrieve available withdrawal methods, follow the example code carefully and ensure all parameters are correctly provided. You will need to make a request to the following API endpoint.

Live End Point: https://sovamoney.com/api/merchant/withdraw/getmethod

Request Method: POST

Request to the end point with the following parameters below.

Param Name	Param Type	Description
public_key	string (50)	Required Your Public API key

Example PHP code

<?php
    $parameters = [
        'public_key' => 'your_public_key'
    ];

    //live end point
    $url = "https://sovamoney.com/api/merchant/withdraw/getmethod";

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_POSTFIELDS,  $parameters);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    $result = curl_exec($ch);
    curl_close($ch);

    //$result contains the response back.
?>

Example Responses

//Error Response.
{
    "remark": "invalid_api_key",
    "status": "error",
    "message": {
        "error": [
            "Invalid api key."
        ]
    }
}

//Success Response.
{
    "remark": "get_withdraw_method",
    "status": "success",
    "message": {
        "success": [
            "Withdraw method list"
        ]
    },
    "data": {
        "userMethods": [
            {
                "user_method_id": 117,
                "name": "Thomas Whitaker",
                "method_id": 1,
                "min_limit": 10,
                "max_limit": 1000,
                "withdraw_method": {
                    "id": 1,
                    "name": "Bank Transfer",
                    "min_limit": "10.00000000",
                    "max_limit": "1000.00000000",
                    "fixed_charge": "1.00000000",
                    "rate": "1.00000000",
                    "percent_charge": "2.00",
                    "currency": "USD"
                }
            }
        ],
        "otp_methods": ['email','sms','2FA'],
        "otp_required": true
    }
}

Request Merchant Withdrawal

This section describes the process of requesting a withdrawal from the system.

To request a withdrawal, follow the example code carefully and ensure all required parameters are correctly provided. You will need to make a request to the following API endpoint.

Live End Point: https://sovamoney.com/api/merchant/withdraw/request

Request Method: POST

Request to the end point with the following parameters below.

Param Name	Param Type	Description
public_key	string (50)	Required Your Public API key
method_id	int (10)	Required Method ID
user_method_id	int (10)	Required User Method ID
amount	decimal	Required Withdrawal Amount
otp_method	enum('email', 'sms', '2FA')	Nullable/Required OTP verify method

N.B: If the selected withdrawal method has OTP verification enabled (otp_required: true), then the otp_method field becomes required when submitting a withdrawal request. The OTP will be sent using the selected method (e.g., email, sms, or 2FA). The withdrawal request will only be confirmed after successful OTP verification. If OTP verification is not required for the selected method, the withdrawal request will be confirmed immediately without any OTP step.

Example PHP code without OTP

<?php
    $parameters = [
        'public_key' => 'your_public_key',
        'method_id' => 1,
        'user_method_id' => 15,
        'amount' => 500,
    ];

    //live end point
    $url = "https://sovamoney.com/api/merchant/withdraw/request";

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_POSTFIELDS,  $parameters);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    $result = curl_exec($ch);
    curl_close($ch);

    //$result contains the response back.
?>

Example Responses

//Error Response.
{
    "remark": "invalid_api_key",
    "status": "error",
    "message": {
        "error": [
            "Invalid api key."
        ]
    }
}

//Success Response.
{
    "remark": "withdraw_money",
    "status": "success",
    "message": {
        "success": [
            "Withdraw request sent successfully"
        ]
    },
    "data": {
        "withdraw": {
            "method_id": 1,
            "user_id": 403,
            "user_type": "MERCHANT",
            "amount": "500",
            "rate": "1.00000000",
            "currency": "USD",
            "charge": 11,
            "final_amount": 489,
            "after_charge": 489,
            "trx": "PQE2L696BVLI",
            "updated_at": "2025-07-12T15:05:51.000000Z",
            "created_at": "2025-07-12T15:05:51.000000Z",
            "id": 91,
            "status": 2,
            "method": {
                "id": 1,
                "form_id": 13,
                "name": "Bank Transfer",
                "image": "66bb036c113031723532140.png",
                "min_limit": "10.00000000",
                "max_limit": "1000.00000000",
                "fixed_charge": "1.00000000",
                "rate": "1.00000000",
                "percent_charge": "2.00",
                "currency": "USD",
                "description": "Please Provide The information Below:
",
                "status": 1,
                "user_guards": [
                    "2",
                    "3"
                ],
                "created_at": "2022-03-30T15:09:11.000000Z",
                "updated_at": "2024-08-13T06:55:40.000000Z"
            }
        }
    }
}

Example PHP code with OTP

<?php
    $parameters = [
        'public_key' => 'your_public_key',
        'method_id' => 1,
        'user_method_id' => 15,
        'amount' => 500,
        'otp_method' => 'email',
    ];

    //live end point
    $url = "https://sovamoney.com/api/merchant/withdraw/request";

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_POSTFIELDS,  $parameters);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    $result = curl_exec($ch);
    curl_close($ch);

    //$result contains the response back.
?>

Example Responses

//Error Response.
{
    "remark": "invalid_api_key",
    "status": "error",
    "message": {
        "error": [
            "Invalid api key."
        ]
    }
}

//Success Response.
{
    "remark": "verify_otp",
    "status": "success",
    "message": {
        "success": [
            "Verify otp sent successfully."
        ]
    },
    "data": {
        "action_id": 720,
        "expired_at": "2025-07-12T15:22:18.388450Z",
        "transaction_no": "V3OU3JUUQKTF"
    }
}

Verify Merchant Withdrawal OTP

This section describes the process of verifying the OTP for a merchant withdrawal request.

To verify a withdrawal OTP, follow the example code carefully and ensure all required parameters are correctly provided. You will need to make a request to the following API endpoint to complete the OTP verification process.

Live End Point: https://sovamoney.com/api/merchant/withdraw/otp/verify

Request Method: POST

Request to the end point with the following parameters below.

Param Name	Param Type	Description
public_key	string (50)	Required Your Public API key
action_id	int (10)	Required Action ID
otp_method	enum('email', 'sms', '2FA')	Required OTP verify method
otp	int (6)	Required OTP code
transaction_no	string (255)	Required Withdrawal transaction number

Example PHP code

<?php
    $parameters = [
        'public_key' => 'your_public_key',
        'method_id' => 1,
        'user_method_id' => 15,
        'amount' => 500,
    ];

    //live end point
    $url = "https://sovamoney.com/api/merchant/withdraw/request";

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_POSTFIELDS,  $parameters);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    $result = curl_exec($ch);
    curl_close($ch);

    //$result contains the response back.
?>

Example Responses

//Error Response.
{
    {
    "remark": "invalid_otp",
    "status": "error",
    "message": {
        "error": [
            "error",
            "Your OTP has expired"
        ]
    }
}
}

//Success Response.
{
    "remark": "withdraw_money",
    "status": "success",
    "message": {
        "success": [
            "Withdraw request sent successfully"
        ]
    },
    "data": {
        "withdraw": {
            "id": 93,
            "method_id": 1,
            "user_id": 403,
            "user_type": "MERCHANT",
            "amount": "500.00000000",
            "currency": "USD",
            "rate": "1.00000000",
            "charge": "11.00000000",
            "trx": "V3OU3JUUQKTF",
            "final_amount": "489.00000000",
            "after_charge": "489.00000000",
            "status": 2,
            "admin_feedback": null,
            "created_at": "2025-07-12T15:19:26.000000Z",
            "updated_at": "2025-07-12T15:30:16.000000Z",
            "method": {
                "id": 1,
                "form_id": 13,
                "name": "Bank Transfer",
                "image": "66bb036c113031723532140.png",
                "min_limit": "10.00000000",
                "max_limit": "1000.00000000",
                "fixed_charge": "1.00000000",
                "rate": "1.00000000",
                "percent_charge": "2.00",
                "currency": "USD",
                "description": "Please Provide The information Below:
",
                "status": 1,
                "user_guards": [
                    "2",
                    "3"
                ],
                "created_at": "2022-03-30T15:09:11.000000Z",
                "updated_at": "2024-08-13T06:55:40.000000Z"
            }
        }
    }
}

Get Agent Withdrawal Methods

This section describes the process of retrieving the available withdrawal methods.

To retrieve available withdrawal methods, follow the example code carefully and ensure all parameters are correctly provided. You will need to make a request to the following API endpoint.

Live End Point: https://sovamoney.com/api/agent/withdraw/getmethod

Request Method: POST

Request to the end point with the following parameters below.

Param Name	Param Type	Description
public_key	string (50)	Required Your Public API key

Example PHP code

<?php
    $parameters = [
        'public_key' => 'your_public_key'
    ];

    //live end point
    $url = "https://sovamoney.com/api/agent/withdraw/getmethod";

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_POSTFIELDS,  $parameters);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    $result = curl_exec($ch);
    curl_close($ch);

    //$result contains the response back.
?>

Example Responses

//Error Response.
{
    "remark": "invalid_api_key",
    "status": "error",
    "message": {
        "error": [
            "Invalid api key."
        ]
    }
}

//Success Response.
{
    "remark": "get_withdraw_method",
    "status": "success",
    "message": {
        "success": [
            "Withdraw method list"
        ]
    },
    "data": {
        "userMethods": [
            {
                "user_method_id": 117,
                "name": "Thomas Whitaker",
                "method_id": 1,
                "min_limit": 10,
                "max_limit": 1000,
                "withdraw_method": {
                    "id": 1,
                    "name": "Bank Transfer",
                    "min_limit": "10.00000000",
                    "max_limit": "1000.00000000",
                    "fixed_charge": "1.00000000",
                    "rate": "1.00000000",
                    "percent_charge": "2.00",
                    "currency": "USD"
                }
            }
        ],
        "otp_methods": ['email','sms','2FA'],
        "otp_required": true
    }
}

Request Agent Withdrawal

This section describes the process of requesting a withdrawal from the system.

To request a withdrawal, follow the example code carefully and ensure all required parameters are correctly provided. You will need to make a request to the following API endpoint.

Live End Point: https://sovamoney.com/api/agent/withdraw/request

Request Method: POST

Request to the end point with the following parameters below.

Param Name	Param Type	Description
public_key	string (50)	Required Your Public API key
method_id	int (10)	Required Method ID
user_method_id	int (10)	Required User Method ID
amount	decimal	Required Withdrawal Amount
otp_method	enum('email', 'sms', '2FA')	Nullable/Required OTP verify method

N.B: If the selected withdrawal method has OTP verification enabled (otp_required: true), then the otp_method field becomes required when submitting a withdrawal request. The OTP will be sent using the selected method (e.g., email, sms, or 2FA). The withdrawal request will only be confirmed after successful OTP verification. If OTP verification is not required for the selected method, the withdrawal request will be confirmed immediately without any OTP step.

Example PHP code without OTP

<?php
    $parameters = [
        'public_key' => 'your_public_key',
        'method_id' => 1,
        'user_method_id' => 15,
        'amount' => 500,
    ];

    //live end point
    $url = "https://sovamoney.com/api/agent/withdraw/request";

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_POSTFIELDS,  $parameters);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    $result = curl_exec($ch);
    curl_close($ch);

    //$result contains the response back.
?>

Example Responses

//Error Response.
{
    "remark": "invalid_api_key",
    "status": "error",
    "message": {
        "error": [
            "Invalid api key."
        ]
    }
}

//Success Response.
{
    "remark": "withdraw_money",
    "status": "success",
    "message": {
        "success": [
            "Withdraw request sent successfully"
        ]
    },
    "data": {
        "withdraw": {
            "method_id": 1,
            "user_id": 403,
            "user_type": "AGENT",
            "amount": "500",
            "rate": "1.00000000",
            "currency": "USD",
            "charge": 11,
            "final_amount": 489,
            "after_charge": 489,
            "trx": "PQE2L696BVLI",
            "updated_at": "2025-07-12T15:05:51.000000Z",
            "created_at": "2025-07-12T15:05:51.000000Z",
            "id": 91,
            "status": 2,
            "method": {
                "id": 1,
                "form_id": 13,
                "name": "Bank Transfer",
                "image": "66bb036c113031723532140.png",
                "min_limit": "10.00000000",
                "max_limit": "1000.00000000",
                "fixed_charge": "1.00000000",
                "rate": "1.00000000",
                "percent_charge": "2.00",
                "currency": "USD",
                "description": "Please Provide The information Below:
",
                "status": 1,
                "user_guards": [
                    "2",
                    "3"
                ],
                "created_at": "2022-03-30T15:09:11.000000Z",
                "updated_at": "2024-08-13T06:55:40.000000Z"
            }
        }
    }
}

Example PHP code with OTP

<?php
    $parameters = [
        'public_key' => 'your_public_key',
        'method_id' => 1,
        'user_method_id' => 15,
        'amount' => 500,
        'otp_method' => 'email',
    ];

    //live end point
    $url = "https://sovamoney.com/api/agent/withdraw/request";

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_POSTFIELDS,  $parameters);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    $result = curl_exec($ch);
    curl_close($ch);

    //$result contains the response back.
?>

Example Responses

//Error Response.
{
    "remark": "invalid_api_key",
    "status": "error",
    "message": {
        "error": [
            "Invalid api key."
        ]
    }
}

//Success Response.
{
    "remark": "verify_otp",
    "status": "success",
    "message": {
        "success": [
            "Verify otp sent successfully."
        ]
    },
    "data": {
        "action_id": 720,
        "expired_at": "2025-07-12T15:22:18.388450Z",
        "transaction_no": "V3OU3JUUQKTF"
    }
}

Verify Agent Withdrawal OTP

This section describes the process of verifying the OTP for a agent withdrawal request.

To verify a withdrawal OTP, follow the example code carefully and ensure all required parameters are correctly provided. You will need to make a request to the following API endpoint to complete the OTP verification process.

Live End Point: https://sovamoney.com/api/agent/withdraw/otp/verify

Request Method: POST

Request to the end point with the following parameters below.

Param Name	Param Type	Description
public_key	string (50)	Required Your Public API key
action_id	int (10)	Required Action ID
otp_method	enum('email', 'sms', '2FA')	Required OTP verify method
otp	int (6)	Required OTP code
transaction_no	string (255)	Required Withdrawal transaction number

Example PHP code

<?php
    $parameters = [
        'public_key' => 'your_public_key',
        'method_id' => 1,
        'user_method_id' => 15,
        'amount' => 500,
    ];

    //live end point
    $url = "https://sovamoney.com/api/agent/withdraw/request";

    $ch = curl_init();
    curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, false);
    curl_setopt($ch, CURLOPT_URL, $url);
    curl_setopt($ch, CURLOPT_POSTFIELDS,  $parameters);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    $result = curl_exec($ch);
    curl_close($ch);

    //$result contains the response back.
?>

Example Responses

//Error Response.
{
    {
    "remark": "invalid_otp",
    "status": "error",
    "message": {
        "error": [
            "error",
            "Your OTP has expired"
        ]
    }
}
}

//Success Response.
{
    "remark": "withdraw_money",
    "status": "success",
    "message": {
        "success": [
            "Withdraw request sent successfully"
        ]
    },
    "data": {
        "withdraw": {
            "id": 93,
            "method_id": 1,
            "user_id": 403,
            "user_type": "AGENT",
            "amount": "500.00000000",
            "currency": "USD",
            "rate": "1.00000000",
            "charge": "11.00000000",
            "trx": "V3OU3JUUQKTF",
            "final_amount": "489.00000000",
            "after_charge": "489.00000000",
            "status": 2,
            "admin_feedback": null,
            "created_at": "2025-07-12T15:19:26.000000Z",
            "updated_at": "2025-07-12T15:30:16.000000Z",
            "method": {
                "id": 1,
                "form_id": 13,
                "name": "Bank Transfer",
                "image": "66bb036c113031723532140.png",
                "min_limit": "10.00000000",
                "max_limit": "1000.00000000",
                "fixed_charge": "1.00000000",
                "rate": "1.00000000",
                "percent_charge": "2.00",
                "currency": "USD",
                "description": "Please Provide The information Below:
",
                "status": 1,
                "user_guards": [
                    "2",
                    "3"
                ],
                "created_at": "2022-03-30T15:09:11.000000Z",
                "updated_at": "2024-08-13T06:55:40.000000Z"
            }
        }
    }
}