Developer

Payment API

With SigePay Standard and Payment API, you can easily and safely receive online payments from your customer.

A step-by-step guide on how to integrate SigePay Payment API

Updated: August 18, 2024

POST /v3/payment/order

URL: https://api.mail.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": "card",
                        "m_currency": "USD",
                        "m_amount": "29.00",
                        "m_order_no": "000001",
                        "m_lang": "en",
                        "m_callback_url": "https://callback.url.com/",
                        "m_success_url": "https://your.site/success",
                        "m_cancel_url": "https://your.site/cancel",
                        "m_failure_url": "https://your.site/failure",
                        "m_customer_name": "John Doe",
                        "m_customer_email": "john.doe@example.com",
                        "m_customer_phone": "+971501234567",
                        "signature": "90ee4ee764cd84b1d9cabaaeea24a1695f4adee7cb0fce4a1a02a40aee6fe021"
                    }
                
            

Parameters

Name Type Description
m_key_id* string API Key ID generated from https://mail.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 ISO 4217 format.
m_amount* string Transaction amount to be paid as a numeric string. It should be written with two decimal places.
m_order_no* string Reference ID provided by the merchant. Up to 255 characters. Must be unique for each API key.
signature* string HMAC-SHA256 signature computed from body parameters. Click here to view the request signing guide.
m_callback_url string (Optional) The callback URL to send status updates of the transaction.
m_success_url string (Optional) The URL where the user is redirected after the transaction is completed. The query parameter uuid is appended: the transaction id, the same value as transaction_id in /v3/transaction/status. This redirect is not proof of payment, since anyone can open the URL. Confirm the payment with /v3/payment/status or the payment callback before you fulfil the order.
m_cancel_url string (Optional) The URL where the user is redirected after the transaction is cancelled. The query parameter uuid is appended: the transaction id, the same value as transaction_id in /v3/transaction/status. This redirect is not proof of payment, since anyone can open the URL. Confirm the payment with /v3/payment/status or the payment callback before you fulfil the order.
m_failure_url string (Optional) The URL where the user is redirected after the transaction failed. The query parameter uuid is appended: the transaction id, the same value as transaction_id in /v3/transaction/status. This redirect is not proof of payment, since anyone can open the URL. Confirm the payment with /v3/payment/status or the payment callback before you fulfil the order.
m_lang string (Optional) Language code to set as default on the payment page (e.g., en, ae, tr, jp, in).
m_customer_name string (Optional) Customer's full name. Pre-fills the name field on the payment page. The customer can still edit it before submitting.
m_customer_email string (Optional) Customer's email address. Pre-fills the email field on the payment page. The customer can still edit it before submitting.
m_customer_phone string (Optional) Customer's phone number. Pre-fills the phone field on the payment page. The customer can still edit it before submitting.
metadata json (Optional) Additional data to be sent to the callback handler.

Responses

Code Description
200

Successfully generates a payment link URL.

                                    
                                        {
                                            "message": "OK",
                                            "response": {
                                                "url": "https://api.mail.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."
                                        }
                                    
                                
GET /v3/payment/methods

URL: https://api.mail.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": {
                                                    ...
                                                },
                                                ...
                                            }
                                        }
                                     
                                
POST /v3/payment/status

URL: https://api.mail.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://mail.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.
refunded The payment order was successful and has since been refunded to the customer.

Responses

Code Description
200

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

Sample Response (Pending):

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

Sample Response (Success):

                                    
                                        {
                                            "message": "OK",
                                            "response": {
                                                "m_order_no": "000001",
                                                "m_status": "success",
                                                "customer_details": {
                                                    "cardholder_name": "Mohamed Afzal",
                                                    "email": "afzal@example.com",
                                                    "phone": "7994459106",
                                                    "card_type": "VISA",
                                                    "card_category": "Debit",
                                                    "card_last_four": "1112",
                                                    "expiry_date": "06/2030",
                                                    "issuer_country": "PK"
                                                }
                                            }
                                        }
                                     
                                

Sample Response (Failed):

                                    
                                        {
                                            "message": "OK",
                                            "response": {
                                                "m_order_no": "000001",
                                                "m_status": "failed",
                                                "customer_details": {
                                                    "cardholder_name": "Mohamed Afzal",
                                                    "email": "afzal@example.com",
                                                    "card_type": "VISA",
                                                    "card_category": "Credit",
                                                    "card_last_four": "0002",
                                                    "expiry_date": "12/2029",
                                                    "issuer_country": null
                                                },
                                                "failure_code": "310",
                                                "failure_reason": "3DSecure authentication rejected"
                                            }
                                        }
                                     
                                

customer_details Fields

Field Type Description
cardholder_namestring|nullName of the cardholder as returned by the payment gateway.
emailstring|nullEmail address of the customer.
phonestring|nullPhone number of the customer.
card_typestring|nullCard scheme (e.g. VISA, Mastercard).
card_categorystring|nullCard category (e.g. Credit, Debit).
card_last_fourstring|nullLast 4 digits of the card number.
expiry_datestring|nullCard expiry in MM/YYYY format.
issuer_countrystring|nullISO 3166-1 alpha-2 country code of the card issuer.

Failure Fields (present when m_status is failed or cancelled)

Field Type Description
failure_codestring|nullGateway-specific decline code (e.g. 310 for 3DS rejection). Falls back to PAYMENT_FAILED or CANCELLED if not available.
failure_reasonstring|nullHuman-readable reason for the failure (e.g. 3DSecure authentication rejected). Falls back to a generic message if not available.
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."
                                        }
                                     
                                
Payment Callback

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×tamp=1794460800&signature_v2=691135b847a0e3bd8e9964171f64bd332cbf08c33c28dab59cd5f351770a1897
                         
                    

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 Legacy HMAC-SHA256 signature over the m_ parameters only. Kept for existing integrations; it does not cover metadata or the time of sending, so prefer signature_v2.
timestamp* string Time the callback was sent, in Unix seconds. Refuse a callback whose timestamp is more than 5 minutes away from your clock: it is a replay.
signature_v2* string HMAC-SHA256 over every other parameter of the callback (metadata, payouts and timestamp included). Check this one rather than signature. See Verifying callbacks.
metadata base64 (Optional) Base64 encoded metadata passed to the order endpoint.

Payment Status

Status Description
failed The payment order failed to complete. This is final: the order cannot be paid again. To let the customer retry, create a new payment order.
success The payment order is successful.

Retries and expiry

A failed callback ends the payment order: its payment link stops accepting payments. A payment order that has not been paid also stops accepting payments 24 hours after it was created; no callback is sent for that, and a payment the customer started before then can still complete. Either way, the customer sees that the payment has ended and is asked to return to your site, so create a new payment order for each retry. In rare cases the payment provider confirms a payment only after the order was reported failed; the same order is then sent a success callback.

POST /v3/wallet

URL: https://api.mail.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://mail.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."
                                            }
                                         
                                    
POST /v3/wallet/balance

URL: https://api.mail.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://mail.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.",
                                                        ...
                                                    ],
                                                    ...
                                                }
                                            }
                                         
                                    
GET /v3/payout/banks

URL: https://api.mail.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.",
                                                ...
                                            }
                                        }
                                     
                                
POST /v3/payout/order

URL: https://api.mail.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.

Payouts are disabled for an API key until they are enabled for it. Contact support to enable them.

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/",
                            "m_timestamp": "1762934400",
                            "m_nonce": "4f9c2b7e1a6d4c3e8b0f5a9d2c7e1b6a",
                            "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://mail.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.
m_timestamp* string Unix time in seconds when the request was signed. See the request signing guide.
m_nonce* string A value used once per request. See the request signing guide.
payouts* string The array of payouts to process in the order. See the list below for the parameters.
signature* string HMAC-SHA256 signature v2, computed over the method, the path and every body parameter, the payouts list included. Payout orders must carry m_timestamp and m_nonce; a payout order signed the legacy way (the m_ fields only) is refused with 403. 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, the request is not signed with signature v2, or payouts are not enabled for the API key.

                                    
                                        {
                                            "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."
                                                ]
                                            }
                                        }
                                     
                                
POST /v3/payout/status

URL: https://api.mail.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://mail.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"
                              }
                         
                    
Payout Callback

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",
                                "timestamp": "1794460800",
                                "signature_v2": "18bc125ff993187c7ef3f4dd5288c4d04add24e2151e2c9f299a761b07326cec"
                              }
                         
                    

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",
                                "timestamp": "1794460800",
                                "signature_v2": "e1e9fb480e0d25c56422637a2d78c88973871907c9b670ec31b7a78fc0d15052"
                            }
                         
                    

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 Legacy HMAC-SHA256 signature over the m_ parameters only. Kept for existing integrations; it does not cover payouts or the time of sending, so prefer signature_v2.
timestamp* string Time the callback was sent, in Unix seconds. Refuse a callback whose timestamp is more than 5 minutes away from your clock: it is a replay.
signature_v2* string HMAC-SHA256 over every other parameter of the callback (metadata, payouts and timestamp included). Check this one rather than signature. See Verifying callbacks.

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.
Request Signing

To secure your requests, we require all API requests to be signed. A combination of a key ID and an HMAC-SHA256 signature ensures the request we received was sent by you, was not tampered with and is not a replay of an earlier request.

Key:

Secret key granted by SigePay (60 characters).

Signature v2 (recommended)

Add two parameters to every request:

  • m_timestamp: the current time in Unix seconds. Requests more than 5 minutes away from our clock are refused, so keep your server clock in sync (NTP).
  • m_nonce: a new random value for every request, 16 to 128 characters of A-Z a-z 0-9 . _ ~ - (for example 32 hex characters). A nonce can be used only once per key; a request repeating one is refused.

Then sign every parameter you send (query and body, including m_key_id, m_timestamp, m_nonce, metadata and payouts), except signature itself:

  1. Flatten nested objects and arrays into parent[child] names, e.g. metadata[cart_id], payouts[0][amount].
  2. Write each value as text: strings as they are, null as an empty string, booleans as true / false. Send amounts and other numbers as strings ("29.00") so both sides see the same text; a JSON number is signed in its shortest form (29.00 as 29, 0.5 as 0.5).
  3. Percent-encode every name and value as in RFC 3986 (UTF-8; only A-Z a-z 0-9 - _ . ~ stay as they are; a space is %20).
  4. Sort the pairs by encoded name (byte order) and join them as name=value with &. This is the canonical string.
  5. The string to sign is the HTTP method, the path and the canonical string, separated by a newline (\n): POST\n/v3/payment/order\n{canonical string}.
  6. The signature parameter is the lowercase hex HMAC-SHA256 of that string with your secret key.

Send the values exactly as you signed them, as a JSON body (Content-Type: application/json) or a form body (application/x-www-form-urlencoded). Parameters are signed as sent, before any trimming on our side. If you send m_timestamp or m_nonce, the request is checked under v2 only. A nonce is used up as soon as the signature is accepted, so to retry a request, sign it again with a new m_timestamp and m_nonce.

Sample v2 request

                    
                        POST /v3/payment/order
                        {
                            "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/",
                            "metadata": { "cart_id": "42" },
                            "m_timestamp": "1794460800",
                            "m_nonce": "9f86d081884c7d659a2feaa0c55ad015"
                        }
                    
                

The string to sign for the request above is:

                    
                        const stringToSign = "POST\n/v3/payment/order\nm_amount=29.00&m_callback_url=https%3A%2F%2Fcallback.url.com%2F&m_currency=PHP&m_key_id=269282cd-1954-4239-9219-6d27033baaad&m_method=GCASH&m_nonce=9f86d081884c7d659a2feaa0c55ad015&m_order_no=000001&m_timestamp=1794460800&metadata%5Bcart_id%5D=42";
                    
                

Verifying callbacks

Payment and payout callbacks carry timestamp and signature_v2. To check one, take every parameter of the callback (the query parameters of a payment callback, the JSON body of a payout callback) except signature and signature_v2, build the canonical string as above, and compute the HMAC-SHA256 of callback\n{canonical string} with your secret key. Accept the callback only if it equals signature_v2 (compare in constant time) and timestamp is within 5 minutes of your clock. The verifyCallbackV2 function in the samples below does this. The signature_v2 values in the callback examples are computed with the secret key used in the samples (IikNBQ…TG2CQ).

Legacy signature (being retired)

Requests without m_timestamp and m_nonce are still accepted with the legacy signature for now, but this will be switched off: please move to v2. The legacy payload is a string of all key-value pairs joined by = that start with m_ (where key is the name of the request parameter and value is its value), sorted alphabetically, and concatenated without separators. It does not cover metadata or payouts and does not protect against replays.

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 legacy 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; therefore, 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 compute the v2 request signature (signV2), check a callback (verifyCallbackV2) and compute the legacy signature (sign).

                                
                                    <?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);
    }
};

                                
                            
                                
                                    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;
    }
}
                                
                            
                                
                                    /**
 * 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;
                                
                            
GET /v3/transaction/status

URL: https://api.mail.sigepay.online/v3/transaction/status

Get the detailed status of the transaction.

Header

Key Value
Accept application/json

Query Parameters

Name Type Description
m_key_id* string API Key ID generated from https://mail.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 query parameters. Click here to view the request signing guide.

Payment Status

Status Description
PENDING Transaction is pending and awaiting completion.
CLEARING Payment is being processed by the acquiring bank.
SUCCESS Payment completed successfully.
REFUNDED Payment has been refunded to the customer.
CANCELLED Payment was cancelled.
FAILED Payment failed or was declined.

Responses

Code Description
200

Successful operation. Returns the detailed transaction status and customer details.

Sample Response (Pending):

                                    
                                        {
                                            "success": true,
                                            "message": "Transaction retrieved successfully",
                                            "data": {
                                                "transaction_id": "67bdff936ccda",
                                                "order_no": "ORDER-001",
                                                "status": {
                                                    "code": "PENDING",
                                                    "description": "Transaction is pending and awaiting completion",
                                                    "is_final": false,
                                                    "is_successful": false
                                                }
                                            }
                                        }
                                     
                                

Sample Response (Success):

                                    
                                        {
                                            "success": true,
                                            "message": "Transaction retrieved successfully",
                                            "data": {
                                                "transaction_id": "67bdff936ccda",
                                                "order_no": "ORDER-001",
                                                "status": {
                                                    "code": "SUCCESS",
                                                    "description": "Payment completed successfully",
                                                    "is_final": true,
                                                    "is_successful": true
                                                },
                                                "customer_details": {
                                                    "cardholder_name": "Mohamed Afzal",
                                                    "email": "afzal@example.com",
                                                    "phone": "7994459106",
                                                    "card_type": "VISA",
                                                    "card_category": "Debit",
                                                    "card_last_four": "1112",
                                                    "expiry_date": "06/2030",
                                                    "issuer_country": "PK"
                                                }
                                            }
                                        }
                                     
                                

Sample Response (Failed):

                                    
                                        {
                                            "success": true,
                                            "message": "Transaction retrieved successfully",
                                            "data": {
                                                "transaction_id": "67bdff936ccda",
                                                "order_no": "ORDER-001",
                                                "status": {
                                                    "code": "FAILED",
                                                    "description": "Payment was failed or declined",
                                                    "is_final": true,
                                                    "is_successful": false
                                                },
                                                "customer_details": {
                                                    "cardholder_name": "Mohamed Afzal",
                                                    "email": "afzal@example.com",
                                                    "phone": "7994459106",
                                                    "card_type": "VISA",
                                                    "card_category": "Credit",
                                                    "card_last_four": "0002",
                                                    "expiry_date": "12/2029",
                                                    "issuer_country": "PK"
                                                },
                                                "failure_code": "310",
                                                "failure_reason": "3DSecure authentication rejected"
                                            }
                                        }
                                     
                                
403

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

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

Payment Providers