PayNext Extra Installment App Redirection

Accept online installment payments from TrueMoney Wallet users through your website or mobile app using the PayNext Extra Installment payment method.

📋 Overview

✅ How to enable PayNext Extra Installment

To enable PayNext Extra Installment App Redirection for your account, email support@omise.co to request the feature. You will be required to review and accept updated terms and conditions before the payment method is activated.

🔄 Payment flow

PayNext Extra Installment uses an app_redirect flow. After the customer confirms their payment method, they are redirected from your website or mobile app to the TrueMoney Wallet app or TrueMoney secure checkout page to authorise and confirm the payment.

Important: There are two separate expiry windows to be aware of: - Source expiry: If the customer does not proceed to the TrueMoney application within 3 minutes of source creation, the source expires and the charge becomes expired. - Charge expiry: If the charge is not completed within 7 days of creation (see expires_at in the charge response), it expires automatically.

These are independent. Build your retry logic to handle both: re-create the source and charge for a 3-minute timeout; treat a 7-day expiry as an abandoned order.

📱 Mobile payment flow

1. The customer selects PayNext Extra Installment as their payment method on the merchant website or app.
2. The customer is redirected to their TrueMoney Wallet app and logs in.
3. The customer selects their preferred installment term and interest rate.
4. Payment details are displayed for review.
5. The customer confirms the payment.
6. A payment success screen displays the relevant payment details.

🖥️ Desktop browser payment flow

1. The customer selects PayNext Extra Installment as their payment method on the merchant website.
2. A QR code is generated and displayed on the merchant website.
3. The customer opens the TrueMoney Wallet app on their mobile device.
4. The customer navigates to the scan function in the app and scans the QR code.
5. The customer selects their preferred installment term and interest rate.
6. Payment details are displayed for review.
7. The customer confirms the payment on the confirmation page.
8. A payment success screen is displayed.

⚙️ Implementation

To accept a PayNext Extra Installment payment, complete the following steps:

1. Create a source — Create a new payment source with type: installment_paynext_extra_jumpapp using Omise.js or a mobile SDK (iOS / Android).
2. Create a charge — Create a new charge using the source identifier returned in Step 1.
3. Verify the charge — After receiving the charge.complete webhook event, retrieve the charge to confirm its status (optional but recommended).

Use your public key to create the source (client-side, in the customer's browser or mobile device).
Use your secret key to create the charge (server-side).

If source creation and charge creation must both happen server-side, you can combine them into a single API request using your secret key.

Step 1 — Creating a source

When the customer confirms they want to pay with PayNext Extra Installment, create a new source with the following parameters.

The following examples create a new PayNext Extra Installment source for ฿500.00 (50000). Replace omise_public_key / $OMISE_PUBLIC_KEY with your test public key from your dashboard.

In Omise.js, type is passed as the first argument to createSource.

Omise.js

Omise.setPublicKey(omise_public_key);

Omise.createSource('installment_paynext_extra_jumpapp', {
  "amount": 50000,
  "currency": "THB"
}, function(statusCode, response) {
  console.log(response);
});

cURL

curl https://api.omise.co/sources \
  -u $OMISE_PUBLIC_KEY: \
  -d "amount=50000" \
  -d "currency=THB" \
  -d "type=installment_paynext_extra_jumpapp"

Example response

{
  "object": "source",
  "id": "src_test_601oytj0iy7dtjgnme4",
  "livemode": false,
  "location": "/sources/src_test_601oytj0iy7dtjgnme4",
  "amount": 50000,
  "currency": "THB",
  "flow": "app_redirect",
  "type": "installment_paynext_extra_jumpapp",
  "charge_status": "unknown",
  "created_at": "2024-06-11T01:54:41Z",
  "barcode": null,
  "bank": null,
  "email": null,
  "installment_term": null,
  "ip": "35.198.236.178",
  "absorption_type": null,
  "name": null,
  "mobile_number": null,
  "phone_number": null,
  "platform_type": null,
  "scannable_code": null,
  "billing": null,
  "shipping": null,
  "items": [],
  "references": null,
  "provider_references": null,
  "store_id": null,
  "store_name": null,
  "terminal_id": null,
  "zero_interest_installments": null,
  "receipt_amount": null,
  "discounts": [],
  "promotion_code": null
}

The id field (prefixed src_) is the source identifier used in the following step.

Notable response fields

Step 2 — Creating a charge

Create a charge using the source identifier from Step 1.

Replace $OMISE_SECRET_KEY with your test secret key from your dashboard and $SOURCE_ID with the id of the source.

cURL

curl https://api.omise.co/charges \
  -u $OMISE_SECRET_KEY: \
  -d "amount=50000" \
  -d "currency=THB" \
  -d "return_uri=http://example.com/orders/345678/complete" \
  -d "source=$SOURCE_ID"

Example response

{
  "object": "charge",
  "id": "chrg_test_601oytlxd07w48h4paq",
  "location": "/charges/chrg_test_601oytlxd07w48h4paq",
  "amount": 50000,
  "currency": "THB",
  "funding_currency": "THB",
  "funding_amount": 50000,
  "net": 48047,
  "fee": 1825,
  "fee_vat": 128,
  "interest": 0,
  "interest_vat": 0,
  "refunded_amount": 0,
  "transaction_fees": {
    "fee_flat": "0.0",
    "fee_rate": "3.65",
    "vat_rate": "7.0"
  },
  "status": "pending",
  "authorize_uri": "https://pay.omise.co/payments/pay2_test_601oytlz0xfm33yubdb/authorize",
  "return_uri": "http://example.com/orders/345678/complete",
  "source": {
    "object": "source",
    "id": "src_test_601oyt8hdkdx8qoy4n9",
    "livemode": false,
    "amount": 50000,
    "currency": "THB",
    "flow": "app_redirect",
    "type": "installment_paynext_extra_jumpapp",
    "charge_status": "pending",
    "provider_references": {
      "reference_number_1": "4Nv0Qf0VJZ89KueL",
      "reference_number_2": null
    }
  },
  "authorized": false,
  "capturable": false,
  "capture": true,
  "paid": false,
  "expired": false,
  "reversed": false,
  "reversible": false,
  "refundable": false,
  "partially_refundable": false,
  "disputable": false,
  "voided": false,
  "can_perform_void": false,
  "livemode": false,
  "created_at": "2024-06-11T01:54:41Z",
  "paid_at": null,
  "expires_at": "2024-06-18T01:54:41Z"
}

Notable response fields

Creating a source and charge in a single request

If both source creation and charge creation must happen server-side, you can combine them into a single API call using your secret key.

curl https://api.omise.co/charges \
  -u $OMISE_SECRET_KEY: \
  -d "amount=50000" \
  -d "currency=THB" \
  -d "return_uri=http://example.com/orders/345678/complete" \
  -d "source[type]=installment_paynext_extra_jumpapp"

Step 3 — Completing the charge

The charge is created with a status of pending. The following sections explain how to authorise the charge, receive the webhook event, and confirm the final charge status.

Full payment sequence

Authorising the charge

Redirect the customer to the URL in the authorize_uri field of the charge response so they can authorise the payment in TrueMoney Wallet.

After completing authorisation, the customer is redirected to the return_uri you specified.

Testing: In test mode, visit authorize_uri in your browser to simulate the authorisation step. You will be presented with buttons to manually mark the charge as Successful or Failed. Use this to verify your webhook handler and return_uri logic before going live. Note that the 3-minute source expiry still applies in test mode, so complete this step promptly after creating the charge.

Receiving the charge completion webhook

Set up an endpoint on your server to receive webhook events, and register it on the Omise dashboard. Omise sends a charge.complete event when the charge reaches a final status.

Verifying the charge status

After receiving the charge.complete webhook, retrieve the charge by its id and confirm that the status in the retrieved charge matches the status in the webhook event.

Possible failure codes

↩️ Voids and refunds

• Voids: A PayNext Extra Installment charge can only be voided on the same day as the transaction authorisation.
• Refunds: Refunds can only be issued within 30 days of a successful payment.

For refund instructions, see the Refunds API documentation.

📊 Limits

🔧 Troubleshooting

The charge status is expired

There are two causes:

• 3-minute source timeout: The customer did not complete the authorisation step in TrueMoney Wallet within 3 minutes of the source being created. Create a new source and charge, then redirect the customer again.
• 7-day charge timeout: The charge was not completed within 7 days of creation (see expires_at in the charge response). This typically indicates an abandoned order. No retry is necessary unless the customer returns.

The charge status is failed with failure_code: failed_processing

A general processing failure occurred on the TrueMoney side. Prompt the customer to retry the payment. If the issue persists, contact support@omise.co.

The customer was redirected to return_uri but the charge is still pending

Do not rely solely on the return_uri redirect to determine charge status. Always wait for the charge.complete webhook event and verify the charge status by retrieving it from the API.

The QR code is not appearing on desktop

The QR code is displayed on the page at authorize_uri. Ensure the customer is being redirected to authorize_uri immediately after the charge is created. If the redirect is delayed or blocked, the QR code will not be displayed.

The amount is rejected with a validation error

Confirm the amount does not exceed the maximum of 500000 (฿5,000.00). There is no minimum. Also confirm the amount and currency values on the charge request exactly match those on the source.

The promotion_code field has no effect

Promotional codes are issued by TrueMoney and must be valid and active at the time of source creation. Contact TrueMoney directly to verify that the code is active and applicable to your transaction.

❓ Frequently asked questions

Which countries and currencies does PayNext Extra Installment support?
PayNext Extra Installment is supported in Thailand only and processes payments in Thai Baht (THB).

Does the customer need a TrueMoney Wallet account?
Yes. The customer must have an active TrueMoney Wallet account to authorise the payment, whether on mobile or desktop (via QR code scan).

What happens if the customer closes the app before confirming?
If the customer does not complete the authorisation within 3 minutes, the source expires and the charge status becomes expired. You will need to create a new source and charge.

Can I use this payment method without Omise.js?
Yes. If both source creation and charge creation occur on your server, you can use the single-request approach with your secret key — no client-side SDK required. See Creating a source and charge in a single request.

Can I offer zero-interest installments?
The zero_interest_installments field appears in the source and charge objects but is returned as null or false for PayNext Extra Installment. Interest rates are determined by TrueMoney and presented to the customer during the authorisation step.

Can I refund a PayNext Extra Installment charge?
Yes, refunds are supported within 30 days of a successful payment. Voids are only possible on the same day as the transaction. See the Refunds API documentation.

How do I test this integration?
Use your test public and secret keys from the Omise dashboard. After creating a charge, visit the authorize_uri in your browser to manually simulate a successful or failed payment.

Where can I find my API keys?
See How to access Omise API keys.

🔑 API keys

For information on how to obtain your public and secret keys, see How to access Omise API keys.

📖 Related documentation

• Charges API
• Sources API
• Webhooks API
• Omise.js
• iOS SDK
• Android SDK