Standard Payment API

Updated: August 18, 2024

URL: https://api.sigepay.online/v3/payment/order

Creates a new payment link for the transaction.

Header

Key Value
Content-Type application/json

Body

                        
                            {
                                "m_key_id": "269282cd-1954-4239-9219-6d27033baaad",
                                "m_method": "GCASH",
                                "m_currency": "PHP",
                                "m_amount": "29.00",
                                "m_order_no": "000001",
                                "m_callback_url": "https://callback.url.com/",
                                "signature": "90ee4ee764cd84b1d9cabaaeea24a1695f4adee7cb0fce4a1a02a40aee6fe021"
                            }

Parameters

Name Type Description
m_key_id* string API Key ID generated from https://sigepay.online/merchant/keys.
m_method* string Payment method to use for the transaction. Available payment methods are returned from /v3/payment/methods.
m_currency* string Currency used for the transaction in ISO4217 format.
m_amount* string Transaction amount to be paid as numeric string. It should be written with two decimal places.
m_order_no* string Reference ID provided by the merchant. Up to 255 characters. This should be unique for each API key.
m_callback_url string The callback URL to send status updates of the transaction.
signature* string HMAC-SHA256 signature computed from body parameters. Click here to view the request signing guide.
metadata json (Optional) Additional data to be sent to the callback handler.
m_success_url string (Optional) The URL where the user is redirected to after the transaction is completed. No query parameters are added.
m_cancel_url string (Optional) The URL where the user is redirected to after the transaction is cancelled. No query parameters are added.
m_failure_url string (Optional) The URL where the user is redirected to after the transaction failed. No query parameters are added.

Responses

Code Description
200

Successfully generates a payment link url.

                                            
                                                {
                                                    "message": "OK",
                                                    "response": {
                                                        "url": "https://api.sigepay.online/v3/payment/checkout/51ee7c37-659f-493f-95e0-2fc94ffe76e6"
                                                    }
                                                }
403

API Key ID and/or signature are invalid or missing.

                                    
                                        {
                                            "message": "This action is unauthorized."
                                        }
422

One or more parameters are invalid. The first parameter error is in message. Errors for each parameter are placed as an array.

                                        
                                            {
                                                "message": "The amount field must be a number.",
                                                "errors": {
                                                    "m_amount": [
                                                        "The amount field must be a number.",
                                                        ...
                                                    ],
                                                    ...
                                                }
                                            }
500

Internal server error.

                                        
                                            {
                                                "message": "Internal server error exception."
                                            }

URL: https://api.sigepay.online/v3/payment/methods

Gets the list of available payment methods.

Responses

Code Description
200

Successful operation. Returns the list of payment methods available. Each payment method is identified by its code. It has its name and list of currency codes usable.

                                    
                                        {
                                            "message": "OK",
                                            "response": {
                                                "GCASH": {
                                                    "name": "GCash",
                                                    "currencies": [
                                                        "PHP",
                                                        ...
                                                    ]
                                                },
                                                "CODE": {
                                                    ...
                                                },
                                                ...
                                            }
                                        }

URL: https://api.sigepay.online/v3/payment/status

Get the status of the transaction.

Header

Key Value
Content-Type application/json

Body

                        
                            {
                                "m_key_id": "269282cd-1954-4239-9219-6d27033baaad",
                                "m_order_no": "000001",
                                "signature": "90ee4ee764cd84b1d9cabaaeea24a1695f4adee7cb0fce4a1a02a40aee6fe021"
                            }

Parameters

Name Type Description
m_key_id* string API Key ID generated from https://sigepay.online/merchant/keys.
m_order_no* string Reference ID provided by the merchant. Up to 255 characters.
signature* string HMAC-SHA256 signature computed from body parameters. Click here to view the request signing guide.

Payment Status

Status Description
created The payment link has been created but not yet opened.
pending The payment link has been opened and waiting to be executed.
failed The payment order failed to complete.
success The payment order is successful.

Responses

Code Description
200

Successful operation. Returns the order number and the status of the transaction.

                                    
                                        {
                                            "message": "OK",
                                            "response": {
                                                "m_order_no": "000001",
                                                "m_status": "pending"
                                            }
                                        }
403

API Key ID and/or signature are invalid or missing.

                                    
                                        {
                                            "message": "This action is unauthorized."
                                        }
422

One or more parameters are invalid. The first parameter error is in message. Errors for each parameter are placed as an array.

                                    
                                        {
                                            "message": "The order number field is required.",
                                            "errors": {
                                                "m_order_no": [
                                                    "The order number field is required.",
                                                    ...
                                                ],
                                                ...
                                            }
                                        }
500

Internal server error.

                                    
                                        {
                                            "message": "Internal server error exception."
                                        }

If the m_callback_url is specified in the transaction, the server will send callback requests to your system. The system will only send callbacks when the payment status is either success or failed.

URL

                        
                            https://{webhook_url}/?m_order_no=000001&m_status=success&signature=90ee4ef764cd84b1d9cabaaeea24a1695f4adee7cb0fce4a1a02a40aef6fe021

Query Parameters

.
Name Type Description
m_order_no* string Reference ID provided by the merchant. Up to 255 characters.
m_status* string Current transaction status. Either created, pending, failed, or success.
signature* string HMAC-SHA256 signature computed from query parameters. Click here to view the request signing guide.
metadata base64 (Optional) Base64 encoded metadata passed to the order endpoint.

Payment Status

Status Description
failed The payment order failed to complete.
success The payment order is successful.

URL: https://api.sigepay.online/v3/wallet

Gets the user's lists of wallets with balance and currency code.

Header

Key Value
Content-Type application/json

Body

                        
                            {
                                "m_key_id": "269282cd-1954-4239-9219-6d27033baaad",
                                "signature": "90ee4ee764cd84b1d9cabaaeea24a1695f4adee7cb0fce4a1a02a40aee6fe021"
                            }

Parameters

Name Type Description
m_key_id* string API Key ID generated from https://sigepay.online/merchant/keys.
signature* string HMAC-SHA256 signature computed from body parameters. Click here to view the request signing guide.

Responses

Code Description
200

Returns an array of wallets with balance and currency code in ISO4217 format.

                                            
                                                {
                                                    "message": "OK",
                                                    "response": [
                                                        {
                                                            "balance": "4.00000000",
                                                            "currency": "AED"
                                                        },
                                                        {
                                                            "balance": "573348.35760000",
                                                            "currency": "PHP"
                                                        },
                                                        {
                                                            "balance": "0.00000000",
                                                            "currency": "USD"
                                                        }
                                                    ]
                                                }
403

API Key ID and/or signature are invalid or missing.

                                        
                                            {
                                                "message": "This action is unauthorized."
                                            }

URL: https://api.sigepay.online/v3/wallet/balance

Get the wallet balance of the user with the given currency code.

Header

Key Value
Content-Type application/json

Body

                        
                            {
                                "m_key_id": "269282cd-1954-4239-9219-6d27033baaad",
                                "m_currency": "PHP",
                                "signature": "90ee4ee764cd84b1d9cabaaeea24a1695f4adee7cb0fce4a1a02a40aee6fe021"
                            }

Parameters

Name Type Description
m_key_id* string API Key ID generated from https://sigepay.online/merchant/keys.
m_currency* string Currency code of the wallet in ISO4217 format.
signature* string HMAC-SHA256 signature computed from body parameters. Click here to view the request signing guide.

Responses

Code Description
200

Returns an array of wallets with balance and currency code in ISO4217 format.

                                            
                                                {
                                                    "message": "OK",
                                                    "response": [
                                                        {
                                                            "balance": "4.00000000",
                                                            "currency": "AED"
                                                        }
                                                    ]
                                                }
403

API Key ID and/or signature are invalid or missing.

                                        
                                            {
                                                "message": "This action is unauthorized."
                                            }
422

One or more parameters are invalid. The first parameter error is in message. Errors for each parameter are placed as an array.

                                        
                                            {
                                                "message": "The currency field is required.",
                                                "errors": {
                                                    "m_currency": [
                                                        "The currency field is required.",
                                                        ...
                                                    ],
                                                    ...
                                                }
                                            }

URL: https://api.sigepay.online/v3/payout/banks

Gets the list of available banks for payout.

Responses

Code Description
200

Successful operation. Returns the list of banks available. Each bank is identified by its code used her as key.

                                    
                                        {
                                            "message": "OK",
                                            "response": {
                                                "ALLIED": "Allied Bank",
                                                "GCASH": "G Exchange Inc.",
                                                ...
                                            }
                                        }

URL: https://api.sigepay.online/v3/payout/order

Create a new payout order. The payout fields should contain all the parameters of the receipients. The system will execute the processing of the payouts in a queued job. Any change in status of the payouts will be sent to the client through a POST callback.

Header

Key Value
Content-Type application/json

Body

                    
                        {
                            "m_key_id": "269282cd-1954-4239-9219-6d27033baaad",
                            "m_batch_no": "XXXXXXXXX",
                            "m_callback_url": "https://callback.url.com/",
                            "payouts": [
                                {
                                    "bank_code": "GCASH",
                                    "account_no": "09XXXXXXXXX",
                                    "amount": "10000",
                                    "first_name": "XXXXXXXXX",
                                    "middle_name": "XXXXXXXXX",
                                    "last_name": "XXXXXXXXX"
                                },
                                {
                                    "bank_code": "GCASH",
                                    "account_no": "09XXXXXXXXX",
                                    "amount": "5000",
                                    "first_name": "XXXXXXXXX",
                                    "middle_name": "XXXXXXXXX",
                                    "last_name": "XXXXXXXXX"
                                },
                                {
                                    "bank_code": "GCASH",
                                    "account_no": "09XXXXXXXXX",
                                    "amount": "1000",
                                    "first_name": "XXXXXXXXX",
                                    "last_name": "XXXXXXXXX"
                                }
                            ],
                            "signature": "90ee4ee764cd84b1d9cabaaeea24a1695f4adee7cb0fce4a1a02a40aee6fe021"
                        }

Parameters

Name Type Description
m_key_id* string API Key ID generated from https://sigepay.online/merchant/keys.
m_batch_no* string A unique batch number identifier. Maximum length is 32 characters.
m_callback_url* string The callback URL to send status updates of the payouts.
payouts* string The array of payouts to process in the order. See the list below for the parameters.
signature* string HMAC-SHA256 signature computed from body parameters. Note that the payouts parameter is not included in the computation of the signature. Click here to view the request signing guide.

Payout Parameters

Name Type Description
bank_code* string The code identifier of the destination bank.
account_no* string The receipient's account number. Maximum length is 16 characters.
amount* string The amount of money to send to. Maximum decimal digits is two.
first_name* string The receipient's first name. Maximum length is 32 characters.
middle_name string The receipient's middle name. Maximum length is 32 characters.
last_name* string The receipient's last name. Maximum length is 32 characters.

Responses

Code Description
200

Successful operation. The processing of the payouts has been dispatched in the system.

                                        
                                            {
                                                "message": "OK"
                                            }
403

API Key ID and/or signature are invalid or missing.

                                    
                                        {
                                            "message": "This action is unauthorized."
                                        }
422

One or more parameters are invalid. The first parameter error is in message. Errors for each parameter are placed as an array.

                                    
                                        {
                                            "message": "The batch number field is required.",
                                            "errors": {
                                                "m_batch_no": [
                                                    "The batch number field is required."
                                                ]
                                            }
                                        }

URL: https://api.sigepay.online/v3/payout/status

Get the status of the payouts.

Header

Key Value
Content-Type application/json

Body

                        
                            {
                                "m_key_id": "269282cd-1954-4239-9219-6d27033baaad",
                                "m_batch_no": "XXXXXXXXX",
                                "signature": "90ee4ee764cd84b1d9cabaaeea24a1695f4adee7cb0fce4a1a02a40aee6fe021"
                            }

Parameters

Name Type Description
m_key_id* string API Key ID generated from https://sigepay.online/merchant/keys.
m_batch_no* string A unique batch number identifier. Maximum length is nine characters.
signature* string HMAC-SHA256 signature computed from body parameters. Click here to view the request signing guide.

Successful and Failure Responses

Refer to payout callback to view the successful and failure responses returned by this endpoint.

Processing Response

The payout order is processing right after placement. After the payout order is executed, the status will change to either success or failure. 

                        
                            {
                                "m_batch_no": "XXXXXXXXX",
                                "m_status": "processing",
                                "m_status_code": 200,
                                "m_message": "OK",
                                "m_total_amount": "30000.00",
                                "m_total_fees": "390.00",
                                "m_count": 3,
                                "payouts": [
                                    {
                                        "bank_code": "GCASH",
                                        "account_no": "09XXXXXXXXX",
                                        "amount": "10000.00",
                                        "fees": "130.00",
                                        "first_name": "XXXXXXXXX",
                                        "middle_name": "XXXXXXXXX",
                                        "last_name": "XXXXXXXXX",
                                        "status": "processing"
                                    },
                                    {
                                        "bank_code": "GCASH",
                                        "account_no": "09XXXXXXXXX",
                                        "amount": "10000.00",
                                        "fees": "130.00",
                                        "first_name": "XXXXXXXXX",
                                        "middle_name": "XXXXXXXXX",
                                        "last_name": "XXXXXXXXX",
                                        "status": "processing"
                                    },
                                    {
                                        "bank_code": "GCASH",
                                        "account_no": "09XXXXXXXXX",
                                        "amount": "10000.00",
                                        "fees": "130.00",
                                        "first_name": "XXXXXXXXX",
                                        "middle_name": "XXXXXXXXX",
                                        "last_name": "XXXXXXXXX",
                                        "status": "processing"
                                    }
                                ],
                                "signature": "45eda12b0a8bdfc24148d09aab2962870dee93e1adbc449c5b966625777a3684"
                              }

The server will send callback POST requests to your system for every update on the payout of the order. You must ensure that your system could receive multiple callbacks from the server. Due to size of the data, the callbacks will be sent as POST and secured using a signature.

Successful Response

After the payouts in the order are successfully processed, the server will send a callback to your system with the following data. The callback provides the status code and message of the process. It also computes the total amount and the total fees incurred for all the transactions. The status of each payout and the fees are also shown. The order of the payout is strictly the same as it was in the request.

The order is a success if all the payouts are sent to the bank for disbursement whether individual payout status is success or failed. If a payout status is failed, a failed_reason field is provided. 

                        
                            {
                                "m_batch_no": "XXXXXXXXX",
                                "m_status": "success",
                                "m_status_code": 200,
                                "m_message": "OK",
                                "m_total_amount": "16000.00",
                                "m_total_fees": "208.00",
                                "m_count": 3,
                                "payouts": [
                                  {
                                    "bank_code": "GCASH",
                                    "account_no": "09XXXXXXXXX",
                                    "amount": "10000.00",
                                    "fees": "130.00",
                                    "first_name": "XXXXXXXXX",
                                    "middle_name": "XXXXXXXXX",
                                    "last_name": "XXXXXXXXX",
                                    "status": "success"
                                  },
                                  {
                                    "bank_code": "GCASH",
                                    "account_no": "09XXXXXXXXX",
                                    "amount": "5000.00",
                                    "fees": "65.00",
                                    "first_name": "XXXXXXXXX",
                                    "middle_name": "XXXXXXXXX",
                                    "last_name": "XXXXXXXXX",
                                    "status": "success"
                                  },
                                  {
                                    "bank_code": "GCASH",
                                    "account_no": "09XXXXXXXXX",
                                    "amount": "1000.00",
                                    "fees": "13.00",
                                    "first_name": "XXXXXXXXX",
                                    "last_name": "XXXXXXXXX",
                                    "status": "failed",
                                    "failed_reason": "account does not exist"
                                  }
                                ],
                                "signature": "45eda12b0a8bdfc24148d09aab2962870dee93e1adbc449c5b966625777a3684"
                              }

Failed Response

If any of the payouts have an invalid input or an error has occured during the process, the order will stop the execution and return an error. A sample error callback body is shown below. Note that the value of the m_status_code will not be 200 in this case. For this case, your system shall correct the issue and create a new order. 

                        
                            {
                                "m_batch_no": "XXXXXXXXX",
                                "m_status": "failed",
                                "m_status_code": 400,
                                "m_message": "Amount of payout 2 is above the maximum limit of 50,000.00",
                                "signature": "ce48cab9e1d91190836139ec81cc72d0f08ec74b3ffc34d3ce19f751e2fea804"
                            }

Body Parameters

.
Name Type Description
m_batch_no* string The unique batch number identifier of the order.
m_status* string Current payout order status. Either processing, failed, or success.
m_status_code* string The status code of the process. This uses similar HTTP status codes.
m_message* string The description of the status code or the exception's message.
m_total_amount* string The total amount sent to all the payouts in the order.
m_total_fees* string The total fees charged to the merchant to process the payouts.
m_count* string The number of payouts processed.
signature* string HMAC-SHA256 signature computed from query parameters. Click here to view the request signing guide.

Payout Status

Status Description
processing The payout is processing.
failed The payout failed. A failed_reason provides the error description.
success The payout is successful.

To secure your requests, we require all the payment requests to be signed. A combination of a key id and HMAC-SHA256 signature makes sure the request we received was not tempered.

The signature is computed using:

  • Key: Secret key granted by SigePay (60 characters).
  • Payload: A string of all key-value pairs joined by '='  that start with 'm_'  (where key is the name the request parameter and value is its value), sorted alphabetically, and concatenated without separators.

Sample payload 

                        
                            {
                                "m_key_id": "269282cd-1954-4239-9219-6d27033baaad",
                                "m_method": "GCASH",
                                "m_currency": "PHP",
                                "m_amount": "29.00",
                                "m_order_no": "000001",
                                "m_callback_url": "https://callback.url.com/"
                            }

The payload for the request above is as follows. 

                            
                                const payload = "m_amount=29.00m_callback_url=https://callback.url.com/m_currency=PHPm_key_id=269282cd-1954-4239-9219-6d27033baaadm_method=GCASHm_order_no=000001";

Please note that the private key should be kept secret, hence the creation of the request payload needs to happen on your server. It cannot happen on the customer's browser or mobile application.

Request signing code

The following code snippets can be used to compute the request signature. 

                                
                                    import org.apache.commons.codec.binary.Hex;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.nio.charset.StandardCharsets;
import java.util.Arrays;
import java.util.Map;
import java.util.stream.Collectors;

class RequestUtils {
    /**
     * Calculates the HMAC/SHA256 signature of a request array.
     * All elements without a 'm_' prefix are ignored.
     * The array is sorted alphabetically by key, concatenated without using
     * any separators and the resulting string is then
     * passed to the hashing function.
     *
     * @param Map<String, String> request array of key -> value pairs
     * @param String secretKey secret key
     * @throws Exception
     * @return String the calculated signature
     */
    public static String sign(Map<String, String> request, String secretKey) throws Exception {
        // Filter keys starting with m_
        String[] keys = request.keySet()
                .stream()
                .filter(k -> k.startsWith("m_"))
                .collect(Collectors.toList())
                .toArray(new String[0]);

        // Sort the keys
        Arrays.sort(keys);

        // Build the payload string
        String payload = "";
        for (String key : keys) {
            payload += String.format("%s=%s", key, request.get(key));
        }

        // Calculate payload and secret bytes
        byte[] secretByes = secretKey.getBytes(StandardCharsets.UTF_8);
        SecretKeySpec secretKeySpec = new SecretKeySpec(secretByes, "HmacSHA256");
        Mac sha256Hmac = Mac.getInstance("HmacSHA256");
        sha256Hmac.init(secretKeySpec);

        // Compute the signature
        byte[] dataUtf8Bytes = payload.getBytes(StandardCharsets.UTF_8);
        byte[] signatureBytes = sha256Hmac.doFinal(dataUtf8Bytes);
        String signature = Hex.encodeHexString(signatureBytes);

        return signature;
    }
}
                                
                            
                                
                                    using System;
using System.ComponentModel;
using System.Security.Cryptography;
using System.Text;

class RequestUtils
{
    /**
     * Calculates the HMAC/SHA256 signature of a request array.
     * All elements without a 'm_' prefix are ignored.
     * The array is sorted alphabetically by key, concatenated without using
     * any separators and the resulting string is then
     * passed to the hashing function.
     *
     * @param Dictionary<string, string> request array of key -> value pairs
     * @param string secretKey secret key
     * @return string the calculated signature
     */
    public static string Sign(Dictionary<string, string> request, string secretKey)
    {
        // Filter keys that start with 'm_'
        var attributes = request.Where(kvp => kvp.Key.StartsWith("m_"))
            .Select(kvp => kvp.Key)
            .ToList();

        // Sort the keys
        attributes.Sort();

        // Build the payload
        string payload = string.Join("",
            attributes.Select(k => k + "=" + request[k]));

        // Initialize 
        byte[] secretBytes = Encoding.UTF8.GetBytes(secretKey);
        using HMACSHA256 hmac = new(secretBytes);

        // Compute the hash
        byte[] dataUtf8Bytes = Encoding.UTF8.GetBytes(payload);
        byte[] signatureBytes = hmac.ComputeHash(dataUtf8Bytes);
        string signature = BitConverter.ToString(signatureBytes)
                                       .Replace("-", "").ToLower();

        return signature;
    }
}
                                 
                            
                                
                                    <?php
class RequestUtils
{
    /**
     * Calculates the HMAC/SHA256 signature of a request array.
     * All elements without a 'm_' prefix are ignored.
     * The array is sorted alphabetically by key, concatenated without using
     * any separators and the resulting string is then
     * passed to the hashing function.
     *
     * @param array $request array of key -> value pairs
     * @param string $secret_key secret key
     * @return string the calculated signature
     */
    public static function sign(array $request, string $secret_key): string
    {
        // Select elements with x_ prefix
        $mElements = array_filter($request, function ($k) {
            return substr($k, 0, 2) === 'm_';
        }, ARRAY_FILTER_USE_KEY);

        // Sort by keys
        ksort($mElements);

        // Concatenate parameters
        $payload = '';
        foreach ($mElements as $k => $v) {
            $payload .= $k . '=' . $v;
        }

        return hash_hmac('sha256', $payload, $secret_key);
    }
};

                                 
                            
                                
                                    /**
 * Calculates the HMAC/SHA256 signature of a request object.
 * All elements without a 'm_' prefix are ignored.
 * The array is sorted alphabetically by key, concatenated without using
 * any separators and the resulting string is then
 * passed to the hashing function.
 * 
 * @param {*} request 
 * @param {*} secretKey 
 * @returns calculated signature of the request
 */
async function sign(request, secretKey) {
    // Extract the entries here
    const keys = [];
    for (const [key, _] of Object.entries(request)) {
        // Extract the keys that start with x_
        if (key.startsWith("m_")) {
            keys.push(key);
        }
    }

    // Sort
    keys.sort(function (a, b) {
        return a.toLowerCase().localeCompare(b.toLowerCase());
    });

    // Build the payload string
    let payload = "";
    for (const key of keys) {
        const value = request[key];
        payload += `${key}=${value}`;
    }

    // Create the encoder
    const enc = new TextEncoder("utf-8");

    const key = await crypto.subtle.importKey(
        "raw",
        enc.encode(secretKey),
        {
            name: "HMAC",
            hash: { name: "SHA-256" }
        },
        false, 
        ["sign"]
    );

    const signatureBytes = await crypto.subtle.sign(
        "HMAC",
        key, 
        enc.encode(payload)
    );

    // Convert to hex
    const bytes = new Uint8Array(signatureBytes);
    const signature = Array.prototype.map.call(bytes, x => x.toString(16).padStart(2, '0'));

    return signature.join("");
}

// Export sign function 
var RequestUtils = RequestUtils || {};
RequestUtils.sign = sign;