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
-
The system creates a new
reg_ref (registration reference) and saves
a record in scb_registrations table with the customer and
merchant userIDs.
-
The Financial Team system retrieves the Merchant’s SCB config
(
merchantId, subAccountId,
PUBLIC_KEY) from the merchant table using the receiving
user's ID.
-
The system contacts SCB's
/v1/registration/web/init endpoint.
-
Sent Data (Encrypted):
regRef (the new
reference ID), ref1 (combined customer-merchant ID for
uniqueness), ref2 (merchant ID), and
backUrl (return URL).
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
-
Internal System Lookup: The
regRef is used
to retrieve the stored payerUserId,
receivingUserId, and the Merchant’s
PUBLIC_KEY from the merchant table.
-
Transaction Setup: The system creates a unique payment
ID (
ref_number), records the transaction in
scb_debit_transactions, and generates a
timestamp.
-
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.
-
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.
-
C. Confirm the Result: The system checks with SCB using
/v1/payment/inquiry to verify the payment was completed
successfully.
-
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.
|