> ## Documentation Index > Fetch the complete documentation index at: https://docs.singapay.id/llms.txt > Use this file to discover all available pages before exploring further. # Binding Card > Initiates a Direct Debit binding flow. The merchant must redirect the customer to `data.redirect_url` to complete bank authentication; the link is single-use and expires at `data.expires_at` (typically ~15 minutes). Final binding outcome is delivered via the configured `direct_debit_notif_url` callback. ## OpenAPI ````yaml https://payment-b2b.singapay.id/api/docs/merchant-api.json post /api/v2.0/direct-debit/bindings openapi: 3.1.0 info: title: Singa Merchant API description: >- OpenAPI specification for the merchant/partner HTTP API. All routes below are additionally protected by `ip.whitelisted.merchant` — the caller IP must be registered for the credential or merchant. Obtain a JWT using `POST /api/v1.0/access-token/b2b` (Basic auth) or `POST /api/v1.1/access-token/b2b` (X-Signature) before calling secured endpoints. version: 1.0.0 servers: - url: https://sandbox-payment-b2b.singapay.id description: >- API host. Paths include `/api` prefix (see `RouteServiceProvider`). Replace scheme/host with your environment. security: [] tags: - name: Security description: >- Merchant authentication (`OauthMerchantTokenController`). **v1.1** B2B token uses `X-CLIENT-ID`, `X-PARTNER-ID`, and `X-Signature` (no Basic auth). Secured routes also require the issued Bearer JWT plus `X-PARTNER-ID`. - name: Accounts description: >- Account management (`routes/merchantApiRoute.php`, `v1.0`). Path parameter `{id}` is always the account ULID. - name: Balance Inquiry description: >- Merchant and per-account balance inquiry (`BalanceController`, `v1.0`). Path `account_id` is the account ULID. - name: Statements description: >- Per-account statement list and detail (`AccountController::accountStatements`, `accountStatementDetail`, prefix `v1.0/statements`). Flugger responses; detail path param `{statement_id}` maps to `statements.transaction_id`. - name: Payment Link description: >- Payment link CRUD and payment-method catalog (`PaymentLinkApiController`, prefix `v1.0/payment-link-manage`). `account_id` is ULID; `payment_link_id` is numeric `payment_links.id`. - name: Payment Link History description: >- Payment link transaction/history listing and detail (`PaymentLinkApiController`, prefix `v1.0/payment-link-histories`). `history_id` is numeric `payment_link_histories.id`. - name: Virtual Account description: >- Native VA CRUD (`VirtualAccountController`, prefix `v1.0/virtual-accounts`). `account_id` and `virtual_account_id` are ULIDs. - name: VA Transaction description: >- VA money-in transaction listing and detail (`VirtualAccountController`, prefix `v1.0/va-transactions`). - name: QRIS (Money In) description: >- MPM dynamic QRIS list, show, and generate (`QrisMpmDynamicApiController`, prefix `v1.0/qris-dynamic`). - name: QRIS (Money Out) description: >- Issuer MPM decode/inquiry, payment credit (money out), and transaction status (`QrisIssuerMpmController`, `QrisApiV2Controller::checkStatus`, prefix `v2.0/qris`). Related list/detail: `GET /api/v2.0/qris/transaction/...`. - name: E-Wallet (Money In) description: >- E-Wallet Native checkout and transactions (`EwalletNativeApiController`, `EwalletNativeTransactionApiController`, `EwalletNativeV2ApiController`). Paths include `v1.0/ewallet-native`, `v1.0/ewallet-native-transactions`, and `v2.0/ewallet-native`. - name: E-Wallet (Money Out) description: >- E-wallet disbursement / top-up to beneficiary wallets (`EWalletTopUpController`, prefix `v2.0/ewallet`). Responses use the custom **`MerchantV2ApiEnvelope`** with **`MerchantV2ResponseCode`** (SP000–SP020). - name: Card (Money In) description: >- One-time card payment, cancel, and inquiry (`CardPaymentMerchantApiController`, prefix `v2.0/card`). - name: Subscription (Recurring) description: >- Credit-card recurring subscription plans (`SubscriptionPlanApiController`, prefix `v2.0/recurring`). Plan `{id}` is UUID (`sub_plans.id`). - name: Direct Debit description: >- Direct Debit — bind a customer bank account once via hosted webview, then charge it host-to-host (`DirectDebitMerchantController`, prefix `v2.0/direct-debit`). Binding `{binding_id}` and transaction `{transaction_id}` are UUIDs. Responses use the **`MerchantV2ApiEnvelope`** with both standard SP000–SP020 codes and Direct-Debit-specific codes (`SP_DD_*`). The `/charge` endpoint is additionally protected by **`X-Signature`** + **`X-Timestamp`** (`verify.signature-internal`); see operation parameters for the signing scheme. - name: Account Transfer description: >- Move funds between sub-accounts within the same merchant (`AnotherAccountApiController`, prefix `v1.0/account-transfer`). The transfer endpoint requires request signature headers (`verify.signature-internal`). Both accounts must belong to the authenticated merchant and be accessible to the credential. - name: Disbursement (Money Out) description: >- Bank disbursement (`DisbursementController` **v1.0**, `DisbursementV2Controller` **v2.0**). **v1.0** list/show/fee/beneficiary/transfer use Flugg envelopes; v1 inquiry-status uses the **custom v2 envelope** (`MerchantV2ApiEnvelope`, codes **SP000–SP020**). **v2.0** check-beneficiary, transfer, and inquiry-status use the same custom envelope — see component schema **`MerchantV2ResponseCode`** for the full response code table. - name: Cardless Withdrawal description: >- Cardless withdrawal API for initiating ATM cash withdrawals without a physical card. Supports creating withdrawals with OTP generation, listing transaction history, viewing transaction details, canceling pending withdrawals, and deleting canceled records. All endpoints use the `v1.0/cardless-withdrawals` route prefix and the standard success/error response envelope. Path parameter `{id}` refers to the `transaction_id` (platform-assigned business identifier). paths: /api/v2.0/direct-debit/bindings: post: tags: - Direct Debit summary: Binding Card description: >- Initiates a Direct Debit binding flow. The merchant must redirect the customer to `data.redirect_url` to complete bank authentication; the link is single-use and expires at `data.expires_at` (typically ~15 minutes). Final binding outcome is delivered via the configured `direct_debit_notif_url` callback. operationId: directDebitBindingsCreate requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateDirectDebitBindingRequest' responses: '200': description: >- **SP000** Binding initiated — `data` matches `DirectDebitBindingInitiationData`. The customer must open `redirect_url` to authenticate. content: application/json: schema: $ref: '#/components/schemas/MerchantV2ApiEnvelope' example: response_code: SP000 response_message: Binding initiated data: binding_id: 9a1c5b3e-2d4f-4d8c-93cf-9a1c5b3e2d4f status: PENDING_AUTH customer_ref: cust-9001 bank_code: '008' redirect_url: https://hosted-webview.example.com/dd/bind?token=eyJhbGc... expires_at: '2026-06-04T07:40:00+07:00' payment_otp_mode: WITH_OTP '401': description: Unauthorized (missing/invalid bearer token or `X-PARTNER-ID`). content: application/json: schema: $ref: '#/components/schemas/MerchantV2ApiEnvelope' example: response_code: '4010000' response_message: Invalid or expired bearer token data: null '403': description: IP not on the merchant allowlist (`ip.whitelisted.merchant`). content: application/json: schema: $ref: '#/components/schemas/MerchantV2ApiEnvelope' example: response_code: SP403 response_message: IP address not whitelisted data: null '422': description: >- **SP018** Validation error — missing/invalid field in the request body. content: application/json: schema: $ref: '#/components/schemas/MerchantV2ApiEnvelope' example: response_code: SP018 response_message: Validation failed data: errors: phone_no: - The phone_no field is required. '502': description: >- **SP_DD_BINDING_FAILED** — upstream gateway call could not be persisted as a binding row. Merchant action: retry with the same payload (idempotent on `customer_ref` while the previous binding is still `PENDING_AUTH`). content: application/json: schema: $ref: '#/components/schemas/MerchantV2ApiEnvelope' example: response_code: SP_DD_BINDING_FAILED response_message: Failed to persist binding. Please retry. data: null security: - BearerAuth: [] PartnerId: [] components: schemas: CreateDirectDebitBindingRequest: description: >- Initiates a Direct Debit binding flow. The merchant must redirect the customer to the returned `redirect_url` to complete bank authentication. `bank_code` is optional; when omitted the hosted webview renders a bank picker. `payment_otp_mode` is a preferred charge-time mode and the bank may still enforce its own OTP rules. required: - customer_ref - phone_no properties: customer_ref: description: >- Merchant-side stable id for the customer (NOT the bank account number). Used to scope future bindings of the same customer. type: string maxLength: 15 minLength: 4 example: cust-9001 phone_no: description: >- Customer mobile phone in E.164-ish form (e.g. `+6281234567890`). The bank may use this to deliver OTP. type: string maxLength: 20 example: '+6281234567890' bank_code: description: >- 3-digit BI/SNAP code of the target bank. Common values: `002` BRI, `008` Mandiri, `009` BNI, `011` Danamon, `014` BCA, `022` CIMB, `490` BNC. type: - string - 'null' maxLength: 3 minLength: 3 example: '008' payment_otp_mode: description: >- Preferred OTP behavior for later charge requests. The actual bank flow may still require OTP regardless of this hint. type: - string - 'null' enum: - WITH_OTP - WITHOUT_OTP example: WITH_OTP success_redirect_url: description: Where the hosted webview redirects after a successful authorization. type: - string - 'null' format: uri maxLength: 512 example: https://example.com/success failure_redirect_url: description: >- Where the hosted webview redirects after a failed/cancelled authorization. type: - string - 'null' format: uri maxLength: 512 example: https://example.com/failure type: object MerchantV2ApiEnvelope: description: >- SingaPay Merchant API v2 custom response envelope (`ApiResponderHelper::responseJson`, `ApiResponseTrait`). Business outcome is determined by `response_code` (SP000–SP020), not by HTTP status alone. On success (`SP000`), `data` holds the operation payload. On errors, `data` often includes a `message` and may echo request fields. required: - response_code - response_message properties: response_code: $ref: '#/components/schemas/MerchantV2ResponseCode' response_message: $ref: '#/components/schemas/MerchantV2ResponseMessage' data: description: >- Endpoint-specific payload on success, or error context (validation message, inquiry result with `status` invalid, etc.). type: - object - 'null' additionalProperties: true type: object example: response_code: SP000 response_message: Successfully data: [] MerchantV2ResponseCode: description: SingaPay custom business response code. type: string example: SP000 MerchantV2ResponseMessage: description: Human-readable label paired with `response_code`. type: string example: Successfully securitySchemes: BearerAuth: type: http description: >- JWT issued by `POST /api/v1.1/access-token/b2b`. Send `Authorization: Bearer `. bearerFormat: JWT scheme: bearer PartnerId: type: apiKey description: Merchant API key (`Credential.api_key`). Required on every request. name: X-PARTNER-ID in: header ````