Financial Team: SCB Direct Debit API Specification (Smart City)

1. How This Works

SCB Direct Debit allows customers to pay using their bank account directly. Here's how the process works:

The process begins by checking if the customer's debit card is registered using /ourApi/v1/registration/status. If the card is not registered, redirect the customer via /ourApi/v1/registration/init to the bank's website to complete registration. After returning to the application via backUrl, poll /ourApi/v1/registration/status/{regRef} until isRegistered is true. Payment processing occurs only when /ourApi/v1/payment/debit is explicitly called.

Simple Steps to use Direct Debit for Other Teams

Step Action Input Required What It Does
1 Check if user's debit card works Payer and receiver's userId This is called registration - verifies the customer's bank account. If not registered, you'll get regRef and link for user registration.
1b Wait for registration completion regRef from Step 1 and backUrl Poll /status/{regRef} every 5-10 seconds until isRegistered becomes true. User will be at backUrl during polling.
2 Process payment (ddpay) regRef from Step 1, amount, currency type Processes the payment when called. Returns success or failure. Registration alone does not trigger payment.
3 Check payment status (future reference) refNumber from Step 2's return Allows you to check the payment information anytime after payment is completed

2. Purpose

This document outlines the specific API endpoints that the Financial Team provides to other development teams. The solution maintains strict security by following a non-storage policy for sensitive customer banking information while supporting the complete SCB Direct Debit process: Customer Registration Status Verification and Setup plus Direct Debit Payments.


3. Financial Team Database Structure for SCB Direct Debit

The Financial Team tracks and manages direct debit transactions using three main database tables. Note that merchant-specific financial configuration data (such as merchantId, subAccountId, billerId, and PUBLIC_KEY) is stored in a separate merchant table rather than the user table to properly segregate financial credentials from general user information.

Table A: merchants (Stores SCB Configuration for Users)

This table stores all SCB-specific financial configuration data for users who act as merchants (payment receivers).

Column Data Type Description Constraints / Notes
id SERIAL Unique identifier for each merchant record. Primary Key
user_id INT Links to the user who owns this merchant configuration. FK to users(id), UNIQUE
merchant_id VARCHAR(50) SCB-assigned merchant identifier for this user's account. NOT NULL, UNIQUE
sub_account_id VARCHAR(50) SCB sub-account identifier for payment processing. NOT NULL
biller_id VARCHAR(50) SCB biller identifier for this merchant account. NOT NULL
public_key TEXT SCB public key used for encrypting API requests to SCB. NOT NULL
created_at TIMESTAMPTZ Date and time when merchant configuration was created. NOT NULL, Default: now()

Table B: scb_registrations (Tracks Payer’s SCB Registration Link)

This table stores the unique reference ID needed to fetch the customer’s bank details from SCB.

Column Data Type Description Constraints / Notes
reg_ref VARCHAR(20) Unique identifier created by the Financial Team that serves as the SCB regRef during customer registration. Primary Key
payer_user_id INT The customer who will make payments (Payer). FK to users(id)
receiving_user_id INT The merchant who will receive payments (Receiver). FK to users(id)
status VARCHAR(50) Registration status (‘pending’, ‘success’, ‘failed’). NOT NULL, Default: 'pending'
created_at TIMESTAMPTZ Date and time when registration was started. NOT NULL, Default: now()

Table C: scb_debit_transactions (Tracks Individual Payments)

This table tracks individual payment transactions, storing the unique ID (ref_number) for each debit request and its completion status.

Column Data Type Description Constraints / Notes
ref_number VARCHAR(20) Unique identifier created by the Financial Team that serves as the SCB refNumber for payment processing. Primary Key
reg_ref VARCHAR(20) Links to the completed registration record that enables this payment. FK to scb_registrations(reg_ref)
ref_date_time TIMESTAMPTZ Date and time stamp sent to SCB as refDateTime for this transaction. NOT NULL
ref_time_date VARCHAR(14) Transaction reference time and date returned by SCB (refTimeDate). Indexed
customer_ref VARCHAR(50) Customer reference sent to SCB in format "payerId:receiverId" (customerRef). Indexed
amount NUMERIC(12,2) Amount of money to be debited from the customer's account. NOT NULL
currency VARCHAR(3) Currency code (e.g., USD, THB) for the transaction. NOT NULL
scb_txn_number VARCHAR(255) Transaction reference number provided by SCB after processing (txnNumber). Indexed
status VARCHAR(50) Final payment status (‘confirmed’, ‘failed’, ‘refunded’). NOT NULL, Default: 'pending'
created_at TIMESTAMPTZ Date and time when the payment request was submitted. NOT NULL, Default: now()

4. Financial Team Wrapper APIs for SCB Direct Debit

4.1 Stage 0: Registration Status Check

This API lets development teams check whether a customer (Payer) has already registered with a specific merchant (Receiver) using their internal user IDs. This check is always the first step before processing any payment. If the user is not registered, you'll get a regRef and need to redirect them to link registrationURL from Stage 1 to complete registration, then poll until isRegistered becomes true.

Action Wrapper Endpoint Method Purpose
Check Registration /ourApi/v1/registration/status GET Checks the existence and status of a Payer’s registration link to determine the next step (init or pay).

Required Input Fields (Query Parameters)

Field Type Required Description
payerUserId INT Yes System ID of the customer who will make payments.
receivingUserId INT Yes System ID of the merchant who will receive payments.

Return Value

Field Type Description
isRegistered BOOLEAN true if the customer has completed registration (statusCode "0002") with this merchant and can be charged.
regRef VARCHAR(20) The unique identifier for this registration (only included when statusCode is "1000" - meaning init has been called for this user).
status VARCHAR The status of the found registration (‘success’, ‘pending’, ‘failed’).
statusCode VARCHAR If not "1000", user has never called init (no regRef returned). If "1000", it does not necessarily mean the user is registered.
statusDesc VARCHAR This shows registration state like "Initiated", "Verified Success" or Error Messages.

4.1b Registration Status Check (by RegRef)

Alternative version for polling registration status using regRef directly. Use this after calling the init API to monitor when user completes bank registration. Poll until isRegistered becomes true.

Action Wrapper Endpoint Method Purpose
Check Registration /ourApi/v1/registration/status/{regRef} GET Check registration status using regRef directly for polling.

Required Input Fields (URL Parameter)

Field Type Required Description
regRef VARCHAR(20) Yes Registration reference ID obtained from init API or status check.

Return Value

Returns the same format as the main registration status endpoint above.

4.2 Stage 1: Customer Registration Initialization (Web Redirect)

Use this API when the status check shows isRegistered: false. It starts the SCB web-based registration process for new customers. After redirecting the user to the registrationUrl, poll /status/{regRef} until isRegistered becomes true before charging.

Action Wrapper Endpoint Method SCB API Called
Register Payer /ourApi/v1/registration/init POST /v1/registration/web/init

Required Input Fields

Field Type Required Description
customerUserId VARCHAR Yes The unique identifier for the customer requesting registration.
merchantUserId VARCHAR Yes The unique identifier for the merchant processing the registration.
backUrl VARCHAR Yes The return URL where the customer should be redirected after completing SCB registration.

Wrapper Logic

  1. The system creates a new reg_ref (registration reference) and saves a record in scb_registrations table with the customer and merchant userIDs.
  2. The Financial Team system retrieves the Merchant’s SCB config (merchantId, subAccountId, PUBLIC_KEY) from the merchant table using the receiving user's ID.
  3. The system contacts SCB's /v1/registration/web/init endpoint.

Return Value

Field Type Description
registrationUrl VARCHAR SCB web page URL where the customer should be sent to complete their bank registration.
regRef VARCHAR(20) The unique ID created in the Financial Team’s system. Required for the debit API.

4.3 Stage 2: Direct Debit Payment

Use this API only after confirming you have a valid regRef where isRegistered is true. This processes the complete payment transaction.

Action Wrapper Endpoint Method SCB Workflow Handled
Debit Payment /ourApi/v1/payment/debit POST Gets account info → Processes payment → Checks final status

Required Input Fields

Field Type Required Description
regRef VARCHAR(20) Yes Registration reference ID that links the customer to the merchant.
amount NUMERIC(12,2) Yes Amount of money to charge the customer.
currency VARCHAR(3) Yes Currency code using international standard (default is "THB" for Thai Baht).

Wrapper Logic

  1. Internal System Lookup: The regRef is used to retrieve the stored payerUserId, receivingUserId, and the Merchant’s PUBLIC_KEY from the merchant table.
  2. Transaction Setup: The system creates a unique payment ID (ref_number), records the transaction in scb_debit_transactions, and generates a timestamp.
  3. A. Fetch Payer Details (Dynamic): Call SCB /v1/registration/inquiry using the regRef. The response is decrypted to retrieve the Payer’s accountNo. These values are NOT STORED IN THE DATABASE.
  4. B. Process the Payment: The system tells SCB to charge the customer using /v1/payment/direct/ddpay, providing the account number and our transaction identifiers.
  5. C. Confirm the Result: The system checks with SCB using /v1/payment/inquiry to verify the payment was completed successfully.
  6. Record Keeping: The system updates our scb_debit_transactions table with the final payment status and SCB's transaction number.

Return Value

Field Type Description
success BOOLEAN true if the payment completed successfully.
refNumber VARCHAR(20) Our system's unique identifier for this payment transaction.
paymentRefId VARCHAR SCB's unique transaction reference number.

4.4 Stage 3: Status Inquiry Endpoints

Use this API to check the status of a payment at any time using the refNumber provided when the payment was initiated.

Endpoint Method Purpose
/ourApi/v1/payment/status/{refNumber} GET Gets the current status and reference numbers for a specific payment.

Required Input Fields

Field Type Required Description
refNumber VARCHAR(20) Yes Payment ID from the debit request (passed as URL parameter).

Return Value

Field Type Description
refNumber VARCHAR(20) The unique ID of the payment transaction.
status VARCHAR The final status of the payment (‘confirmed’, ‘failed’, ‘pending’) from the database.
scbTxnNumber VARCHAR(255) The transaction ID provided by SCB (scb_txn_number).
regNumber String Merchant reference number.
refDateTime String Merchant reference date and time per transaction. Format: yyyyMMddHHmmss.
amount Number Transaction amount. Ex: 100.00
currency String Transaction currency. Ex: THB
customerRef String Customer reference.
statusCode String Transaction status code (see link for payment status).
statusDesc String Transaction status description.

5. Variable Glossary and Source Mapping

Complete reference of all variables used in the SCB Direct Debit system, their sources, and how they map between different APIs.

Variable Used In SCB API Field Format Source/Description
regRef Registration/Payment APIs regRef [0-9a-f] hexadecimal Generated by wrapper, stored in scb_registrations table. Links customer to merchant registration. IMPORTANT: Each regRef can only be used once for registration. If customer doesn't complete registration or you need a new registration URL, you must generate a completely new regRef by calling the init API again.
accountNo Registration inquiry response accountNo String(10) Customer's bank account number. Retrieved from SCB, used temporarily, then discarded for security.
customerRef Registration/Payment APIs ref1 / customerRef [0-9a-f] hexadecimal and : Combined customerId:merchantId identifier. Created from ref1, stored in scb_debit_transactions with payment details.
refNumber Payment APIs refNumber [0-9a-f] hexadecimal Unique payment transaction ID generated by wrapper, stored in scb_debit_transactions table.
refDateTime Payment APIs refDateTime yyyyMMddHHmmss timestamp generated by wrapper for transaction, stored in scb_debit_transactions table.
accountNumber Payment charge API accountNumber String(10) Customer's bank account number retrieved from registration inquiry (section 4.1), used for payment processing and discarded after.
payerUserId Wrapper APIs N/A [A-Z0-9] Internal system ID of the customer making payments. Input by other teams.
receivingUserId Wrapper APIs N/A [A-Z0-9] Internal system ID of the merchant receiving payments. Input by other teams.
backUrl Registration init API backUrl String(255) Return URL where SCB redirects customer after completing bank registration. Input by other teams.
registrationUrl Registration init response registrationUrl String SCB bank website URL where customer completes registration. Returned by wrapper init API.
isRegistered Status check APIs N/A Boolean Boolean flag indicating if customer has completed registration and can be charged. Determined by wrapper logic.
statusCode Status check APIs statusCode String(4) SCB status codes (e.g., "1000", "0001", "0002"). Handled internally by wrapper to determine isRegistered value.
statusDesc Status check APIs statusDesc String SCB status descriptions (e.g., "Initiated", "Verified Success"). Handled internally by wrapper.
ref1 SCB APIs ref1 [A-Z0-9] Reference field used by SCB APIs, typically contains customer identifier.
ref2 SCB APIs ref2 [A-Z0-9] Secondary reference field used by SCB APIs for additional identification.
encryptedValue SCB APIs encryptedValue String Encrypted data payload sent to/from SCB APIs containing sensitive information.