CUP QR

Overview

CUP QR is payment method to pay by using QR code. You can perform purchases through this method by using Payment Page and Gate.

General information

Payment method type QR code payments
Payment instruments bank accounts
Countries and regions CH
Payment currencies CNY
Currency conversion –
Purchases +
Payouts –
Stored credentials payments –
Full refunds –
Partial refunds –
Chargebacks –
Notes –
Onboarding and access fee Refer to your key account manager ecommpay

Interaction diagram

Payment processing by using the CUP QR payment method requires merchant's web service, one of ecommpay interfaces, and the ecommpay payment platform, as well as provider's the technical facilities.



Operations support

Interfaces Amounts
Payment Page CMS Plug-ins Gate Dashboard minimum maximum
Purchases + – + – – –

Processing scenarios

In the CUP QR method to perform a purchase operation customer needs to scan QR code by using bank mobile application.

Figure: Purchase by using Payment Page procedure diagram



Figure: Purchase by using Gate procedure diagram



The sections that follow provide detailed information about what you need to perform payments and how you can analyze the information on payments and operations.

Purchase by using Payment Page

General information

In the CUP QR method, to perform a purchase by using Payment Page, the merchant web service should 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 have Payment Page opened with the CUP QR method selected. For more information about preselecting payment methods, see in Preselecting payment methods.

The full sequence and particularities of the purchase process are provided below.



Figure: Purchase sequence in the Payment Page method:

  1. Customer initiates purchase by using the web service.
  2. The merchant web service sends to the specified ecommpay URL the purchase request for processing the purchase by using Payment Page.
  3. The payment platform receives the request for processing the purchase by using Payment Page.
  4. The payment platform performs the initial request processing that involves validation of the required parameters and signature.
  5. Requested Payment Page is generated into the ecommpay payment platform as specified in the project settings and the request parameters.
  6. Payment Page is displayed to the customer.
  7. The customer selects the CUP QR payment method and agrees to use the method (or accepts the method already selected on Payment Page and agrees).
  8. The list of supported banks is displayed to the customer on the Payment Page.
  9. The customer selects bank.
  10. The payment platform receives the purchase request for payment processing in the CUP QR service.
  11. The payment platform performs the internal purchase request processing and sends it to the CUP QR service.
  12. The purchase request is processed on the CUP QR side.
  13. The CUP QR service generates the data for the displaying QR code to the customer and sends it to the payment platform.
  14. The payment platform sends to Payment Page the data for the displaying QR code to the customer.
  15. The QR code is displayed to the customer on Payment Page.
  16. The customer scans QR code by using mobile application and completes all the required steps.
  17. The payment is processed on the CUP QR side.
  18. CUP QR service sends email with the payment result to the customer.
  19. CUP QR service sends the payment result notification to the payment platform.
  20. The payment platform sends the callback to the web service.
  21. The payment platform sends payment results to Payment Page.
  22. A page with the payment result information is displayed to the customer.

The sections that follow discuss in more details the request format and the Payment Page parameters to use in the CUP QR payment method 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 need to consider when using the CUP QR method:

  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_currency—payment currency in ISO-4217 alpha-3 format
    • payment_amount—payment amount
  2. Additionally the customer data parameters should be specified (if they are not passed in the request, the are requested from the customer on Payment Page):
    • customer_first_name and customer_last_name—first and last names in Chinese
    • customer_email—email address
    • customer_phone—phone number
    • customer_country—country of residence in ISO 3166-1 alpha-2 format
    • customer_city—city of residence in Chinese
    • customer_street—address of residence in Chinese
    • customer_zip— postal code

    And the payment description in the payment_description parameter.

  3. The currency of payment can only be CNY.
  4. If you need to have payment form displayed with the CUP QR method selected, set the force_payment_method parameter to cup-qr.
  5. If required, you can also add any other additional parameters Payment Page supports.
  6. 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 CUP QR method must include project, customer, and payment IDs, customer data, the currency and the amount of a payment in the appropriate currency, as shown in the following example:

EPayWidget.run(
    { payment_id: '876543, 
      payment_amount: 30000, 
      payment_currency: 'CNY',     
      payment_description: 'payment_876543',
      project_id: 100, 
      customer_id: '123',
      customer_first_name: '伍',
      customer_last_name: '伍',
      customer_email: 'paul@mail.com',
      customer_country: 'CH',
      customer_city: '倩',
      customer_street: '倩',
      customer_phone: '13632264147',
      customer_zip: '123456',
      signature: "kUi2x9dKHAVNU0FYldJrxh4yo8552Kt8KU+Y1Y4HASCQ9vySO...=="
    }
)

For information about all parameters available in the CUP QR method, see Parameters for opening payment form.

Callback format

The CUP QR method uses the standard format for callbacks to deliver purchase results. For more information, see Callbacks.

The following is the example of a callback with an information about successful 300.00 CNY purchase made by the 2233 customer in the 843 project.

Figure: Example of a successful purchase callback

"project_id": 843,
        "payment": {
            "id": "EP761d-6f6d",
            "type": "purchase",
            "status": "success",
            "date": "2019-12-11T12:20:17+0000",
            "method": "cup-qr",
            "sum": {
                "amount": 30000,
                "currency": "CNY"
            },
            "description": "123"
        },
        "account": {
            "number": "qwerty@qwe.fff"
        },
        "customer": {
            "phone": "2233"
        },
        "operation": {
            "id": 2000000029,
            "type": "sale",
            "status": "success",
            "date": "2019-12-11T12:20:17+0000",
            "created_date": "2019-12-11T12:18:04+0000",
            "request_id": "9a593318e4842a725b60498b-00000003",
            "sum_initial": {
                "amount": 30000,
                "currency": "CNY"
            },
            "sum_converted": {
                "amount": 30000,
                "currency": "CNY"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 1838,
                "payment_id": "1001905226143910",
                "auth_code": "",
                "date": "2019-12-11T12:18:14+0000"
            }
        },
        "signature": "y/DQVScN32bQi2BHO4YU1gfuikigFEbA...=="
    }

The following is the example of a callback for a purchase declined due to time-out.

Figure: Example of a declined purchase callback

"project_id": 843,
        "payment": {
            "id": "EP761d-6f6d",
            "type": "purchase",
            "status": "decline",
            "date": "2019-12-11T12:20:17+0000",
            "method": "cup-qr",
            "sum": {
                "amount": 30000,
                "currency": "CNY"
            },
            "description": "123"
        },
        "account": {
            "number": "qwerty@qwe.fff"
        },
        "customer": {
            "phone": "2233"
        },
        "operation": {
            "id": 2000000029,
            "type": "sale",
            "status": "decline",
            "date": "2019-12-11T12:20:17+0000",
            "created_date": "2019-12-11T12:18:04+0000",
            "request_id": "9a593318e4842a725b60498b-00000003",
            "sum_initial": {
                "amount": 30000,
                "currency": "CNY"
            },
            "sum_converted": {
                "amount": 30000,
                "currency": "CNY"
            },
            "code": "20602",
            "message": "Time-out",
            "provider": {
                "id": 1838,
                "payment_id": "1001905226143910",
                "auth_code": "",
                "date": "2019-12-11T12:18:14+0000"
            }
        },
        "signature": "y/DQVScN32bQi2BHO4YU1gfuikigFEbA...=="
    }

Related topics

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

Purchase by using Gate

General information

In the CUP QR method, 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. Provide the displaying of the QR code on the web service side.
  3. Get the callback with the payment result from the payment platform.

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



Figure: Purchase by using Gate

  1. Customer initiates purchase on the merchant web service by using CUP QR method.
  2. The web service sends the request for processing the purchase by using Gate to the specified ecommpay URL.
  3. The payment platform receives the request for processing the purchase by using Gate.
  4. The payment platform performs the initial request processing that includes validation of the required parameters and signature.
  5. The payment platform sends to the web service response with request receipt confirmation and correctness check result.
  6. The payment platform performs the internal payment request processing and sends it to the CUP QR service.
  7. The purchase request is processed on the CUP QR side.
  8. The CUP QR service generates the data for the displaying QR code to the customer and sends it to the payment platform.
  9. The payment platform sends to the web service the callback that delivers the data for the displaying QR code to the customer.
  10. The QR code is displayed to the customer on the web service side.
  11. The customer scans QR code by using mobile application and completes all the required steps.
  12. The payment is processed on the CUP QR side.
  13. The CUP QR service sends email with the payment result to the customer.
  14. The CUP QR service sends the payment result notification to the payment platform.
  15. The payment platform sends the callback to the web service.
  16. The customer receives the payment result from the web service.

The sections that follow discuss in more details the request format and the Gate parameters to use in the CUP QR payment method and provide the information on the format of callbacks with purchase results.

Request format

There are several things you must consider when using purchase requests in the CUP QR method:
  1. You perform a purchase by sending the request to /v2/payment/cup/qr/sale by using HTTP method POST.
  2. The following objects and parameters must be specified in any request:
    • 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.
    • customer—object that contains customer information:
      • id—the unique ID of the customer within your project
      • ip_address—IP address
      • first_name—first name in Chinese
      • last_name—last name in Chinese
      • phone—phone number without "+" sign
      • email—customer email
      • zip—postcode
      • country—country of residence in the ISO 3166-1 alpha-2 format
      • city—city of residence in Chinese
      • street—address of residence in Chinese
    • payment—object that contains purchase information:
      • amount—purchase amount in minor units
      • currency—purchase currency in ISO-4217 alpha-3 format
      • description—description or comment to the payment
    • return_url—URL for returning customers from bank site to merchant web service after payment performing:
      • success—URL for returning after performed payment
  3. The currency of payment can only be VND.
  4. If required, you can also add any other additional parameters Gate supports.

Thus, a correct payment request in the CUP QR method must include project, customer and payment IDs, currency and amount of the purchase, customer data, as shown in the following example:

Figure: Example of a purchase request

{
  "general": {
    "project_id": 200,
    "payment_id": "ECT_TEST_1559134591371-pz-3",
    "signature": "pK1YN6fd7yajGSWAzsbYeJo5nvotVBtOijOzgFvAU5Cc8PB...=="
  },
  "customer": {
    "id": "123",
    "ip_address": "183.57.40.238",
    "first_name": "伍",
    "last_name": "倩文",
    "phone": "13632264147",
    "email": "2524243674@email.com",
    "street":"street",
    "city": "city",
    "zip": "123045607",
    "country": "CH"
    }
  },
  "payment": {
    "amount": 1000,
    "currency": "CNY",    
    "description": "payment"
  },
  "return_url: {
    "success": "http://example.com"
  }
}

Formats of the data displayed to customers

To complete the payment, customers must get the payment QR code from you. The QR code data is sent in the callback from the payment platform in the display_data object. Therefore, before displaying the QR code, you need to accept and process such callback.

This callback is sent from the ecommpay payment platform to the URL specified in the merchant project settings. The payment status in this callback is awaiting customer action until the payment is completed by the customer.

The following is the callback fragment containing payment QR code data.

 "display_data": [
            {
                "type": "qr_data",
                "title": "QR Code",
                "data": "https://cashier.xhepay.com/paygate/union/pay/MDAyMDUxNjk0OTMwNjYyMTQzMTgwOHwwNHw0ODgxMDAwMA=="
            },
            {
                "type": "add_info",
                "title": "QR Code Timeout",
                "data": "600"
            }
        ]

Callback format

The CUP QR method uses the standard format for callbacks to deliver purchase results. For more information, see Callbacks.

The following is the example of a callback with an information about successful 300.00 CNY purchase made by the 2233 customer in the 843 project.

Figure: Example of a successful purchase callback

"project_id": 843,
        "payment": {
            "id": "EP761d-6f6d",
            "type": "purchase",
            "status": "success",
            "date": "2019-12-11T12:20:17+0000",
            "method": "cup-qr",
            "sum": {
                "amount": 30000,
                "currency": "CNY"
            },
            "description": "123"
        },
        "account": {
            "number": "qwerty@qwe.fff"
        },
        "customer": {
            "phone": "2233"
        },
        "operation": {
            "id": 2000000029,
            "type": "sale",
            "status": "success",
            "date": "2019-12-11T12:20:17+0000",
            "created_date": "2019-12-11T12:18:04+0000",
            "request_id": "9a593318e4842a725b60498b-00000003",
            "sum_initial": {
                "amount": 30000,
                "currency": "CNY"
            },
            "sum_converted": {
                "amount": 30000,
                "currency": "CNY"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 1838,
                "payment_id": "1001905226143910",
                "auth_code": "",
                "date": "2019-12-11T12:18:14+0000"
            }
        },
        "signature": "y/DQVScN32bQi2BHO4YU1gfuikigFEbA...=="
    }

The following is the example of a callback for a purchase declined due to time-out.

Figure: Example of a declined purchase callback

"project_id": 843,
        "payment": {
            "id": "EP761d-6f6d",
            "type": "purchase",
            "status": "decline",
            "date": "2019-12-11T12:20:17+0000",
            "method": "cup-qr",
            "sum": {
                "amount": 30000,
                "currency": "CNY"
            },
            "description": "123"
        },
        "account": {
            "number": "qwerty@qwe.fff"
        },
        "customer": {
            "phone": "2233"
        },
        "operation": {
            "id": 2000000029,
            "type": "sale",
            "status": "decline",
            "date": "2019-12-11T12:20:17+0000",
            "created_date": "2019-12-11T12:18:04+0000",
            "request_id": "9a593318e4842a725b60498b-00000003",
            "sum_initial": {
                "amount": 30000,
                "currency": "CNY"
            },
            "sum_converted": {
                "amount": 30000,
                "currency": "CNY"
            },
            "code": "20602",
            "message": "Time-out",
            "provider": {
                "id": 1838,
                "payment_id": "1001905226143910",
                "auth_code": "",
                "date": "2019-12-11T12:18:14+0000"
            }
        },
        "signature": "y/DQVScN32bQi2BHO4YU1gfuikigFEbA...=="
    }

Related topics

The following topics might be useful when implementing payments through Gate:

Analysis of payments results

As with other payment methods ecommpay offers, when using the CUP QR 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.