Card (Money In)
Card Merchant API v2.0
Card Merchant API v2.0 enables merchants to accept card payments. This document describes endpoints, request/response parameters, and sample usage.
Note: This is a Money In operation — funds are transferred from the customer's card to your SingaPay Payment Gateway account.
API Overview
| API Version | v2.0 |
| Base Path | /api/v2.0/card |
| Authentication | Bearer Token (JWT, OAuth 2.0 client credentials) |
| Content-Type | application/json |
Authentication
Merchants must obtain a JWT access token before calling Card endpoints.
Obtaining Access Token
- Endpoint:
POST /api/v1.0/access-token/b2borPOST /api/v1.1/access-token/b2b - Headers:
Authorization: Basic {base64(client_id:client_secret)},X-PARTNER-ID: {api_key},Content-Type: application/x-www-form-urlencodedorapplication/json - Body:
grant_type=client_credentials
Using Access Token: Include Authorization: Bearer {access_token} in all Card API requests.
IP Whitelist: Merchant API routes require IP whitelisting. Ensure your server IP is registered for the merchant account.
Base URL & Paths
| Environment | Base URL |
|---|---|
| Production | https://{your-domain}/api/v2.0/card |
| Staging/Local | https://{your-domain}/api/v2.0/card |
Card Payment Flow
Transaction Status Lifecycle
- pendingAwaiting 3DS (includes internal pre-submission state).
- processingPayment submitted, awaiting final result.
- successPayment completed.
- failedPayment failed.
- cancelledVoided (not captured).
- refundedRefunded after capture.
Path Parameters
- •
{account_id}: Merchant Account ULID (e.g.01K5G4FZZ18DMK0M5QTR8Y9QY9) - •
{id}: Transaction ID (string, format:99+ ULID, e.g.9901JAB3CD4E5F6G7H8J9K0), from payment response
Available Operations
- • Payment (One-Time): Process a one-time card payment (full or installment) in a single request with amount, customer info, and card data.
- • Cancel Transaction: Void or refund a transaction depending on its current status.
- • Inquiry Status: Check the latest transaction status and optionally update the local record.
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:
{
"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
- • Single-Step Payment: Card payments are processed in a single API call that includes amount, customer info, and card data together.
- • 3DS Authentication: When the issuing bank requires 3DS, the response includes a
payment_url/html_formto render for customer authentication. - • Cancellation: Transactions can be voided (before capture) or refunded (after capture) using the Cancel endpoint. Both return
status: "success"; usecancel_typeto distinguish void vs refund. - • IP Whitelist: Merchant API routes require IP whitelisting. Ensure your server IP is registered for the merchant account.
- • Installments: Supports full payment and installment options (1, 3, 6, or 12 months) via the
installmentandinstallment_monthparameters.
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 aligned with processOneTime; removed register-transaction; request uses card_number, card_expiry, card_cvv, card_holder_name |

