Card Merchant API v2.0

API Overview

Authentication

Merchants must obtain a JWT access token before calling Card endpoints.

Obtaining Access Token

• Endpoint: POST /api/v1.0/access-token/b2b or POST /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-urlencoded or application/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

Transaction Status Lifecycle

1. pendingAwaiting 3DS (includes internal pre-submission state).
2. processingPayment submitted, awaiting final result.
3. successPayment completed.
4. failedPayment failed.
5. cancelledVoided (not captured).
6. 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

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

Appendix

Installment Type Reference

Installment Month Options

Transaction ID Format

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_form to render for customer authentication.
• • Cancellation: Transactions can be voided (before capture) or refunded (after capture) using the Cancel endpoint. Both return status: "success"; use cancel_type to 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 installment and installment_month parameters.

Changelog