Dragonpay

General information

Interaction diagram

Payment processing by using one of the Dragonpay payment methods requires merchant web service, one of the ecommpay interfaces, and the ecommpay payment platform, as well as the Dragonpay service that provides payment processing that involves banks and other parties.

Operations support

* To request a full or partial refund, customer needs to submit the online refund form.

For more information about bills payment facilities and their amount limits, see Bills payment facilities and their amount limits.

Processing scenarios

In the Dragonpay methods, purchase involves customer redirection to the Dragonpay form.

Figure: Payment by using Payment Page

Figure: Payment by using Gate

Bills payment facilities and their amount limits

Bills payment facilities are provided by Dragonpay. Each of the facilities has individual code used to identify the bills payment facility in callbacks and specific requirements for amount limits.

The table below provides information about these bills payment facilities for informational purposes only, as it may change without additional notice; for the most recent list of supported bills payment facilities, contact your ecommpay key account manager.

General information

In the Dragonpay methods, when processing a purchase by using Payment Page, the merchant web service is required to send a request with all the required parameters and signature to the ecommpay URL and get the callback with the payment result from the payment platform. When opening Payment Page, you can either allow your customer to select the Dragonpay methods from the list of other payment methods on Payment Page or have Payment Page opened with one of the Dragonpay methods selected. For more information about preselecting payment methods, see Preselecting payment methods.

The following diagram provides the detailed picture of the payment processing procedure.

The sections that follow discuss in more details the request format and the Payment Page parameters to use in the Dragonpay payment methods and provide the information on the format of callbacks with payment results. For the general information on how to use the API, see Payment Page API Description.

Request format

There are several things you must consider when using the Dragonpay methods:

1. You must provide values for the basic minimum of parameters. Listed below are the parameters that are mandatory for any payment method:
   • customer_id—the unique ID of the customer within your project
   • project_id—the project ID obtained from ecommpay
   • payment_id—payment ID unique within the project
   • payment_amount—payment amount in minor units
   • payment_currency—payment currency in ISO-4217 alpha-3 format
2. If you need to have Payment Page displayed with one of the Dragonpay methods selected, set the force_payment_method parameter to:
   • online-banking-dragonpay—the online banking method
   • otc-atm-dragonpay—the OTC and ATM cash method
   • mobile-dragonpay—the mobile wallet method
3. If required, you can also add any other additional parameters Payment Page supports.
4. After you specify all the parameters you need, you must create the signature for the request. For instructions on how to sign a payment request, see Signature generation and verification.

Thus, a correct payment request in the Dragonpay methods must include project, customer and payment IDs, amount and currency of a payment in the appropriate currency and the signature, as shown in the following example:

EPayWidget.run(
    { payment_id: 'ECT_TEST_15470375651583', 
      payment_amount: amount for example, 
      payment_currency: 'currency for example', 
      project_id: 580, 
      customer_id: '123',
      signature: "kUi2x9dKHAVNU0FYldJrxh4yo+52Kt8KU+Y1Y4HASCQ9vyS
                        O\/RLCvhtT4DqtVUkDJrOcZzUCwX6R\/ekpZhkIQg=="
    }
)

For information about all parameters available in the Dragonpay methods, see Parameters for opening payment form.

Callback format

In the Dragonpay methods, the callbacks that deliver purchase results use the standard format described in Callbacks.

Note that unlike other payment methods, in the Dragonpay methods, the callbacks do not contain any specific method name from the group of the Dragonpay payment methods. Instead, the callbacks contain the following data:

• dragonpay—the payment method group name passed in the method parameter of the payment object.
• The name of bills payment facility within specific payment method passed in the endpoint_id parameter of the operation.provider object. (For more detailed information about bills payment facilities and their codes, see Bills payment facilities and their amount limits.)

The following example of callback contains an information about successful 10.00 PHP purchase made in the 580 project by using the UCPB ATM/Cash Payment bills payment facility.

{
        "project_id": 580,
        "payment": {
            "id": "ECT_TEST_15470375651583",
            "type": "purchase",
            "status": "success",
            "date": "2019-01-14T15:32:47+0000",
            "method": "dragonpay",
            "sum": {
                "amount": 1000,
                "currency": "PHP"
            },
            "description": "ECT_TEST_15470375651583"
        },
        "operation": {
            "id": 19907000002680,
            "type": "sale",
            "status": "success",
            "date": "2019-01-14T15:32:47+0000",
            "created_date": "2019-01-14T15:29:25+0000",
            "request_id": "1f6b17a91782602b127403ba97f0b2cff2d82791-92
                                d62a12c048b7cb7c057cfb11112119c7db8307",
            "sum_initial": {
                "amount": 1000,
                "currency": "PHP"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "PHP"
            },
            "provider": {
                "id": 1165,
                "payment_id": "WVUFHH55",
                "auth_code": "",
                "endpoint_id": "UCXB"
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "FZZUc4IZa1zO+WokUvz063QqsFnUPevaQBE8l/Zq3hd
                            dq9wyhWRWkeLL8xdU8sWDWFn54K3f0BVSakCedm2dxw=="
    }

The following example of callback is for a payment rejected due to amount or frequency limitation.

{
        "project_id": 580,
        "payment": {
            "id": "ECT_TEST_1547027708135",
            "type": "purchase",
            "status": "decline",
            "date": "2019-01-09T12:58:04+0000",
            "method": "dragonpay",
            "sum": {
                "amount": 1000,
                "currency": "PHP"
            },
            "description": "ECT_TEST_1547027708135"
        },
        "operation": {
            "id": 12225000002575,
            "type": "sale",
            "status": "decline",
            "date": "2019-01-09T12:58:04+0000",
            "created_date": "2019-01-09T12:27:59+0000",
            "request_id": "ac0ff611f811045c4b3f82c499158c0d02f9e1d5-4343dab2d9ffbd3d71d453931db2a1870aed09eb",
            "sum_initial": {
                "amount": 1000,
                "currency": "PHP"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "PHP"
            },
            "provider": {
                "id": 1165,
                "payment_id": "U3N9EUE4",
                "date": "2019-01-09T20:28:05+0000",
                "auth_code": ""
            },
            "code": "20101",
            "message": "Decline due to amount or frequency limit"
        },
        "signature": "Cova73mh3yF+2awvR5qDPN1DpVAfv+LVQanLRze1KjqkNYWri
                           8KtVl5A6W2wve4gZPq/m/uDS618+RTk4sSB3w=="
    }

Related topics

The following topics might be useful when implementing payments by using Payment Page:

• Interaction concepts
• Signature generation and verification
• Payment models and statuses
• Information of operations performing

General information

In the Dragonpay methods, when processing a purchase by using Gate, the merchant web service is required to do the following:

1. Send a request with all the required parameters and signature to the ecommpay URL.
2. Perform redirection of a customer to the Dragonpay service.
3. Get the callback with the payment result from the payment platform.

The following diagram provides the detailed picture of the payment processing procedure.

The sections that follow discuss in more details the request format and the Gate parameters to use in the Dragonpay payment methods and provide the information about formats of the data for redirecting customers and the information about the format of callbacks with payment results.

Request format

There are several things you must consider when using purchase requests in the Dragonpay methods:

1. You perform purchases by sending a POST request to the following endpoint: /v2/payment/online-banking/dragonpay/sale. This endpoint is an online banking endpoint of the /v2/payment/online-banking/{payment_method}/sale group.
2. You must provide values for the basic minimum of the following objects and parameters:
   • general—object that contains general request identification information:
     • project_id—the project ID obtained from ecommpay
     • payment_id—payment ID unique within the project
     • signature—signature created after you specify all the required parameters. For more information about signature generation, see Signature generation and verification.
   • payment—object that contains purchase information:
     • amount—purchase amount in minor units
     • currency—purchase currency in ISO-4217 alpha-3 format
     • extra_param—specific method name from the group of Dragonpay payment methods:
       • online_banking—the online banking method
       • otc_atm—the OTC and ATM cash method
       • mobile—the mobile wallet method
   • customer—object that contains customer information:
     • id—the unique ID of the customer within your project
     • ip_address—customer IP address
3. If required, you can also add any other additional parameters Gate supports.

Thus, a correct payment request in the Dragonpay methods must include project, customer and payment IDs, signature, amount and currency of the purchase, specific method name from the group of the Dragonpay payment methods, customer IP address, as shown in the following example:

{
    "general": {
        "project_id": 2852,
        "payment_id": "EPd6db-b9db",
        "signature": "U5LCm6489ly9cXCKIVBNV0mFr4XiCruECSyQEbT1hSX
                          J70zuH4s05cFDqLks8ZJMR6iNdlUtm1EdHHdA3D19Qg=="
    },
    "payment": {
        "amount": 10000,
        "currency": "PHP",
        "extra_param": "online_banking"
    },
    "customer": {
        "id": "123",
        "ip_address": "248.121.176.220"
    }
}

Formats of the customer redirection data

In the Dragonpay methods, when redirecting customer to the Dragonpay form, it is required to do the following:

1. Get a callback with the redirect_data object from the payment platform.
2. Generate full redirect URL in the following format {url}?tokenid={tokenid}&mode={mode} by using parameter values contained in the redirect_data object.
3. Open the full redirect URL by using GET (HTTP) method.

The redirect_data object contains the following parameters with values received from the Dragonpay service:

• method—the request method
• body—object that contains following information:
  • tokenid—token ID for purchase. Note that validity of this token is limited only to at most one hour.
  • mode—numeric ID of one of the Dragonpay methods:
    • 1—the online banking method
    • 6—the OTC and ATM cash method
    • 128—the mobile wallet method
• url—basic URL for redirecting to the Dragonpay form

The following example of callback code contains required parameters: the request method, the IDs of token and one of the Dragonpay methods, as well as basic URL.

"redirect_data": {
            "method": "GET",
            "body": {
                "tokenid": "f252d914dce5f0522da611d9e33fb781",
                "mode": "1"
            },
            "encrypted": [],
            "url": "https://gw.dragonpay.ph/Pay.aspx"
        }

Format of callback with purchase results

In the Dragonpay methods, the callbacks that deliver purchase results use the standard format described in Callbacks.

Note that unlike other payment methods, in the Dragonpay methods, the callbacks do not contain any specific method name from the group of the Dragonpay payment methods. Instead, the callbacks contain the following data:

• dragonpay—the payment method group name passed in the method parameter of the payment object.
• The name of bills payment facility within specific payment method passed in the endpoint_id parameter of the operation.provider object. (For more detailed information about bills payment facilities and their codes, see Bills payment facilities and their amount limits.)

The following example of callback contains an information about successful 10.00 PHP purchase made in the 580 project by using the UCPB ATM/Cash Payment bills payment facility.

{
        "project_id": 580,
        "payment": {
            "id": "ECT_TEST_15470375651583",
            "type": "purchase",
            "status": "success",
            "date": "2019-01-14T15:32:47+0000",
            "method": "dragonpay",
            "sum": {
                "amount": 1000,
                "currency": "PHP"
            },
            "description": "ECT_TEST_15470375651583"
        },
        "operation": {
            "id": 19907000002680,
            "type": "sale",
            "status": "success",
            "date": "2019-01-14T15:32:47+0000",
            "created_date": "2019-01-14T15:29:25+0000",
            "request_id": "1f6b17a91782602b127403ba97f0b2cff2d82791
                              -92d62a12c048b7cb7c057cfb11112119c7db8307",
            "sum_initial": {
                "amount": 1000,
                "currency": "PHP"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "PHP"
            },
            "provider": {
                "id": 1165,
                "payment_id": "WVUFHH55",
                "auth_code": "",
                "endpoint_id": "UCXB"
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "FZZUc4IZa1zO+WokUvz063QqsFnUPevaQBE8l/Zq3hddq9wyhW
                          RWkeLL8xdU8sWDWFn54K3f0BVSakCedm2dxw=="
    }

The following example of callback is for a payment rejected due to amount or frequency limitation.

{
        "project_id": 580,
        "payment": {
            "id": "ECT_TEST_1547027708135",
            "type": "purchase",
            "status": "decline",
            "date": "2019-01-09T12:58:04+0000",
            "method": "dragonpay",
            "sum": {
                "amount": 1000,
                "currency": "PHP"
            },
            "description": "ECT_TEST_1547027708135"
        },
        "operation": {
            "id": 12225000002575,
            "type": "sale",
            "status": "decline",
            "date": "2019-01-09T12:58:04+0000",
            "created_date": "2019-01-09T12:27:59+0000",
            "request_id": "ac0ff611f811045c4b3f82c499158c0d02f9e1d5
                              -4343dab2d9ffbd3d71d453931db2a1870aed09eb",
            "sum_initial": {
                "amount": 1000,
                "currency": "PHP"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "PHP"
            },
            "provider": {
                "id": 1165,
                "payment_id": "U3N9EUE4",
                "date": "2019-01-09T20:28:05+0000",
                "auth_code": ""
            },
            "code": "20101",
            "message": "Decline due to amount or frequency limit"
        },
        "signature": "Cova73mh3yF+2awvR5qDPN1DpVAfv+LVQanLRze1KjqkNYW
                         ri8KtVl5A6W2wve4gZPq/m/uDS618+RTk4sSB3w=="
    }

Related topics

The following topics might be useful when implementing payments by using Gate:

• Interaction concepts
• Signature generation and verification
• Payment models and statuses
• Information of operations performing

As with other payment methods ecommpay offers, when using the Dragonpay method, you have several options to analyse the information about payments and operations performed by using the method—alone or in conjunction with other methods.

You can load and analyse all the necessary information in Dashboard, for instance you can use the analytic panels on the Analytics tab to this end.

Also, you can export the information for further analysis by using third party analytical tools. The following options are available:

• Dashboard allows you to download reports in CSV and XLS formats—by using the tools on the Payments tab. You can perform export as a one-time download to your local computer or have payment data regularly exported and delivered to email addresses you specify.
• Data API allows you to have payment information exported in JSON format and delivered to a URL you specify. The payment information is exported by using the /operations/get queries.

If you have any further questions regarding payment data analysis, contact ecommpay technical support.