Step 1: Payment Methods

Retrieve available methods and saved payment options for your customer.

Request headers

All three endpoints use these headers. Sign an empty body and the sorted query when present.

Field	Type	Required	Description
X-Api-Key	string	Yes	Your API key; keep it on your backend.
X-Timestamp	string	Yes	Current Unix time in seconds; within five minutes of server time.
X-Nonce	string	Yes	Fresh identifier for every request, including retries.
X-Signature	string	Yes	v1= followed by the request's HMAC signature.

Follow API Key Authentication.

Get payment methods

GET https://api.iimmpact.com/v2/payment-methods

Query fields

Field	Type	Required	Description
customer_external_id	string	Yes	Your own customer ID, 1–100 characters, matched exactly. Use the same value when creating a payment. URL-encode it, including any +, &, or /.

An unknown customer ID returns no saved methods. Your backend must authorize the customer making the lookup.

Request example

curl 'https://api.iimmpact.com/v2/payment-methods?customer_external_id=CUS-1042' \
  --header "X-Api-Key: $API_KEY" \
  --header "X-Timestamp: $TIMESTAMP" \
  --header "X-Nonce: $NONCE" \
  --header "X-Signature: v1=$SIGNATURE"

Response fields

Field	Type	Description
data.payment_methods	array	Usable payment methods. Empty when none are available.
code	string	Method code for calculation and payment creation.
display_name	string	Display name.
icon_url	string or null	null when no icon is available.
description	string or null	null when no display text is available.
fee	object	Method's fixed or percentage fee. Calculate Order returns the exact payable total.
payment_details_schema	object or null	Fields to send in payment_method_details for a new payment. Each entry in fields has a type and required flag. null means no details are needed.
saved_payment_methods	array	This customer's saved options for this method. Empty when none exist.
saved_payment_methods[].saved_payment_method_id	string	Send as top-level saved_payment_method_id to pay with this saved option.
saved_payment_methods[].display_name	string	Ready-to-display label.
saved_payment_methods[].card	object	Display-only brand, last4, expiry_month, and expiry_year. Expiry values may be null.

If a method's payment_details_schema contains option_code, call Get method options first and send the selected option's code as payment_method_details.option_code. Currently this applies to FPX only.

When paying with a saved method, send saved_payment_method_id instead of payment_method_details.

Response example — 200

{
  "data": {
    "payment_methods": [
      {
        "code": "CARD",
        "display_name": "Card",
        "icon_url": null,
        "description": null,
        "payment_details_schema": {
          "fields": {
            "card_number": { "type": "string", "required": true },
            "expiry_month": { "type": "string", "required": true },
            "expiry_year": { "type": "string", "required": true },
            "cvv": { "type": "string", "required": true },
            "cardholder_first_name": { "type": "string", "required": true },
            "cardholder_last_name": { "type": "string", "required": true },
            "cardholder_email": { "type": "string", "required": true },
            "cardholder_phone_number": { "type": "string", "required": true }
          }
        },
        "fee": {
          "type": "percentage",
          "value": "1.70"
        },
        "saved_payment_methods": [
          {
            "saved_payment_method_id": "01J9Z6Q2W8X4K7M3N5P1R2S3T4",
            "display_name": "VISA ending in 1091",
            "card": {
              "brand": "VISA",
              "last4": "1091",
              "expiry_month": 12,
              "expiry_year": 2029
            }
          }
        ]
      },
      {
        "code": "FPX",
        "display_name": "FPX Online Banking",
        "icon_url": null,
        "description": null,
        "payment_details_schema": {
          "fields": {
            "option_code": { "type": "string", "required": true }
          }
        },
        "fee": {
          "type": "fixed",
          "value": "2.00"
        },
        "saved_payment_methods": []
      }
    ]
  }
}

Errors

HTTP	Code	Action
400	invalid_customer_external_id	Supply a non-empty customer ID of at most 100 characters.

Get method options

GET https://api.iimmpact.com/v2/payment-methods/{payment_method_code}/options

Call this when a method's payment_details_schema.fields contains option_code; currently only FPX has options. No query fields and no customer ID.

Path fields

Field	Type	Required	Description
payment_method_code	string	Yes	Method code from Get payment methods, for example FPX.

Request example

curl 'https://api.iimmpact.com/v2/payment-methods/FPX/options' \
  --header "X-Api-Key: $API_KEY" \
  --header "X-Timestamp: $TIMESTAMP" \
  --header "X-Nonce: $NONCE" \
  --header "X-Signature: v1=$SIGNATURE"

Response fields

Field	Type	Description
data.payment_method_code	string	The requested method code.
data.options	array	Selectable options. For FPX, the supported personal banks; empty when FPX is unavailable to your account.
options[].code	string	Send as payment_method_details.option_code when creating the payment.
options[].display_name	string	Name to show in your picker, for example a bank name.

Response example — 200

Shortened; FPX returns every supported bank.

{
  "data": {
    "payment_method_code": "FPX",
    "options": [
      { "code": "CIMB_FPX", "display_name": "CIMB Bank" },
      { "code": "PUBLIC_FPX", "display_name": "Public Bank" }
    ]
  }
}

Errors

HTTP	Code	Action
400	invalid_payment_method	The method has no selectable options; currently only FPX does.

Remove a saved payment method

DELETE https://api.iimmpact.com/v2/payment-methods/{saved_payment_method_id}

The removed method can no longer be used for new payments. Existing payments are not affected. Refresh the customer's payment methods afterwards.

Path fields

Field	Type	Required	Description
saved_payment_method_id	string	Yes	ID from saved_payment_methods.

Query fields

Field	Type	Required	Description
customer_external_id	string	Yes	The customer who owns the saved method, URL-encoded as for Get payment methods.

Request example

curl --request DELETE "https://api.iimmpact.com/v2/payment-methods/$SAVED_PAYMENT_METHOD_ID?customer_external_id=CUS-1042" \
  --header "X-Api-Key: $API_KEY" \
  --header "X-Timestamp: $TIMESTAMP" \
  --header "X-Nonce: $NONCE" \
  --header "X-Signature: v1=$SIGNATURE"

Response — 204

Success returns 204 No Content with an empty body. Removing an already removed method also returns 204.

Errors

HTTP	Code	Action
404	saved_method_not_found	The ID is unknown or belongs to another customer. Refresh the customer's payment methods.
400	invalid_customer_external_id	Supply a non-empty customer ID of at most 100 characters.

See shared errors for authentication and service failures on all three endpoints.

Next: Calculate Order.