Special Test Mode Values
In test mode, you may specify some special values to trigger some common scenarios.
Payments
In the test mode for the Payments (and Batch Payments) API, these account numbers for the receiver will trigger a payment failure.
| Account Number | Effect (non Batch) | Effect (Batch) |
|---|---|---|
000000000 | Failure (immediate) | Failure(this single payment) |
000000001 | Failure (later) | Failure(this single payment) |
000000002 | Success | Failure (entire batch) |
Direct Debit Authorizations
In the test mode for the Direct Debit Authorizations API (Singapore only), a successful authorization returns null for payerIdType and payerIdHash by default. Create the authorization with this bill reference number to receive mock payer identification fields instead. The value must match exactly, including case: s1234567d is a valid bill reference number but returns null for both fields.
| Bill Reference Number | Effect |
|---|---|
S1234567D | A successful authorization returns the mock payer identification fields below |
The mock values are hardcoded and not derived from a real payer ID. To verify the hash, uppercase S1234567D, SHA-256 it, and hex-encode the digest (64 characters). The result should match payerIdHash.
| Field | Value |
|---|---|
payerIdType | NRIC |
payerIdHash | 3578b829767388a631b999b7049e830827b3e99b7504581bcfefa72def689658 |
HSBC Hong Kong
In test mode, HSBC Hong Kong direct debit authorizations go to a simulated HSBC that follows HSBC's specification, so your integration sees what HSBC would answer. No SMS is sent.
A payer who banks with HSBC (payerBankCode 004) gets REQUIRES_AUTHORIZATION and an otp object. These payer account numbers make HSBC reject the authorization instead. Three are HSBC's own test accounts, so the same data also works in HSBC's test environment.
| Payer Account Number | Effect |
|---|---|
900000001005 | FAILED, PAYER_ACCOUNT_NAME_AND_ID_NOT_MATCHED (MPP01005) |
900000001006 | FAILED, PAYER_MOBILE_NUMBER_INVALID (MPP01006, mobile number does not match) |
900000001007 | FAILED, PAYER_ACCOUNT_NAME_NOT_MATCHED (MPP01007) |
002039147001 | FAILED, PAYER_MOBILE_NUMBER_INVALID (MPP01008, no mobile number held by the bank) |
002027522001 | FAILED, PAYER_ACCOUNT_TYPE_NOT_SUPPORTED (MPP03001, not a personal account) |
900000000001 | FAILED, PAYER_ACCOUNT_NOT_FOUND (MFISAC01) |
999999999999 | FAILED, OTHERS (MPP09996, bank maintenance; create a new authorization to retry) |
900000001009 | FAILED, PAYER_MOBILE_NUMBER_INVALID (RJCT, the mobile number HSBC holds is not purely numeric) |
The OTP code is always 123456. The simulated HSBC applies the same rules as HSBC:
| Rule | Error from /otp-confirmation or /otp-regeneration |
|---|---|
A wrong code; attemptsRemaining counts down from 3, codes sent at the same time included | OTP_INCORRECT |
| A 4th try after 3 wrong codes, even with the right code | OTP_ATTEMPTS_EXHAUSTED; regenerate the OTP |
| A code sent 100 seconds or more after the OTP was issued; it uses up an attempt | OTP_EXPIRED; regenerate the OTP |
An otpId that is not the latest otp.id | OTP_NOT_CURRENT |
| A 3rd OTP on the same Hong Kong day, the first one included | OTP_DAILY_LIMIT_REACHED |
| A regeneration sent while another one is still with the bank | CONFLICT (HTTP 409); use the otp the first one returns |
A correct code returns SUBMITTED. The simulated bank activates the authorization at a random time 30 to 60 seconds later, as HSBC does, and Acme checks every 3 seconds after a confirmation: expect SUCCEEDED and the direct-debit-authorizations.succeeded webhook within about a minute. An authorization whose OTP is never confirmed is deleted by HSBC after 7 days; it then becomes FAILED with PAYER_AUTHORIZATION_TIMEOUT and the direct-debit-authorizations.failed webhook is sent.
A payer at any other bank gets no OTP, and the authorization is SUBMITTED while their bank decides. The simulated bank approves it 60 seconds after creation, and Acme picks that up when it next checks with HSBC: expect SUCCEEDED and the direct-debit-authorizations.succeeded webhook about 90 seconds after creation. Msg NORMAL004000001 as ultimatePayerName does the same, as in HSBC's test data. Set ultimatePayerName to Msg EDDA00010001 to have the payer's bank reject it instead, with FAILED, PAYER_AUTHORIZATION_FAILED and the direct-debit-authorizations.failed webhook. These are HSBC's own test values.
When HSBC doesn't answer
These ultimatePayerName values make the simulated HSBC behave as HSBC does when it is unavailable or slow. They are Acme's own values, not HSBC's.
ultimatePayerName | Effect |
|---|---|
Acme TEST CREATE TIMEOUT | HSBC registered the authorization but its answer was lost. You get SUBMITTED with no otp. About 30 seconds later Acme finds the mandate at HSBC. A payer who banks with HSBC is then REQUIRES_AUTHORIZATION with no otp: call /otp-regeneration to get one, which counts as their second OTP of the day (its mobileNumber is empty: HSBC's lost answer was the one that carried it). A payer at another bank continues as above. |
Acme TEST CREATE LOST | HSBC never received the authorization. You get SUBMITTED; about 15 minutes later it becomes FAILED with OTHERS and the direct-debit-authorizations.failed webhook. Create a new authorization; the billReferenceNumber is free again. |
Acme TEST RATE LIMITED | HSBC turns the request away (too many requests): FAILED with OTHERS and the direct-debit-authorizations.failed webhook. Create a new authorization. |
Acme TEST PENDING | For a payer at another bank: their bank never answers, so the authorization stays SUBMITTED. |
Acme TEST CONFIRM UNAVAILABLE | The first /otp-confirmation gets RETRYABLE_UPSTREAM_ERROR (HTTP 503) and uses one attempt; send the code again. |
Acme TEST REGENERATE UNAVAILABLE | /otp-regeneration within 30 seconds of the last OTP gets RETRYABLE_UPSTREAM_ERROR (HTTP 503); later ones work. |
/otp-confirmation on an authorization that has no otp yet returns OTP_NOT_CURRENT: regenerate the OTP first.
After activation
HSBC reports what happens to an active authorization in a daily report, which Acme imports every morning (Hong Kong time). An authorization whose mandate HSBC cancelled, expired or deleted becomes CANCELED and the direct-debit-authorizations.canceled webhook is sent; a suspended or dormant mandate leaves it SUCCEEDED. In test mode the simulated report is imported every 10 minutes. These ultimatePayerName values are Acme's own: the authorization succeeds as usual, and a minute later its mandate changes at the simulated HSBC.
ultimatePayerName | Effect |
|---|---|
Acme TEST CANCELLED | CANCELED and the direct-debit-authorizations.canceled webhook, within about 10 minutes of SUCCEEDED |
Acme TEST EXPIRED | The same |
Acme TEST DELETED | The same |
Acme TEST SUSPENDED | Stays SUCCEEDED |
Acme TEST DORMANT | Stays SUCCEEDED |
Direct Debit Payments
In the test mode for the Direct Debit Payments API, these customer references will trigger a payment failure.
| Customer Reference | Effect |
|---|---|
fail | Failure |
Hosted Payments
In the test mode for the Hosted Payments API, these hosted payment method IDs will trigger specific scenarios.
| Hosted Payment Method ID | Effect |
|---|---|
hpm_TESTMODESUCCEEDED | successful payment |
hpm_TESTMODEFAILED_PAYLAHWALLETDELINKED | failure - customer has unlinked their PayLah! wallet |
hpm_TESTMODEPENDING_INSUFFICIENTFUNDSPENDINGTOPUP | failure - there is insufficient balance in the customer's PayLah! wallet, and they have been prompted to top up. |