# Acme Maybank Singapore Payments (H2H) (/guides/mbb-sg-payments)



This describes validations and allowed data formats for Acme payments going
through Maybank MBB Singapore (SWIFT BIC: MBBESGSGXXX). These rules are
validated by Acme and further validated by the bank. These rules may be
stricter than what the bank requires.

### Common Definitions [#common-definitions]

* SWIFT Character Set:
  * The 26 uppercase Latin letters `A`-`Z`
  * The 26 lowercase Latin letters `a`-`z`
  * The 10 digits `0`-`9`
  * Forward slash `/`
  * Hyphen `-`
  * Question mark `?`
  * Colon `:`
  * Left and right parentheses `(` `)`
  * Full stop `.`
  * Comma `,`
  * Single quote `'`
  * Plus sign `+`
  * Space ` `

## General notes [#general-notes]

* Currency must be **SGD** for FAST, GIRO, and PAYNOW payments. BKTR payments are not restricted to SGD.
* `receiver.bank` (FAST and GIRO) is the beneficiary bank's BIC11. Acme validates it as alphanumeric with a maximum of 11 characters.

## Field visibility on bank portal and statements [#field-visibility-on-bank-portal-and-statements]

Use this as a guide when deciding the value to populate in each field.

### Customer Reference [#customer-reference]

* `customerReference` is an optional field.
* If not provided, Maybank's core banking system generates a reference ID automatically.
* Acme suggest to populate the **Invoice Number** or **Document Reference Number** that will be sent to the beneficiary in this field.

| Maybank field name | Where it appears                                                                                        | What the recipient sees                                                         |
| ------------------ | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| Debit description  | Your Maybank statement and the Transaction Reference column on the Maybank M2E portal                   | -                                                                               |
| Credit reference   | This reference is sent to the beneficiary's bank and should appear in your beneficiary's bank statement | The value you provide in `customerReference` or the auto-generated reference ID |

### Payment Details [#payment-details]

* `paymentDetails` is an optional field for FAST, PAYNOW, and GIRO payments. It must not be provided for BKTR.
* It is sent to the beneficiary's bank as additional payment information.
* Whether the beneficiary sees this value depends on the beneficiary's bank. Not all banks surface this field to account holders.

| Maybank field name | Where it appears   | What the recipient sees                                                                                              |
| ------------------ | ------------------ | -------------------------------------------------------------------------------------------------------------------- |
| Payment details    | Beneficiary's bank | The value you provide in `paymentDetails`. Whether it is shown to the beneficiary depends on the beneficiary's bank. |

## FAST [#fast]

<Callout type="info">
  * 4 characters `purposeCode` is mandatory for `FAST` payments. Refer to the [list](https://www.abs.org.sg/docs/library/mnemonic_purpose_codes.pdf) provided by The Association of Banks in Singapore (ABS).
  * The maximum amount for FAST payments is SGD 200,000 per transaction.
</Callout>

| field                                   | pattern / charset     | max length | mandatory/optional |
| --------------------------------------- | --------------------- | ---------- | ------------------ |
| payments\[N].customerReference          | SWIFT                 | 35         | O                  |
| payments\[N].paymentDetails             | SWIFT                 | 140        | O                  |
| payments\[N].purposeCode                | Alphanumeric          | 5          | M                  |
| payments\[N].receiver.name              | SWIFT                 | 120        | M                  |
| payments\[N].receiver.bank              | Alphanumeric          | 11         | M                  |
| payments\[N].receiver.bankAccountNumber | Numeric (digits only) | 34         | M                  |

Example Request:

```json
{
  "type": "FAST",
  "paymentDate": "2026-06-30",
  "senderAccountId": "intacc_0H3BQNTQGBW2W",
  "senderAccountCurrency": "SGD",
  "currency": "SGD",
  "payments": [
    {
      "amount": 10000,
      "customerReference": "INV-001",
      "paymentDetails": "Payment for invoice 001",
      "purposeCode": "OTHR",
      "receiver": {
        "name": "Tan Ah Kow",
        "bank": "DBSSSGSGXXX",
        "bankAccountNumber": "9876543210"
      }
    }
  ]
}
```

## PAYNOW [#paynow]

<Callout type="info">
  * Acme does not validate the `proxyValue` patterns. Follow the rules specified below to avoid rejection by the bank.
  * `receiver.bank` and `receiver.bankAccountNumber` must not be provided.
  * The maximum amount for PAYNOW payments is SGD 200,000 per transaction.
</Callout>

| field                                     | pattern / charset                                                      | max length | mandatory/optional |
| ----------------------------------------- | ---------------------------------------------------------------------- | ---------- | ------------------ |
| payments\[N].customerReference            | SWIFT                                                                  | 35         | O                  |
| payments\[N].paymentDetails               | SWIFT                                                                  | 140        | O                  |
| payments\[N].purposeCode                  | Alphanumeric                                                           | 5          | M                  |
| payments\[N].receiver.name                | SWIFT                                                                  | 120        | M                  |
| payments\[N].receiver.proxyType           | `MOBILE` or `NRIC` or `UEN`                                            |            | M                  |
| payments\[N].receiver.proxyValue (MOBILE) | `+` followed by up to 15 digits <br /> Example: `+6591234567`          | 35         | M                  |
| payments\[N].receiver.proxyValue (NRIC)   | 9 uppercase alphanumeric characters <br /> Example: `S7800000A`        | 35         | M                  |
| payments\[N].receiver.proxyValue (UEN)    | 9 to 13 uppercase alphanumeric characters <br /> Example: `201688888A` | 35         | M                  |

Example Request:

```json
{
  "type": "PAYNOW",
  "paymentDate": "2026-06-30",
  "senderAccountId": "intacc_0H3BQNTQGBW2W",
  "senderAccountCurrency": "SGD",
  "currency": "SGD",
  "payments": [
    {
      "amount": 10000,
      "customerReference": "INV-002",
      "paymentDetails": "Payment for invoice 002",
      "purposeCode": "OTHR",
      "receiver": {
        "name": "Tan Ah Kow",
        "proxyType": "MOBILE",
        "proxyValue": "+6591234567"
      }
    }
  ]
}
```

## GIRO [#giro]

<Callout type="info">
  * 4 characters `purposeCode` is mandatory for `GIRO` payments. Refer to the [list](https://www.abs.org.sg/docs/library/mnemonic_purpose_codes.pdf) provided by The Association of Banks in Singapore (ABS).
</Callout>

| field                                   | pattern / charset     | max length | mandatory/optional |
| --------------------------------------- | --------------------- | ---------- | ------------------ |
| payments\[N].customerReference          | SWIFT                 | 35         | O                  |
| payments\[N].paymentDetails             | SWIFT                 | 140        | O                  |
| payments\[N].purposeCode                | Alphanumeric          | 5          | M                  |
| payments\[N].receiver.name              | SWIFT                 | 120        | M                  |
| payments\[N].receiver.bank              | Alphanumeric          | 11         | M                  |
| payments\[N].receiver.bankAccountNumber | Numeric (digits only) | 34         | M                  |

Example Request:

```json
{
  "type": "GIRO",
  "paymentDate": "2026-06-30",
  "senderAccountId": "intacc_0H3BQNTQGBW2W",
  "senderAccountCurrency": "SGD",
  "currency": "SGD",
  "payments": [
    {
      "amount": 10000,
      "customerReference": "INV-003",
      "paymentDetails": "Payment for invoice 003",
      "purposeCode": "SALA",
      "receiver": {
        "name": "Tan Ah Kow",
        "bank": "OCBCSGSGXXX",
        "bankAccountNumber": "9876543210"
      }
    }
  ]
}
```

## BKTR [#bktr]

Book transfers move funds between accounts within Maybank SG (MBBESGSGXXX).

<Callout type="info">
  * `receiver.bank` must not be provided.
  * `paymentDetails` must not be provided for book transfers.
  * `purposeCode` must not be provided for book transfers.
</Callout>

| field                                   | pattern / charset     | max length | mandatory/optional |
| --------------------------------------- | --------------------- | ---------- | ------------------ |
| payments\[N].customerReference          | SWIFT                 | 35         | O                  |
| payments\[N].receiver.name              | SWIFT                 | 120        | M                  |
| payments\[N].receiver.bankAccountNumber | Numeric (digits only) | 34         | M                  |

Example Request:

```json
{
  "type": "BKTR",
  "paymentDate": "2026-06-30",
  "senderAccountId": "intacc_0H3BQNTQGBW2W",
  "senderAccountCurrency": "SGD",
  "currency": "SGD",
  "payments": [
    {
      "amount": 10000,
      "customerReference": "INV-004",
      "receiver": {
        "name": "Tan Ah Kow",
        "bankAccountNumber": "9876543210"
      }
    }
  ]
}
```

## Payment Response [#payment-response]

Payment status definitions:

| Status       | Description                                                                       |
| ------------ | --------------------------------------------------------------------------------- |
| `PROCESSING` | Status upon creation.                                                             |
| `SUBMITTED`  | Payment file uploaded to Maybank. Awaiting acknowledgment and final confirmation. |
| `COMPLETED`  | Payment confirmed successful by the bank.                                         |
| `FAILED`     | Payment rejected by the bank. Check `underlyingErrorMessage` for details.         |

### Maybank status mapping [#maybank-status-mapping]

Maybank reports its own transaction status in the return file it sends back to Acme.

Acme maps each Maybank status to an Acme payment status.

<Callout type="info">
  * A payment stays `SUBMITTED` while Maybank reports a non-final status.
  * Acme keeps checking for the latest status until Maybank reports a final status.
</Callout>

| Acme status  | Maybank transaction status | Maybank description                                    |
| ------------ | -------------------------- | ------------------------------------------------------ |
| `PROCESSING` | —                          | Payment created in Acme. Not yet sent to Maybank.      |
| `SUBMITTED`  | Successfully Sent to Bank  | Pending processing by Maybank or the beneficiary bank. |
| `SUBMITTED`  | New                        | Pending action from maker.                             |
| `SUBMITTED`  | Pending Verification       | Pending action from verifier.                          |
| `SUBMITTED`  | Pending Authorisation      | Pending action from authoriser.                        |
| `SUBMITTED`  | Pending Releaser           | Pending action from releaser.                          |
| `SUBMITTED`  | Returned                   | Payment returned by verifier or authoriser.            |
| `COMPLETED`  | Successful                 | Payment successful.                                    |
| `FAILED`     | Bank Rejected              | Payment failed at the bank.                            |
| `FAILED`     | Rejected                   | Payment rejected by verifier, authoriser, or releaser. |
| `FAILED`     | Stopped                    | Payment stopped.                                       |
| `FAILED`     | Expired                    | Transaction expired after a number of days.            |
| `FAILED`     | Deleted                    | Payment deleted by the maker.                          |