TrueMoney Wallet BETA

Omise provides a set of APIs to enable your customers to make payments directly from their TrueMoney Wallet. TrueMoney Wallet enables customers to checkout faster by eliminating the need to enter their card or payment details. In order to use this feature, the customer is required to have a mobile number registered with TrueMoney Wallet. This guide will walk through the payment flow and basic implementation of this payment method.

The following applies to merchants with accounts registered in Thailand.

TrueMoney is currently in closed beta. If you are interested in accepting payments via TrueMoney Wallet, please leave your details in this form. We will provide updates as we open the service to more merchants.

Payment Flow

Customers who choose to pay via TrueMoney Wallet go through a redirect payment flow using a One-Time Password (OTP). This means that after they input their mobile number, they are prompted to authorize and confirm the payment amount using a One-Time Password sent to their phone. Upon completion, the customer is redirected back to your website.

  1. At checkout, the customer selects TrueMoney Wallet as their preferred payment method.
  2. After entering their mobile number, the customer is prompted to enter an OTP. This number will be sent to the mobile phone number provided.
  3. The customer only has to review the information and enter the OTP to confirm the payment.

Implementation

Typically, creating a TrueMoney Wallet charge involves:

  1. Creating a new payment source using the Source API
  2. Creating a new charge using the Charge API passing the source ID created in the first step.

This assumes that the TrueMoney Wallet source creation happens client-side (e.g. on a user's browser or mobile phone) using a public key while charge creation happens server-side using a secret key. We recommend using Omise.js or one of our mobile SDKs to implement the client side of this flow.

Note: Omise.js integration is forthcoming.

Alternatively, if both the creation and charge of a source must happen server-side (not recommended), then the Charge API can be used to both create and charge the source.

Creating a Source Client-side

TrueMoney Wallet payment methods are implemented as types of sources. The following code demonstrates how to create a new TrueMoney Wallet source.

Note: for the following example, you must have already set your $OMISE_PUBLIC_KEY environment variable to contain your public key.

curl https://api.omise.co/sources \
  -X POST                         \
  -u $OMISE_PUBLIC_KEY:           \
  -d "amount=100000"              \
  -d "currency=thb"               \
  -d "type=truemoney"             \
  -d "phone_number=11111111111"
{
  "object": "source",
  "id": "src_test_5fxf2nn7bvpkrutcyiu",
  "livemode": false,
  "location": "/sources/src_test_5fxf2nn7bvpkrutcyiu",
  "type": "truemoney",
  "flow": "redirect",
  "amount": 100000,
  "currency": "thb",
  "phone_number": "11111111111"
}

Creating a TrueMoney Charge

Use the value of the id attribute of the returned object above to pass as the value of the source parameter for a new charge. Because this charge involves the customer leaving the site to authorize the charge, you must also pass the parameter return_uri. This is the URL on your site to which the customer is redirected upon charge completion.

Note: for this example, you must have already set your $OMISE_SECRET_KEY environment variable to contain your secret key, and $SOURCE_ID must contain the value of the id attribute above.

curl https://api.omise.co/charges                           \
  -X POST                                                   \
  -u $OMISE_SECRET_KEY:                                     \
  -d "amount=100000"                                        \
  -d "currency=thb"                                         \
  -d "return_uri=http://example.com/orders/345678/complete" \
  -d "source=$SOURCE_ID" 
{
  "object": "charge",
  "id": "chrg_test_5fxf2ntltpp1th6yawp",
  "livemode": false,
  "location": "/charges/chrg_test_5fxf2ntltpp1th6yawp",
  "amount": 100000,
  "currency": "thb",
  "funding_amount": 100000,
  "funding_currency": "thb",
  "description": null,
  "metadata": {
  },
  "status": "pending",
  "capture": true,
  "authorized": false,
  "schedule": null,
  "reversed": false,
  "reversed_at": null,
  "expires_at": "2019-05-24T08:09:48Z",
  "expired": false,
  "expired_at": null,
  "voided": false,
  "paid": false,
  "paid_at": null,
  "transaction": null,
  "refunded": 0,
  "refunds": {
    "object": "list",
    "from": "1970-01-01T00:00:00Z",
    "to": "2019-05-17T08:09:48Z",
    "offset": 0,
    "limit": 20,
    "total": 0,
    "order": "chronological",
    "location": "/charges/chrg_test_5fxf2ntltpp1th6yawp/refunds",
    "data": [

    ]
  },
  "return_uri": "http://example.com/orders/345678/complete",
  "failure_code": null,
  "failure_message": null,
  "card": null,
  "customer": null,
  "ip": null,
  "dispute": null,
  "created": "2019-05-17T08:09:48Z",
  "source": {
    "object": "source",
    "id": "src_test_5fxf2n7baulmpak09c2",
    "type": "truemoney",
    "flow": "redirect",
    "amount": 100000,
    "currency": "thb",
    "phone_number": "11111111111"
  },
  "disputable": false,
  "capturable": false,
  "reversible": false,
  "refundable": false,
  "reference": "pay2_test_5fxf2ntr10o6ibucntm",
  "authorize_uri": "https://pay.omise.co/payments/pay2_test_5fxf2ntr10o6ibucntm/authorize"
}

Creating a Source and Charge Server-side

Alternatively, if the source must be specified at charge creation time (i.e. server-side), the Charge API can be used to create and charge a source using one API call.

curl https://api.omise.co/charges                           \
  -X POST                                                   \
  -u $OMISE_SECRET_KEY:                                     \
  -d "amount=100000"                                        \
  -d "currency=thb"                                         \
  -d "return_uri=http://example.com/orders/345678/complete" \
  -d "source[type]=truemoney"                               \
  -d "source[phone_number]=11111111111"
{
  "object": "charge",
  "id": "chrg_test_5fxf2o3fifulprgiqf7",
  "livemode": false,
  "location": "/charges/chrg_test_5fxf2o3fifulprgiqf7",
  "amount": 100000,
  "currency": "thb",
  "funding_amount": 100000,
  "funding_currency": "thb",
  "description": null,
  "metadata": {
  },
  "status": "pending",
  "capture": true,
  "authorized": false,
  "schedule": null,
  "reversed": false,
  "reversed_at": null,
  "expires_at": "2019-05-24T08:09:49Z",
  "expired": false,
  "expired_at": null,
  "voided": false,
  "paid": false,
  "paid_at": null,
  "transaction": null,
  "refunded": 0,
  "refunds": {
    "object": "list",
    "from": "1970-01-01T00:00:00Z",
    "to": "2019-05-17T08:09:50Z",
    "offset": 0,
    "limit": 20,
    "total": 0,
    "order": "chronological",
    "location": "/charges/chrg_test_5fxf2o3fifulprgiqf7/refunds",
    "data": [

    ]
  },
  "return_uri": "http://example.com/orders/345678/complete",
  "failure_code": null,
  "failure_message": null,
  "card": null,
  "customer": null,
  "ip": null,
  "dispute": null,
  "created": "2019-05-17T08:09:49Z",
  "source": {
    "object": "source",
    "id": "src_test_5fxf2o2v84ly5nu9yyf",
    "type": "truemoney",
    "flow": "redirect",
    "amount": 100000,
    "currency": "thb",
    "phone_number": "11111111111"
  },
  "disputable": false,
  "capturable": false,
  "reversible": false,
  "refundable": false,
  "reference": "pay2_test_5fxf2o3j2moe92owpy8",
  "authorize_uri": "https://pay.omise.co/payments/pay2_test_5fxf2o3j2moe92owpy8/authorize"
}

Authorization

The charge object created from the above API call will contain the attribute authorize_uri. This is the URL for the TrueMoney-operated webpage which contains the OTP input form.

In live mode, you should redirect the user to the URL specified in authorize_uri (https://pay.omise.co/...) to enter their OTP.

TrueMoney Authorize URI Live

In test mode, you can simulate this behavior by visiting the URL to manually mark the charge as successful or failed.

TrueMoney Authorize URI Test

Checking the Status

Webhooks

Use our Events API to get notified when a charge completes. Once your Webhooks URL is set, a request with the event name charge.complete will be sent whenever a TrueMoney charge is completed. See Webhooks for more information.

If the charge failed, check the failure_code and failure_message in the charge object for a detailed explanation on the reason.

code Description
payment_rejected The payment is rejected by TrueMoney service with no specific reason
failed_processing Payment processing has failed
invalid_account Mobile number is not a valid TrueMoney account
insufficient_fund TrueMoney account does not have enough funds to make a payment

Check the Charge API for more details about failure_code and failure_message.

Manual

You can also check the status of the charge by retrieving it via its id as described in Charges API and checking the status attribute:

curl -s https://api.omise.co/charges/$CHARGE_ID \
  -u $OMISE_SECRET_KEY: | jq -M .status
"pending"

Refunds

See the Refunds API documentation for information on how to refund a TrueMoney Wallet charge.

Note: TrueMoney Wallet charges cannot be voided, only refunded.

Enabling TrueMoney Wallet

You will be required to review additional Terms & Conditions before using the API for live transactions.

The minimum API version required is 2017-11-02. See API Versioning for guidance on updating your API version.