Charge Money | Merchant Direct API Document

Direct API Documentation

How to integrate Direct (Server to Server) API

Our PHP platform payment API can be used to integrate with any platform of your choice.

Request Parameter *

Paramters	Required	Data Type	Description
api_key	Yes	String	API key from your account.
first_name	Yes	String	First Name from (Credit/Debit) Card
last_name	Yes	String	Last Name from (Credit/Debit)Card
address	Yes	String	Full Address of User
country	Yes	String	2 letter Country, eg US
state	Yes	String	State Name, 2 letter for US states, eg CA
city	Yes	String	Valid City name
zip	Yes	String	Valid Zip Code
ip_address	Yes	String	IP address of user device, eg 56.85.205.246
email	Yes	String	Valid Email address of User
country_code	No	String	Valid Country Code of User
phone_no	Yes	String	Valid Phone Number of User
amount	Yes	Decimal	Amount Value
currency	Yes	String	3 Digit format, eg USD
card_no	Yes	String	Credit Card number
ccExpiryMonth	Yes	String	Credit card 2 digit expiry month, E.g. 04
ccExpiryYear	Yes	String	Credit card 4 digit expiry Year, E.g. 2022
cvvNumber	Yes	String	Credit card CVV number
customer_order_id	No	String	Customer order id generated from user side.
response_url	Yes	String	Response URL where we redirect after transaction process completed.
webhook_url	No	String	POST URL where we send webhook notification.

Non-3DS Testing card data -

card_no : 4242 4242 4242 4242
ccExpiryMonth : 02
ccExpiryYear : 2026
cvvNumber : 123

3DS Testing card data -

card_no : 4000 0027 6000 3184
ccExpiryMonth : 02
ccExpiryYear : 2026
cvvNumber : 123

Testing URL -
https://dashboard.charge.money/api/test-transaction
URL -
https://dashboard.charge.money/api/transaction

Method - POST

API Call Example

// You can call our API following curl post example
$url = "https://dashboard.charge.money/api/transaction";
$key = "Your API Key";
// Fill with real customer info
$data = [
    'api_key' => $key,
    'first_name' => 'First Name',
    'last_name' => 'Last Name',
    'address' => 'Address',
    'customer_order_id' => 'ORDER-78544646461235',
    'country' => 'US',
    'state' => 'NY', // if your country US then use only 2 letter state code.
    'city' => 'New York',
    'zip' => '38564',
    'ip_address' => '192.168.168.4',
    'email' => 'test@gmail.com',
    'country_code' => '+91',
    'phone_no' => '999999999',
    'amount' => '10.00',
    'currency' => 'USD',
    'card_no' => '4242424242424242',
    'ccExpiryMonth' => '02',
    'ccExpiryYear' => '2026',
    'cvvNumber' => '123',
    'response_url' => 'https://yourdomain.com/callback.php',
    'webhook_url' => 'https://yourdomain.com/notification.php',
];

$curl = curl_init();
curl_setopt($curl, CURLOPT_URL, $url);
curl_setopt($curl, CURLOPT_POST, 1);
curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($curl, CURLOPT_HTTPHEADER,[
    'Content-Type: application/json'
]);
$response = curl_exec($curl);
curl_close($curl);

$responseData = json_decode($response);

if(isset($responseData['status']) && $respsonseData['status'] == '3d_redirect') {
    header("Location: ".$responseData['redirect_3ds_url']);
} elseif(isset($responseData['status']) && $respsonseData['status'] == 'success') {
    echo "your transaction was approved.";
    print_r($responseData);
} else {
    echo "your transaction was declined";
    print_r($responseData);
}

Response

After a successful CURL request, the response will be sent in JSON format.

Mainly there are 3 types of response with the following Parameter:

1.) “status”:"fail” :  Transaction is declined and it's final status.
2.) “status”:"success” : Transaction is success and it's final status.
3.) “status”:"3d_redirect” : 3D secure redirection is required to complete the transaction
4.) “status”:"declined” : Transaction is declined and it's final status..
5.) “status”:"pending” : Transaction was pending state.
6.) “status”:"blocked” : Transaction was blocked and it's final status.

Success, Declined or 3ds response.

If response contains “status”:"fail” or “status”:"success” it means transaction is complete and it doesn’t need to redirect to 3DS URL.

Validation Errors

If in case of validation errors in request, response will be like:

{
    "status": "fail",
    "message": "Some parameters are missing or invalid request data, please check 'errors' parameter for more details.",
    "errors": {
        "phone_no": [
            "The phone no field is required."
        ]
    },
    "data": {
        "order_id": null,
        "amount": "20",
        "currency": "USD",
        "email": "example@mail.com",
        "customer_order_id": "GH56HJ86285CVP"
    }
}

Successful Response

This is successful transaction response

{
    "status": "success",
    "message": "Your transaction has been processed successfully.",
    "data": {
        "order_id": "16249643005FIFA4ARBU",
        "amount": "20",
        "currency": "USD",
        "email": "example@mail.com",
        "customer_order_id": "GH56HJ86285CVP"
    }
}

Declined Response

This is the declined transaction response

{
    "status": "fail",
    "message": "Your card number is incorrect.",
    "data": {
        "order_id": "16249643005FIFA4ARBU",
        "amount": "20",
        "currency": "USD",
        "email": "example@mail.com",
        "customer_order_id": "GH56HJ86285CVP"
    }
}

3Ds secure Json Response type

If the response returns “status”:"3d_redirect” need to redirect the “redirect_3ds_url”

Response After 3DS

After 3D secure is completed, the user will be redirected to merchant website.

If transaction will be successful, the user will redirect to ”response_url” with response in query string similar to the one below:

https://response_url?status=success&message=Your%20transaction%20was%20success&order_id=16249643005FIFA4ARBU&customer_order_id=GH56HJ86285CVP

If the transaction fails, the user will be redirected to “response_url” with response in query string as follows:

https://response_url?status=success&message=Your%20card%20number%20is%20incorrect.",&order_id=16249643005FIFA4ARBU&customer_order_id=GH56HJ86285CVP

{
    "status": "3d_redirect",
    "message": "3DS link generated successfully, please redirect to 'redirect_3ds_url'.",
    "redirect_3ds_url": https://dashboard.charge.money"/payment/test-transaction/DMZB1624964217",
    "customer_order_id": "GH56HJ86285CVP",
    "api_key": "your_api_key"
}

Webhooks

Webhooks events are transaction callbacks that sends notifications of transaction to the merchant server. If you want to receive webhooks, then send "webhook_url" parameter with initial request(See above request example).

Here are the simple explanation of each parameter:

1.) order_id : Transaction reference number of our system.
2.) customer_order_id: Merchant transaction reference.
3.) transaction_status: "success" / "fail".
4.) reason: Response from the bank about transaction status.
5.) currency: Currency of the transaction.
6.) amount: Amount of the transaction.
7.) email: Email of the transaction.
8.) transaction_date: Date of the transaction.

Webhook Example

Here are the example of webhook notification request:

{
    "order_id": "16249643005FIFA4ARBU",
    "customer_order_id": "GH56HJ86285CVP",
    "transaction_status": "success",
    "reason": "Your transaction has been processed successfully.",
    "currency": "USD",
    "descriptor": "chargeMoney",
    "amount": "20",
    "transaction_date": "2021-06-23 04:38:51"
}