Payment (One-Time) - Singapay PG

Information

Method	Path	Format	Authentication
POST	`/api/v2.0/card/{account_id}/payment`	json	OAuth 2.0 with Access Token

Processes one-time payment (full or installment) in a single request. Aligned with Payment Linking processOneTime request/response model.

Request Details

Headers Structure

Field	Value	Type	Mandatory	Description	Example
Authorization	Bearer {access_token}	Alphanumeric	Mandatory	Bearer token obtained from the access token endpoint.	Bearer eyJ0eXAiOiJKV1{…}
Content-Type	application/json	Alphabetic	Mandatory	Specifies JSON as the request body format.	application/json

Path Parameters

Parameter	Type	Mandatory	Description	Example
account_id	String	Required	Merchant Account ULID	01K5G4FZZ18DMK0M5QTR8Y9QY9

Body Structure

Parameter	Type	Mandatory	Validation	Description	Example
amount	Number	Required	min: 5000, max: 999999999	Transaction amount in IDR	100000
goods_name	String	Required	max: 255	Product or service name	Premium Subscription
customer_name	String	Required	max: 255	Customer billing name	John Doe
customer_email	String	Required	email, max: 255	Customer email address	john@example.com
customer_phone	String	Required	max: 50	Customer phone number	08123456789
customer_address	String	Required	max: 500	Billing address	Jl. Sudirman No. 1
customer_city	String	Required	max: 100	City	Jakarta
customer_state	String	Required	max: 100	State or Province	DKI Jakarta
customer_postal_code	String	Required	max: 20	Postal code	10210
customer_country	String	Required	size: 2	ISO country code (e.g. ID)	ID
card_number	String	Required	max: 20	Card number (no spaces)	4111111111111111
card_expiry	String	Required	size: 4	Expiry in YYMM format (e.g. 2512)	2512
card_cvv	String	Required	max: 4	CVV/CVC code	123
card_holder_name	String	Required	max: 45	Cardholder name	John Doe
card_holder_email	String	Required	email, max: 100	Cardholder email address	john@example.com
reference_no	String	Optional	max: 100	Merchant order reference. Auto-generated if omitted	ORD-20260225-001
description	String	Optional	max: 500	Transaction description	Monthly subscription fee
installment	Boolean	Optional	-	`true` for installment payment	false
installment_month	String	Optional	`3`, `6`, `12`	Installment period (default: 3 when installment is true)	3

Request Example

{
    "amount": 100000,
    "goods_name": "Premium Subscription",
    "customer_name": "John Doe",
    "customer_email": "john@example.com",
    "customer_phone": "08123456789",
    "customer_address": "Jl. Sudirman No. 1",
    "customer_city": "Jakarta",
    "customer_state": "DKI Jakarta",
    "customer_postal_code": "10210",
    "customer_country": "ID",
    "reference_no": "ORD-20260225-001",
    "card_number": "4111111111111111",
    "card_expiry": "2512",
    "card_cvv": "123",
    "card_holder_name": "John Doe",
    "card_holder_email": "john@example.com",
    "description": "Monthly subscription fee"
}

cURL Example:

curl -X POST "https://your-domain.com/api/v2.0/card/01K5G4FZZ18DMK0M5QTR8Y9QY9/payment" \
  -H "X-PARTNER-ID: {api_key}" \
  -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100000,
    "goods_name": "Premium Subscription",
    "customer_name": "John Doe",
    "customer_email": "john@example.com",
    "customer_phone": "08123456789",
    "customer_address": "Jl. Sudirman No. 1",
    "customer_city": "Jakarta",
    "customer_state": "DKI Jakarta",
    "customer_postal_code": "10210",
    "customer_country": "ID",
    "reference_no": "ORD-20260225-001",
    "card_number": "4111111111111111",
    "card_expiry": "2512",
    "card_cvv": "123",
    "card_holder_name": "John Doe",
    "card_holder_email": "john@example.com",
    "description": "Monthly subscription fee"
  }'

Response Details

Response Structure

Field	Type	Mandatory	Description	Example
response_code	String	Mandatory	Response code	SP000
response_message	String	Mandatory	Human-readable response message	Successfully
data	Object	Mandatory	Response data	-
> transaction_id	String	Mandatory	Transaction ID (format: 99 + ULID)	9901JAB3CD4E5F6G7H8J9K0M1N2
> reference_no	String	Mandatory	Merchant order reference number	ORD-20260225-001
> status	String	Mandatory	Transaction status	processing
> action	String	Mandatory	`complete` (immediate) or `redirect` (3DS required)	complete
> immediate_success	Boolean	Conditional	`true` when payment succeeded immediately without 3DS	true
> provider_transaction_id	String	Conditional	Transaction reference (present on immediate success)	IONPAYTEST01202602251234567890
> provider_auth_no	String	Conditional	Authorization number (present on immediate success)	123456
> card_masked	String	Conditional	Masked card number (present on immediate success)	411111******1111
> issuing_bank	String	Conditional	Issuing bank name (present on immediate success)	CIMB
> acquiring_bank	String	Conditional	Acquiring bank name (present on immediate success)	CIMB
> result_code	String	Conditional	Result code (present on immediate success)	0000
> requires_3ds	Boolean	Conditional	`true` when 3DS authentication is required	true
> payment_url	String	Conditional	HTML content for 3DS redirect (when `requires_3ds` is true)	<html>…</html>
> html_form	String	Conditional	HTML form for 3DS redirect (when `requires_3ds` is true)	<html>…</html>

Response Example — Immediate Success (HTTP 200)

When 3DS is not required, the payment completes immediately:

Success: Payment completed immediately.

{
    "response_code": "SP000",
    "response_message": "Successfully",
    "data": {
        "transaction_id": "9901JAB3CD4E5F6G7H8J9K0M1N2",
        "reference_no": "ORD-20260225-001",
        "status": "processing",
        "action": "complete",
        "immediate_success": true,
        "provider_transaction_id": "IONPAYTEST01202602251234567890",
        "provider_auth_no": "123456",
        "card_masked": "411111******1111",
        "issuing_bank": "CIMB",
        "acquiring_bank": "CIMB",
        "result_code": "0000"
    }
}

Response Example — 3DS Required (HTTP 200)

When the issuing bank requires 3DS authentication:

Success: 3DS redirect required. Render the payment_url or html_form for the customer.

{
    "response_code": "SP000",
    "response_message": "Successfully",
    "data": {
        "transaction_id": "9901JAB3CD4E5F6G7H8J9K0M1N2",
        "reference_no": "ORD-20260225-001",
        "status": "pending",
        "action": "redirect",
        "requires_3ds": true,
        "payment_url": "<html>...</html>",
        "html_form": "<html>...</html>",
        "provider_transaction_id": "IONPAYTEST01202602251234567890"
    }
}

Error Response (HTTP 400)

Error: Payment declined.

{
    "response_code": "SP001",
    "response_message": "Payment declined by issuer",
    "data": {
        "transaction_id": "9901JAB3CD4E5F6G7H8J9K0M1N2",
        "reference_no": "ORD-20260225-001",
        "status": "failed"
    }
}

3DS Handling

When the response includes action: "redirect" and requires_3ds: true:

Render the form: Insert the payment_url or html_form HTML content into a hidden form element or iframe on your page.
Auto-submit: The form will auto-submit and redirect the customer to the bank’s 3DS authentication page.
Completion: After the customer completes 3DS authentication, the bank’s 3DS page will redirect back to complete the flow, and your webhook may be called on completion.
Verify status: Use the Inquiry Status endpoint to confirm the final payment result.

3DS handling: Render payment_url or html_form in a hidden form and auto-submit, or display in an iframe. The bank’s 3DS page will redirect back to complete the flow, and your webhook may be called on completion.

Installment Reference

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

Important Notes

Single-Step Payment: This endpoint handles the full payment flow in one request — no separate registration step is needed.
Required Customer Data: Customer email, phone, address, city, state, postal code, country, and cardholder email are all required.
Card Data: Card number, expiry, CVV, and cardholder name are all required. The card number must be sent without spaces or dashes.
Expiry Format: The expiry date uses YYMM format (e.g., 2512 for December 2025), not the more common MMYY format.
Action Field: Check the action field to determine if the payment completed immediately (complete) or requires 3DS redirect (redirect).
Final Status: After payment submission, use Inquiry Status or wait for a webhook to confirm the final outcome (success or failed).

On this page