Use this skill for Setel (Setel Ventures Sdn Bhd) merchant payment integration work. The main online product is "Pay with Setel online": a checkout session that sends the customer to Setel Checkout or the Setel app, where they pay with Setel Wallet or Setel CardTerus.
Source
Read references/setel-api.md before giving factual API guidance or writing integration code. It holds environments, auth headers, the endpoint catalogue, checkout session and payment intent field tables, statuses, the webhook payload and signature algorithm, refunds, cancellation, capture, error codes and known documentation inconsistencies.
Read references/setel-other-apis.md for Pay with Setel code scan (wallet transactions), SSO/OAuth, user accounts, user payment methods, Mesra loyalty, external orders, automated parking and EV charging APIs.
Read references/setel-settlement.md for settlement reports (Setel Dashboard, SFTP), the MPF file format, and the manual settlement API.
Read references/account-setup.md for onboarding, credentials, dashboard, sandbox vs production, env var names and commercial contact.
Read references/source-map.md to pick the right official page and to see docs coverage.
Core Workflow
- Confirm the merchant has been onboarded by Setel and holds
x-api-key,x-api-secretandmerchantIdfor the right environment. - Pick the surface: online checkout session (web/mobile), code scan wallet transaction (in-person), or a partner flow (SSO, loyalty, parking, EV).
- Create a local pending order with a unique
referenceIdbefore calling Setel. - Decide capture mode:
capture: true(direct) orcapture: false(hold, then capture within 30 minutes). - Call
POST /v1/checkout/sessionsserver-side withx-api-keyandx-api-secret,amount(string, MYR),currency: "MYR",redirect.successUrl/redirect.cancelUrl, andwebhook.url. - Send the customer to the returned checkout URL (PC: Setel Checkout page; mobile: redirect link, checkout URL, or app deep link). Log the real response field names in sandbox.
- Treat
successUrlas browser UX only. Do not fulfil from the redirect. - On webhook, recompute the
signatureheader: HMAC-SHA256 keyed with hex SHA-256 ofx-api-secret, over the documented field concatenation. Constant-time compare. - Confirm with
GET /v1/checkout/sessions/{session id}(orGET /v1/payments/payment-intents/{id}) and settle idempotently only whenpaymentIntentStatusissucceededand amount, currency, referenceId and session id match. - If a held payment is final, capture with
POST /v1/payments/payment-intents/{id}/capture(never above the authorised amount) or cancel it. - Requery sessions that have no webhook after a timeout; Setel says webhooks may be lost or sent more than once.
Core Facts
- Sandbox base URL:
http://api-pre-prod.setel.com(System environment page, last updated 18 Nov 2024). Production:https://api.setel.com. - Partner auth: headers
x-api-keyandx-api-secreton every request;Content-Type: application/json. Keys are backend-only. - Create session:
POST /v1/checkout/sessions. Required body fields:amount,currency,redirect. - Retrieve session:
GET /v1/checkout/sessions/{id}. Cancel:PATCH /v1/checkout/sessions/{id}/cancel. - Payment intents:
GET /v1/payments/payment-intents/{id},POST .../{id}/capture,POST .../{id}/cancel,POST .../{id}/refund. amountis a string in ringgit (examples use"10"); onlyMYRis supported.capturedefaults totrue. Held (authorised) payments expire after 30 minutes.- Payment intent statuses:
requires_payment_method,requires_action(not supported yet),authorised,processing,failed,succeeded,cancelled,expired,partially_refunded,refunded. - Webhook is set per session via
webhook.url; the header issignature; the body hasid,createdAt,updatedAt,apiKey,paymentIntentId,paymentIntentStatus,amount,referenceId. - Signature:
secretHash = sha256_hex(x-api-secret);data = id+createdAt+updatedAt+apiKey+paymentIntentId+paymentIntentStatus+amount+referenceId(missing field = empty string);signature = hmac_sha256_hex(key=secretHash, data). - Online payment methods: Setel Wallet and Setel CardTerus. Code scan supports Setel Wallet only and has no webhook.
- Duplicate
referenceIdreturns400 REFERENCE_ID_EXISTED(9300101). - Refunds draw from the merchant available balance (not pending balance); partial refunds are allowed until
refundedAmountequalsamount. - Settlement reports are generated daily at 01:00 GMT+8 and cover 00:00 to 23:59 of the previous day.
Critical Rules
- Keep
x-api-keyandx-api-secretserver-side; never ship them to a browser or mobile bundle, never commit them. - Always send a unique
referenceIdper checkout attempt; Setel warns this prevents multiple payments and enables reconciliation. - Verify the webhook
signaturebefore trusting the body, and still requery the session or payment intent before fulfilment. - Build the signature string from the exact received string values; do not reformat timestamps or amounts.
- Handle out-of-order and duplicate webhooks: compare
updatedAtand keep the latest; make settlement idempotent on session id andpaymentIntentId. - Do not treat
processingorauthorisedas paid. Onlysucceeded(or later refund states) means funds were collected. - For
capture: false, capture or cancel within 30 minutes, or the intent becomesexpired. - Third-party acquirers must send
subMerchant(name,reference,merchantCategoryCode,state). - Treat field-name and method inconsistencies listed in
references/setel-api.mdas items to confirm in sandbox, not as settled facts. - Do not quote fees; Setel does not publish merchant rates.
Completion Criteria
A Setel integration is done only when:
- Checkout sessions are created server-side with both auth headers and a unique
referenceId. - The redirect page only shows status; fulfilment comes from a verified webhook plus a session/payment intent requery.
- Webhook handler recomputes
signaturewith the documented algorithm and passes the published test vector. - Settlement checks session id,
paymentIntentId,referenceId, amount, currencyMYR, statussucceeded, and environment. - Duplicate and out-of-order webhooks, lost webhooks (requery job), and expired holds are handled idempotently.
- Refund, cancel and capture paths are guarded against double execution and over-amount.
- Tests cover bad signature, duplicate webhook, wrong amount/reference,
failed/expired/cancelled, andsucceeded. - Deployment docs list
SETEL_API_KEY,SETEL_API_SECRET,SETEL_MERCHANT_ID,SETEL_BASE_URL, success/cancel URLs and webhook URL per environment.
Loophole Review Loop
When asked whether a Setel strategy is "100% confident", run this loop until no factual gaps remain:
- List trust boundaries: browser redirect, Setel Checkout page, Setel app deep link, backend session creator, Setel API, webhook receiver, database, fulfilment job, capture/cancel/refund jobs, settlement report import.
- Check bypasses: fake success redirect, forged webhook, signature built from re-serialised JSON, wrong secret or environment, reused
referenceId, amount mismatch,processingtreated as paid, duplicate or stale webhook overriding a newer state, lost webhook, hold expiring before capture, capture above authorised amount, refund failing on low available balance, duplicate refund. - Add fixes: server-side session creation, local pending order first, documented HMAC check with constant-time compare, requery before settle,
updatedAtordering, idempotency keys, capture deadline job, refund guard, environment-separated config. - Re-read the relevant section of
references/setel-api.md. - State remaining uncertainty: exact checkout URL field names, retrieve-by-referenceId method, webhook retry schedule, webhook source IPs, rate limits, sandbox test accounts, sandbox scheme (http vs https), and commercial terms. These are not documented and must be confirmed with Setel.