Sources: accept payments from e-wallets

sources.md

Sources

With sources, Magpie merchants can now accept payments from the following e-wallets:

• GCash (gcash)
• PayMaya (paymaya)
• Alipay (alipay)
• WeChat Pay (wechat)
• China UnionPay (unionpay)

You can also use this API for bank payments:

• BPI (bpi)
• BDO (bdo)
• UnionBank (unionbank)
• RCBC (rcbc)

To sign up for a Magpie acccount, go here: https://dashboard.magpie.im.

There are no other special configurations to do. As always, you will use your developer keys to sign the transactions you send to the API.

To test payments from the e-wallets, you will need an account for each e-wallet. Our recommendation is to make small P1 payments after your integration.

Overview

If you have encountered or integrated card payments with 3D Secure flow, you will be quite familiar with the sources flow. To initiate and create a payment:

1. Create a source token containing details about the user's transaction.
2. Given the token from step #1, call the create charge endpoint and pass the source token (src_).
3. The response for the charge call will include a checkout_url field. Most of the time, the url points to the wallet sources payment page.
4. Render or redirect the request to the provided checkout_url.
5. Your customer will be taken to the particular e-wallet's authentication and authorization page. Each e-wallet provider will have their own way of handling payment authorization. More details on each below.
6. After successful or unsuccessful payment, Magpie will initiate a call to the redirect url provided in step 1.

---

Create Source

To create a source token, you need to call POST request to https://api.magpie.im/v1.1/sources.

You need to pass your public_token for this endpoint.

Request

{
    "currency": "PHP", 
    "type": "paymaya", 
    "redirect": {
        "success": "https://merchant.com?status=success", 
        "fail": "https://merchant.com?status=fail"
    }
}

• type accepts all the listed payment methods
• redirect.success will be called if payment was successful
• redirect.fail will be called if payment failed

Response

{
    "id": "src_ZDZafiz5sM7Yf7XBkk",
    "source_type": "gcash",
    "amount": 100,
    "currency": "php",
    "redirect": {
        "success": "https://merchant.com?status=success", 
        "fail": "https://merchant.com?status=fail"
    },
    "used": false,
    "object": "source"
}

---

Create Charge using Source token

To initiate charge, create a POST request to https://api.magpie.im/v1.1/charges, same way that you call a card or bank charge but the only difference is that for sources, we pass the source token (src_)

Request

{
  "amount": 100,
  "currency": "php",
  "source": "src_ZDZafiz5sM7Yf7XBkk",
  "description": "Monthly charges",
  "statement_descriptor": "merchant.com",
  "capture": true
}

Response

{
    "id": "ch_ESIlbblPlzSHusA",
    "amount": 100,
    "amount_refunded": 0,
    "captured": false,
    "created": 1604978207,
    "currency": "PHP",
    "status": "pending",
    "statement_descriptor": "merchant.com",
    "description": "Monthly charges",
    "livemode": true,
    "gateway": "gcash",
    "source": "src_bWOHJrqilHEQWbg",
    "refunds": [],
    "version": "v1.1",
    "redirect_response": {},
    "fraud_details": {},
    "checkout_url": "https://payments.gcash.com/gcash-cashier-web/1.2.1/index.html#/confirm?bizNo=20201110121212800110170604108832189&timestamp=1604978209709&sign=YuLZewmrQRURaYazSvQs6lRkI%2B%2FbSAYYxkhWXByP5muxGSRR0cJd75XC7lbVwhjIyeapidynxpdynD2DG7Lp3aLcS1EVT0CsQUrEOwDejYpvKFce1O5aPLz1v7W%2B3mrqL%2Bzp53exIbeOKOHHz0KWYfAOCzoeXfSh7rDaM9gNxWzn0Zgia81HByIgqCA3jSWhybg%2BJfkEJ6%2FptKIRe82p2hn3s7ulrlE0it6eteMmP9ufK16euBeZSwPIJNSkSO0n2JNMN1qx%2BmrPQrs0NmOar1RtM7%2Be8hWJGLSmtlpB1MpW%2BVaDj5%2FC5ltK9R3W0ZCYIz6CkIuISO1O2CZWxxhKmg%3D%3D&merchantName=merchant.com&orderAmount=1.00",
    "object": "charge"
}

Take note of the checkout_url value, the merchant/user is expected to redirect or render a web page using that URL.

PayMaya

Create a PayMaya source

Method: POST

Request example:

{
    "currency": "PHP",
    "type": "paymaya",
    "redirect": {
        "success": "https://magpie.im?status=success",
        "fail": "https://magpie.im?status=fail"
    }
}

Response example:

{
    "id": "src_0fzxbGSrM7dWKmD43Bq8r8",
    "source_type": "paymaya",
    "currency": "php",
    "redirect": {
        "success": "https://magpie.im?status=success",
        "fail": "https://magpie.im?status=fail"
    },
    "used": false,
    "object": "source"
}

Create charge using returned token

Method: POST

Request example:

{
      "amount": 100,
      "currency": "php",
      "source": "src_0fzxbGSrM7dWKmD43Bq8r8",
      "description": "PayMaya charge",
      "statement_descriptor": "DomStore",
      "capture": true
}

Response example:

{
    "id": "ch_kAtTGpZkN50ac",
    "amount": 100,
    "amount_refunded": 0,
    "captured": false,
    "created": 1616466337,
    "currency": "PHP",
    "status": "pending",
    "statement_descriptor": "DomStore",
    "description": "PayMaya charge",
    "livemode": true,
    "gateway": "paymaya",
    "source": "src_0fzxbGSrM7dWKmD43Bq8r8",
    "refunds": [],
    "version": "v1.1",
    "redirect_response": {},
    "fraud_details": {},
    "metadata": null,
    "checkout_url": "https://payments.paymaya.com/paymaya/payment?id=ec9f5f2b-f286-47d7-bbe2-aa87584f28d0",
    "confirmation_id": null,
    "object": "charge"
}

Take the value from checkout_url, and render it (or redirect) in your app. The page looks like this:

At this point, the merchant will not be involved in the process, and it will be up to PayMaya to obtain authorization from their member for the payment request.

PayMaya offers scan to pay. This would be the screens of how it may look:

PayMaya redirect page. Let's assume the customer opens his PayMaya app and chooses to scan the QR code being presented in his computer screen.

The customer sees this on his mobile app after clicking "Scan to Pay" in PayMaya's menu.

As soon as PayMaya detects the scan, the page where the QR code was displayed turns into a processing status page.

The PayMaya mobile app will display a success page if there is enough balance in the account.

At that point the web page will redirect to the appropriate URL (success or fail), which will be the values from the source created.

Alternative way to pay

Aside from Scan to Pay, PayMaya also offers another way to authorize the payment. It looks like this:

As per usual, the payment flow starts from the screen above. The difference is that the customer selects the button beside the star. This triggers the login and OTP flow.

PayMaya presents the login screen, and the customer needs to enter the email or mobile number and the correct password.

PayMaya will send the customer an OTP via SMS, and will ask for it in the form above.

The customer will have one last chance to review the payment. Clicking on "Confirm Payment" button will trigger an authorization. The result (succes or fail) will lead to a redirect to the appropriate result, based on the web address given when the source was created.

GCash

Create a GCash source

Method: POST

Request example:

{
    "currency": "PHP",
    "type": "gcash",
    "redirect": {
        "success": "https://magpie.im?status=success",
        "fail": "https://magpie.im?status=fail"
    }
}

Response example:

{
    "id": "src_Syo4wsSSdu5rqTci0",
    "source_type": "gcash",
    "currency": "php",
    "redirect": {
        "success": "https://magpie.im?status=success",
        "fail": "https://magpie.im?status=fail"
    },
    "used": false,
    "object": "source"
}

Create charge using returned token

Method: POST

Request example:

{
  "amount": 100,
  "currency": "php",
  "source": "src_Syo4wsSSdu5rqTci0",
  "description": "GCash charge",
  "statement_descriptor": "DomStore",
  "capture": true
}

Response example:

{
    "id": "ch_RurstbusX8QLYWsrYdJvs",
    "amount": 100,
    "amount_refunded": 0,
    "captured": false,
    "created": 1616475549,
    "currency": "PHP",
    "status": "pending",
    "statement_descriptor": "DomStore",
    "description": "GCash charge",
    "livemode": true,
    "gateway": "gcash",
    "source": "src_Syo4wsSSdu5rqTci0",
    "refunds": [],
    "version": "v1.1",
    "redirect_response": {},
    "fraud_details": {},
    "metadata": null,
    "checkout_url": "https://payments.gcash.com/gcash-cashier-web/1.2.1/index.html#/confirm?bizNo=20210323121212800110170438610388783&timestamp=1616475550993&sign=UluSm2XHwZJf1efjhDksW0sq2tOp6VGWx8fab9i0cBGwbpl%2FUu4HnGwLe74GXzKqUixg4lxwm2cdGBZ3Y%2BY7KXz388OBwrIvFw7judj0KtvM6DZ4uf9T9p0%2BUhS4qRTd3minIh6geaAJLnhQrUi9IeDrFyoLSBFJ2jBdov0Uq9G43pt1yZzem%2FqqJhvePe2g%2FcB9XSNSHXNLgpUqQaj8PKOxJMOyG0KjqiJQp9O9GDPhCHsfC7f0HNutcBDAhRAwKZWhtP4%2FuZVdxjDUwUOBhqBx90uSWX05ThLptmcu2elQ%2FBlu9hw6m%2FQ7TORZ7g5REag%2FExv6h9MejdeEJcjjUA%3D%3D&merchantName=DomStore&orderAmount=1.00",
    "confirmation_id": null,
    "object": "charge"
}

Take the value from checkout_url, and render it (or redirect) in your app. The page looks like this:

The GCash redirect URL will lead to a page similar to above picture.

GCash will need the customer to input the mobile phone she has registered with the service. Once the pattern is valid, GCash page shows the button "Next" in full blue color, indicating it's active.

If the account is valid, GCash will display the OTP challenge page next. The customer will receive an SMS on her registered mobile phone.

Entering the 6-digit OTP will activate the "Next" button.

GCash will then display the PIN challenge. The customer must enter his GCash PIN correctly.

GCash gives the payer one final check for proceeding or not with the payment.

At this point, GCash is processing the authorization. Next will be a redirect to either success or fail URL indicated in the source.

Other e-wallets

The other e-wallets available for integration are WeChat Pay, Alipay, and China UnionPay. (More e-wallets may be added.)

These are handled by our QR payment service and have common user experience, as follow:

1. The merchant creates sources and charges as explained above.
2. The merchant takes the checkout_url and redirects to it.
3. A QR code will be displayed, indicating the payment request.
4. The customer will scan the QR code using the appropriate app.
5. Success or failure pages will be accessed depending on the result returned.

Alipay

The first screen seen when Alipay redirect is triggered looks like this:

The customer's mobile app will be opened, the QR will be scanned, and the success or fail redirect URLs will be called. The customer's mobile screen will more or less look like the following:

After this, the page where the QR code is displayed will change to the following:

This is an example of success. In the backend, the merchant could check the status of the charge and display a status page for the purchase.

The user experience for WeChat Pay and UnionPay are mostly similar and the difference will be that customers will scan the QR code presented at a unique URL in https://qr.magpie.im.

Some notes

As will any Magpie charge, you will be able to check the status using the same endpoint for retrieving charges, as seen in the main documentation (https://magpie.im/documentation).

You will also be able to refund the charge.