> ## 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.

# Overview

> Accept card payments via SingaPay. Process one-time payments, void/refund, and check transaction status.

<Note>
  **Money In Operation** — Funds are transferred from the customer's card to your SingaPay Payment Gateway account.
</Note>

## API Overview

<CardGroup cols={2}>
  <Card title="API Version" icon="code-branch">
    v2.0
  </Card>

  <Card title="Base Path" icon="route">
    `/api/v2.0/card`
  </Card>

  <Card title="Authentication" icon="lock">
    Bearer Token (JWT, OAuth 2.0 client credentials)
  </Card>

  <Card title="Content-Type" icon="file-code">
    `application/json`
  </Card>
</CardGroup>

***

## Authentication

Merchants must obtain a JWT access token before calling Card endpoints. See [Authentication](/api-reference/authentication) for token requests, required headers, and IP whitelist setup.

***

## Base URL

| Environment     | Base URL                              |
| --------------- | ------------------------------------- |
| Production      | `https://{your-domain}/api/v2.0/card` |
| Staging / Local | `https://{your-domain}/api/v2.0/card` |

***

## Card Payment Flow

```mermaid theme={null}
sequenceDiagram
    participant C as Customer
    participant M as Merchant System
    participant S as SingaPay API
    participant P as Card Provider

    M->>C: Collect card details
    Note over M,C: Card number, expiry, CVV, holder name

    M->>S: POST /{account_id}/payment
    Note over M,S: Amount, customer info, card data

    S->>P: Submit payment authorization
    P-->>S: Auth result

    alt 3DS Required
        S-->>M: action: redirect (payment_url / html_form)
        M->>C: Redirect to 3DS page
        C->>P: Complete 3DS authentication
        P-->>S: 3DS result + final authorization
        S->>S: Update status: pending → success / failed
    else No 3DS
        S->>S: Update status: pending → success / failed
    end

    S-->>M: Payment result
    S-->>M: Webhook notification (optional)
    M->>S: GET /{account_id}/inquiry-status/{id} (optional)
    S-->>M: Latest transaction status
```

***

## Transaction Status Lifecycle

<Steps>
  <Step title="pending">
    Awaiting 3DS (includes internal pre-submission state).
  </Step>

  <Step title="processing">
    Payment submitted, awaiting final result.
  </Step>

  <Step title="success">
    Payment completed successfully.
  </Step>

  <Step title="failed">
    Payment failed (issuer declined or error).
  </Step>

  <Step title="cancelled">
    Voided — transaction was not captured.
  </Step>

  <Step title="refunded">
    Refunded after capture.
  </Step>
</Steps>

***

## Path Parameters

| Parameter      | Description                                                                     |
| -------------- | ------------------------------------------------------------------------------- |
| `{account_id}` | Merchant Account ULID — e.g. `01K5G4FZZ18DMK0M5QTR8Y9QY9`                       |
| `{id}`         | Transaction ID (format: `99` + ULID, 28 chars) — e.g. `9901JAB3CD4E5F6G7H8J9K0` |

***

## Available Endpoints

<CardGroup cols={3}>
  <Card title="Payment (One-Time)" icon="credit-card" href="./payment-one-time">
    Process a one-time card payment (full or installment) in a single request with amount, customer info, and card data.
  </Card>

  <Card title="Cancel Transaction" icon="ban" href="./cancel-transaction">
    Void or refund a transaction depending on its current status.
  </Card>

  <Card title="Inquiry Status" icon="magnifying-glass" href="./inquiry-status">
    Check the latest transaction status and optionally update the local record.
  </Card>
</CardGroup>

***

## Error Responses

### HTTP Status Codes

| Code  | Description                                     |
| ----- | ----------------------------------------------- |
| `200` | Success                                         |
| `400` | Bad Request (validation or business rule error) |
| `401` | Unauthorized (invalid or missing token)         |
| `404` | Account or resource not found                   |
| `422` | Validation error                                |
| `500` | Internal server error                           |

### Standard Error Format

All API responses follow the v2 format with `response_code` and `response_message`:

```json theme={null}
{
  "response_code": "SP001",
  "response_message": "Human-readable error message",
  "data": {
    "transaction_id": "9901JAB3CD4E5F6G7H8J9K0M1N2"
  }
}
```

### Response Codes

| Code    | Description                              | HTTP Status |
| ------- | ---------------------------------------- | ----------- |
| `SP000` | Success                                  | 200         |
| `SP001` | Transaction Failure (issuer declined)    | 400         |
| `SP002` | General Failure (internal error)         | 500         |
| `SP009` | Transaction Not Found                    | 404         |
| `SP012` | Bad Request (invalid status, validation) | 400         |
| `SP020` | Merchant Account Not Found               | 404         |

***

## Appendix

### Installment Type Reference

| Value | Description  |
| ----- | ------------ |
| `1`   | Full payment |
| `2`   | Installment  |

### Installment Month Options

| Value | Description |
| ----- | ----------- |
| `1`   | 1 month     |
| `3`   | 3 months    |
| `6`   | 6 months    |
| `12`  | 12 months   |

### Transaction ID Format

| Channel  | Format                 | Example                       |
| -------- | ---------------------- | ----------------------------- |
| Card     | `99` + ULID (28 chars) | `9901JAB3CD4E5F6G7H8J9K0M1N2` |
| E-Wallet | `88` + ULID            | `8801JAB3CD4E5F6G7H8J9K0M1N2` |
| QRIS     | `66` + ULID            | `6601JAB3CD4E5F6G7H8J9K0M1N2` |

***

## Important Notes

<AccordionGroup>
  <Accordion title="Single-Step Payment" icon="bolt">
    Card payments are processed in a **single API call** that includes amount, customer info, and card data together — no pre-registration step required.
  </Accordion>

  <Accordion title="3DS Authentication" icon="shield-check">
    When the issuing bank requires 3DS, the payment response includes a `payment_url` or `html_form` field. Render this for the customer to complete authentication before the transaction finalises.
  </Accordion>

  <Accordion title="Cancellation (Void vs Refund)" icon="rotate-left">
    Transactions can be **voided** (before capture) or **refunded** (after capture) using the Cancel endpoint. Both return `status: "success"` — use the `cancel_type` field to distinguish which occurred.
  </Accordion>

  <Accordion title="IP Whitelisting" icon="server">
    Merchant API routes require IP whitelisting. Ensure your server IP is registered under the merchant account before going live.
  </Accordion>

  <Accordion title="Installment Payments" icon="calendar">
    Supports full payment and installment options (1, 3, 6, or 12 months) via the `installment` and `installment_month` request parameters.
  </Accordion>
</AccordionGroup>

***

## Changelog

| Date       | Description                                                                                                                                           |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| 2026-02-25 | Initial documentation                                                                                                                                 |
| 2026-02-25 | Transaction reference kept internal; removed from API responses                                                                                       |
| 2026-02-25 | `transaction_id` format aligned with VA/E-Wallet (TransactionCode + ULID)                                                                             |
| 2026-02-26 | Migrated to v2 response format (`response_code`/`response_message`), added error logging                                                              |
| 2026-02-26 | Refactored to single-step one-time payment; removed `register-transaction`; request uses `card_number`, `card_expiry`, `card_cvv`, `card_holder_name` |