Boost Wallet

Overview

Introduction

Boost Wallet is a payment method which allows you to process payments in Malaysian ringgits by using e-wallets in Malaysia. This method supports purchases.

This article provides information about working with the Boost Wallet method: general insights are presented in the Overview section, while information about the actions required to process payments and perform other actions is presented in the sections that follow.

General information

Payment method type digital wallet payments
Payment instruments digital wallets
Countries and regions MY
Payment currencies MYR
Currency conversion –
One-time purchases +
Credential-on-file purchases –
Full refunds –
Partial refunds –
Payouts –
Chargebacks –
Notes –
Onboarding and access fee refer to your ecommpay key account manager

Interaction diagram

Payment processing by using the Boost Wallet method involves the merchant's web service, one of ecommpay interfaces, the ecommpay payment platform, and technical facilities of the Boost Wallet service.



Operations support

Various platform interfaces can be used to process payments and perform operations using the Boost Wallet method. Purchases can be processed by using Payment Page, Gate and Dashboard (using payment links).

Processing scenarios

To perform a purchase by using the Boost Wallet method, a customer should receive on Payment Page or in the merchant's web service a QR-code to complete the payment using the e-wallet.

The customer payment scenario via Payment Page looks like this.

Figure: Proceeding to payment



Figure: Selecting method



Figure: Authentication



Figure: Confirming payment



Figure: Redirecting to the payment form



Figure: Redirecting to the web service



General scenarios of processing purchases and payouts can be presented as follows.

Figure: Purchase by using Payment Page



Figure: Purchase by using Gate



Purchase by using Payment Page

General information

To process a purchase through Payment Page by using the Boost Wallet method, the merchant's web service is required to send a request with all required parameters and signature to the ecommpay URL and receive a callback with the result. The full sequence and special aspects of purchase processing are provided below.



Figure: Purchase sequence by using Payment Page

  1. A customer initiates a purchase in the web service.
  2. The web service sends the request for opening Payment Page to the specified ecommpay URL.
  3. The request for opening Payment Page is sent to the payment platform.
  4. The payment platform receives the request and validates the required parameters and signature.
  5. Payment Page is generated based on the project and request parameters.
  6. Payment Page is displayed to the customer.
  7. The customer selects the Boost Wallet method.
  8. The payment form is displayed to the customer corresponding to the request.
  9. The customer enters the necessary data.
  10. The payment platform receives the request for processing the payment by using the Boost Wallet method.
  11. The payment platform processes the request and sends it to the Boost Wallet service.
  12. The purchase request is processed and a QR code are generated on the Boost Wallet service side.
  13. The Boost Wallet service sends the QR code to the payment platform.
  14. The payment platform sends the QR code and the payment instruction to Payment Page.
  15. The QR code and the payment instruction are displayed to the customer on Payment Page.
  16. The customer completes the payment according to the instruction by scanning the QR code in the Boost Wallet mobile application.
  17. The purchase is processed in the Boost Wallet service.
  18. The payment result is displayed to the customer in the Boost Wallet mobile application.
  19. The Boost Wallet service sends a notification about the result to the payment platform.
  20. The payment platform sends the payment result callback to the web service.

Information about the formats of requests and callbacks used for processing payments by using the Boost Wallet method via Payment Page is presented further in this section; general information about working with the Payment Page API is presented in Interaction concepts.

Request format

There are several things you need to consider when sending purchase requests by using the Boost Wallet method:

  1. The following parameters required for any payment must be specified:
    • project_id—project identifier obtained from ecommpay during integration
    • payment_id—payment identifier unique within the project
    • payment_currency—payment currency code in the ISO-4217 alpha-3 format
    • payment_amount—payment amount in the smallest currency unit
    • customer_id—customer identifier unique within the project
  2. The following parameters required for any payment must be specified: project_id, payment_id, payment_currency, payment_amount, customer_id.
  3. The currency of payment can only be MYR.
  4. There are the mandatory parameters: customer_first_name, customer_last_name, customer_email, customer_phone—the first and last names, email address and phone number of the customer.
  5. If you need to have the payment form displayed with the Boost Wallet method selected, set the force_payment_method parameter to boost.
  6. Additionally, any other parameters available for working with Payment Page can be used (details).
  7. After all target parameters are specified, generate a signature (details).

Thus, a correct request for opening the payment form using the Boost Wallet method must contain the project identifier, basic payment information (identifier, amount, and currency code), customer information and signature.

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "MYR",
   "customer_id": "customer1",
   "customer_first_name": "Putra",
   "customer_last_name": "Cane",
   "customer_phone": "60321669552",
   "customer_email": "customer@example.com",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

Figure: Example of sufficient data in a purchase request

{
   "project_id": 120,
   "payment_id": "580",
   "payment_amount": 1000,
   "payment_currency": "MYR",
   "customer_id": "customer1",
   "customer_first_name": "Putra",
   "customer_last_name": "Cane",
   "customer_phone": "60321669552",
   "customer_email": "customer@example.com",
   "signature": "kUi2x9dKHAVNU0FYldOcZzUCwX6R\/ekpZhkIQg=="
}

Callback format

The Boost Wallet 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 information about a 1000,00 MYR purchase made in the 635 project.

Figure: Example of callback data indicating that the purchase has been processed

{
        "project_id": 635,
        "payment": {
            "id": "EP9a11-3704",
            "type": "purchase",
            "status": "success",
            "date": "2019-03-22T06:20:51+0000",
            "method": "boostViaEGHL",
            "sum": {
                "amount": 10000,
                "currency": "MYR"
            },
            "description": "123"
        },
        "account": {
            "number": "qwe@qwe.qwqw"
        },
        "customer": {
            "id": "sasha",
            "phone": "555"
        },
        "operation": {
            "id": 126,
            "type": "sale",
            "status": "success",
            "date": "2019-03-22T06:20:51+0000",
            "created_date": "2019-03-22T06:20:35+0000",
            "request_id": "f587b6309ccb",
            "sum_initial": {
                "amount": 10000,
                "currency": "MYR"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "MYR"
            },
            "provider": {
                "id": 1352,
                "payment_id": "123123",
                "date": "2019-03-22T06:20:49+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "AoBE429Tp7suALwVK81YfHPVW75FFHYyezXIZ1ZopQZDRjGEBx9kXpi5Q=="
    }

The following is the example of a callback with information about a declined purchase.

Figure: Example of callback data indicating that the purchase has been declined

{
        "project_id": 635,
        "payment": {
            "id": "EP0ec0-9074",
            "type": "purchase",
            "status": "decline",
            "date": "2019-03-22T06:23:56+0000",
            "method": "boostViaEGHL",
            "sum": {
                "amount": 10,
                "currency": "MYR"
            },
            "description": "123"
        },
        "account": {
            "number": "qwe@qwe.qwqw"
        },
        "customer": {
            "id": "sasha",
            "phone": "555"
        },
        "operation": {
            "id": 1000000126,
            "type": "sale",
            "status": "decline",
            "date": "2019-03-22T06:23:56+0000",
            "created_date": "2019-03-22T06:23:32+0000",
            "request_id": "73201c0a413f",
            "sum_initial": {
                "amount": 10,
                "currency": "MYR"
            },
            "sum_converted": {
                "amount": 10,
                "currency": "MYR"
            },
            "provider": {
                "id": 1352,
                "payment_id": "123123",
                "date": "2019-03-22T06:23:54+0000",
                "auth_code": ""
            },
            "code": "20000",
            "message": "General decline"
        },
        "signature": "LDuxQYuGsgNXeV6aCKbsfNec7J8pRoliCf2n0/RkmXfRL1ElQ8vTw3v0f4SFg=="
    }

Useful links

The following articles can be useful when implementing purchases via Payment Page:

Purchase by using Gate

General information

To process a purchase through Gate by using the Boost Wallet method, the merchant's web service is required to do the following:

  1. Send a request with all the required parameters and signature to the ecommpay URL.
  2. Receive an intermediate callback from the payment platform and redirect the customer to the Boost Wallet service.
  3. Receive the final callback from the payment platform.

The full sequence and special aspects of purchase processing are provided below.

Figure: Purchase sequence by using Gate

  1. A customer initiates a purchase by using the Boost Wallet method in the web service.
  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.
  4. The payment platform validates the required parameters and signature in the request.
  5. The payment platform sends the response to the web service with information about the receipt of the request and its validity (details).
  6. The payment platform performs further processing of the request (with parameter consistency check) and sends it to the Boost Wallet service.
  7. The request is processed on the Boost Wallet service side.
  8. The Boost Wallet service sends the redirection data the QR code for the customer to the payment platform.
  9. The payment platform sends the callback with the QR code and redirection data in the redirect_data object to the web service.
  10. The QR code and the payment instruction are displayed to the customer on the web service.
  11. The customer completes the payment according to the instruction at one of the available payment terminals by using one of the received codes.
  12. The payment is processed on the payment terminal service side.
  13. The customer receives the payment result on the Boost Wallet service.
  14. The Boost Wallet service sends the payment result notification to the payment platform.
  15. The payment platform sends the payment result callback to the web service.

Information about the formats of requests and callbacks used for processing payments by using the Boost Wallet method via Gate is presented further in this section. General information about working with the Gate API is presented in Interaction concepts.

Request format

There are several things you need to consider when sending purchase requests by using the Boost Wallet method:

  1. To initiate each purchase, send a separate POST request to the /v2/payment/wallet/boost/sale endpoint. This endpoint belongs to the group /v2/payment/wallet/{payment_method}/sale.
  2. Each request must include the following objects and parameters:
    • Object general—general purchase information:
      • project_id—project identifier obtained from ecommpay during integration
      • payment_id—payment identifier unique within the project
      • signature—request signature generated after all required parameters are specified (details—in the Signature generation and verification) (details)
    • Object payment—payment information:
      • amount—payment amount in the smallest currency unit
      • currency—payment currency code in the ISO-4217 alpha-3 format
      • description—payment description
    • Object customer—customer information:
      • id—customer identifier unique within the project
      • ip_address—customer customer IP address relevant for the initiated payment
      • first_name—customer first name
      • last_name—customer last name
      • email—customer email address
      • phone—customer phone number
  3. The currency of a purchase can only be MYR.
  4. Additionally, any other parameters included in the specification can be used.

Thus, a correct purchase request by using the Boost Wallet method must contain the project identifier, basic payment information (identifier, amount, and currency code), customer information and the signature.

{
  "general": {
    "project_id": 318,
    "payment_id": "EP5fb7-bdg6",
    "signature": "testiuhgfcvbnm8f/kjhg\lkjhgvxbnmcvgfjdssAPOPKSJiojhbnm",
  },
  "payment": {
    "amount": 50000,
    "currency": "MYR",
    "description": "payment"
  },
  "customer": {
    "id":"2990",
    "first_name":"Petra",
    "last_name":"Davis",
    "ip_address":"192.0.2.0",
    "phone":"123456",
    "email":"customer@example.com",
  }
}

Figure: Example of sufficient data in a purchase request

{
  "general": {
    "project_id": 318,
    "payment_id": "EP5fb7-bdg6",
    "signature": "testiuhgfcvbnm8f/kjhg\lkjhgvxbnmcvgfjdssAPOPKSJiojhbnm",
  },
  "payment": {
    "amount": 50000,
    "currency": "MYR",
    "description": "payment"
  },
  "customer": {
    "id":"2990",
    "first_name":"Petra",
    "last_name":"Davis",
    "ip_address":"192.0.2.0",
    "phone":"123456",
    "email":"customer@example.com",
  }
}

Formats of intermediate callbacks for customer redirection

Each payment made with the Boost Wallet method requires redirection of customers from the merchant's web service to the Boost Wallet service. To redirect a customer it is necessary to receive an intermediate callback from the payment platform and use the information included in the redirect_data object. The format of such callbacks is standard (details), and the following objects and parameters are included in the redirect_data object:

  • body—object with data to be sent in the request body
  • method—parameter specifying the HTTP method for sending the request (GET or POST)
  • url—parameter containing a link for redirection

Figure: redirect_data example

"redirect_data": {
    "body": [],
    "method": "GET",
    "url": "https://onlinepayment.boost-my.com/index.php?token=c639de48340c4a532ba6a03d5"
  }

Final callback format

The Boost Wallet 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 information about a 1000,00 MYR purchase made in the 635 project.

Figure: Example of callback data indicating that the purchase has been processed

{
        "project_id": 635,
        "payment": {
            "id": "EP9a11-3704",
            "type": "purchase",
            "status": "success",
            "date": "2019-03-22T06:20:51+0000",
            "method": "boostViaEGHL",
            "sum": {
                "amount": 10000,
                "currency": "MYR"
            },
            "description": "123"
        },
        "account": {
            "number": "qwe@qwe.qwqw"
        },
        "customer": {
            "id": "sasha",
            "phone": "555"
        },
        "operation": {
            "id": 126,
            "type": "sale",
            "status": "success",
            "date": "2019-03-22T06:20:51+0000",
            "created_date": "2019-03-22T06:20:35+0000",
            "request_id": "f587b6309ccb",
            "sum_initial": {
                "amount": 10000,
                "currency": "MYR"
            },
            "sum_converted": {
                "amount": 10000,
                "currency": "MYR"
            },
            "provider": {
                "id": 1352,
                "payment_id": "123123",
                "date": "2019-03-22T06:20:49+0000",
                "auth_code": ""
            },
            "code": "0",
            "message": "Success"
        },
        "signature": "AoBE429Tp7suALwVK81YfHPVW75FFHYyezXIZ1ZopQZDRjGEBx9kXpi5Q=="
    }

The following is the example of a callback with information about a declined purchase.

Figure: Example of callback data indicating that the purchase has been declined

{
        "project_id": 635,
        "payment": {
            "id": "EP0ec0-9074",
            "type": "purchase",
            "status": "decline",
            "date": "2019-03-22T06:23:56+0000",
            "method": "boostViaEGHL",
            "sum": {
                "amount": 10,
                "currency": "MYR"
            },
            "description": "123"
        },
        "account": {
            "number": "qwe@qwe.qwqw"
        },
        "customer": {
            "id": "sasha",
            "phone": "555"
        },
        "operation": {
            "id": 1000000126,
            "type": "sale",
            "status": "decline",
            "date": "2019-03-22T06:23:56+0000",
            "created_date": "2019-03-22T06:23:32+0000",
            "request_id": "73201c0a413f",
            "sum_initial": {
                "amount": 10,
                "currency": "MYR"
            },
            "sum_converted": {
                "amount": 10,
                "currency": "MYR"
            },
            "provider": {
                "id": 1352,
                "payment_id": "123123",
                "date": "2019-03-22T06:23:54+0000",
                "auth_code": ""
            },
            "code": "20000",
            "message": "General decline"
        },
        "signature": "LDuxQYuGsgNXeV6aCKbsfNec7J8pRoliCf2n0/RkmXfRL1ElQ8vTw3v0f4SFg=="
    }

Useful links

The following articles can be useful when implementing purchases via Gate:

Analysis of payments results

To analyse information about payments made with the Boost Wallet method and other methods, you can use:

  • Dashboard interface toolkit with various lists and analytic panels.
  • Reports in CSV file format, available via the Reports section (one-time and periodically).
  • Data in JSON format, sent by program requests to a specified URL available by using the Data API interface.

If you have any questions, refer to the documentation (Dashboard and Using Data API) and ecommpay technical support.