Straitsx

Skill based on StraitsX Card Issuing API (v1-CARDS), generated 2026-02-25 from docs.straitsx.com.

StraitsX Card Issuing lets you launch and manage a payment card program: create users and cards, activate, enroll 3DS, set PIN, and handle authorizations and webhooks. CMS is REST (Bearer token); RHA and webhook are endpoints you implement and StraitsX calls.

Core References

Features

Card Management (CMS)

Remote Host & Webhooks

Best practices

API Reference (by endpoint)

Request/response and curl examples for CMS and RHA/Webhook are in the references below. Call patterns (Node SDK / curl): core-usage-patterns.

More detail: Official API Reference.

External links

• Card Issuing API docs
• API Reference

Generation Info

• Source: https://docs.straitsx.com/v1-CARDS/docs/introduction
• Cache: .bonfire/cache/straitsx
• Fetched via: fetch-docs.js (28 pages, 0 failed)
• Generated: 2026-02-25

Rejection reasons and rate limits

Transaction rejection_reason (webhook)

When webhook event_type=transaction and transaction_status=rejected, use rejection_reason for classification. Key codes:

• Balance/limits: INSUFFICIENT_BALANCE, INSUFFICIENT_SPENDABLE_BALANCE, CARD_LIMIT_EXCEEDED, VIAA_LIMIT_EXCEEDED
• Card/contract: ACCOUNT_NOT_FOUND, CARD_IS_NOT_PRESENT, CARD_TOKEN_NOT_PRESENT, CONTRACT_NOT_PRESENT, CARD_IS_INACTIVE, CARD_IS_LOST, CARD_IS_STOLEN, CARD_IS_SUSPENDED, CARD_IS_BLOCKED_BY_FRAUD, CARD_IS_PERM_BLOCK, CARD_IS_INVALID, CARD_TOKEN_SUSPENDED, CARD_TOKEN_INACTIVE, CARD_TOKEN_DEACTIVATED, CARD_TOKEN_HAS_EXPIRED
• Restrictions: CARD_RESTRICTIONS, TRANSACTION_NOT_PERMITTED, FRAUD_NOT_PERMITTED_TO_TERMINAL
• Idempotency/duplicates: DUPLICATE_TRANSACTION, ORIGINAL_TRANSACTION_NOT_FOUND
• System: CBS_IS_NOT_AVAILABLE, ERRORS_IN_SOFTWARE
• Validation: CVV2_VALIDATION_FAILED, CAVV_VALIDATION_FAILED, TRACK_2_VALIDATION_FAILED, CRYPTOGRAM_VALIDATION_FAILED, PIN_VALIDATION_FAILED, TOO_MANY_CONSECUTIVE_PIN_FAILURES, PIN_NOT_CONFIGURED
• Other: UNKNOWN

Use these to map to user-facing messages or internal handling. When card not found, acquirer_currency, card_opaque_id, cbs_transaction_id, currency may be "" and amounts "0.00".

CMS rate limits

• 429 response: code: "XFC429001", message: "Too many requests". Implement retry with exponential backoff and jitter.
• Production: Default 1000 RPM; Get Card Transaction List / Get Transaction Detail 500 RPM (Transaction Detail has 2500 burst). Create Unassigned Card Batch Transfer: 1 per 30 minutes.
• Sandbox: Default 500 RPM; Create Unassigned Card Batch Transfer: 1 per 15 minutes.

<!-- Source references:

• .bonfire/cache/straitsx/transaction-rejection-reasons.md, rate-limit.md
• https://docs.straitsx.com/v1-CARDS/docs/transaction-rejection-reasons
• https://docs.straitsx.com/v1-CARDS/docs/rate-limit

-->

Authentication (CMS)

CMS enforces HTTP Bearer Token in the Authorization header. StraitsX provides client id and secret via email; use them to obtain an access token before calling any CMS endpoint.

Token endpoint (Sandbox and Production)

POST https://sso.straitsx.com/auth/realms/xfers-internal/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
client_id=<your_client_id>
client_secret=<your_client_secret>
scope=openid

Example (curl)

curl --request POST \
  --url https://sso.straitsx.com/auth/realms/xfers-internal/protocol/openid-connect/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data client_id=<your_client_id> \
  --data client_secret=<your_client_secret> \
  --data scope=openid

Use the returned access token as Authorization: Bearer <access_token> on all CMS requests. Do not reuse the same credentials for RHA or webhook (RHA uses a separate API key; webhook uses a signing secret).

<!-- Source references:

• https://docs.straitsx.com/v1-CARDS/docs/authentication-method

-->

Error responses

API errors return JSON with code and message. In sandbox, a debug field may be included for support.

Response format

{
  "code": "string",
  "message": "string"
}

Sandbox only:

{
  "code": "string",
  "message": "string",
  "debug": "string"
}

Usage

• Use code for programmatic handling (e.g. retry on 429, show user-friendly text for 400).
• Common patterns: XFC400* = 400 Bad Request, XFC404* = 404 Not Found, XFC401001 = Unauthorized, XFC403001 = Access denied, XFC429001 = Too many requests, XFC500001 = Internal server error.
• Insufficient funds: XFC400039. Card inactive: XFC400007. Invalid PIN / max attempts: XFC400040, XFC400042. Idempotency: XFC400065 = Duplicate idempotency key.

Key codes (subset)

Full list is in the docs; always handle 4xx/5xx and map code for logging and user feedback.

<!-- Source references:

• https://docs.straitsx.com/v1-CARDS/docs/errors

-->

Getting started flow

Prerequisites (from StraitsX)

• Authentication method (client id/secret for token).
• Issuer group, issuer plan, and card product. Use issuing_plan_opaque_id in path for all CMS requests; use card_product_opaque_id when creating cards.

Typical flow

1. Create user — POST .../issuing_plans/{issuing_plan_opaque_id}/users. Response gives user.opaque_id → use as customer_opaque_id. 2. Create card — POST .../users/{customer_opaque_id}/cards with card product, cardholder name parts, contact, funding_source (e.g. remote-host), address. Response gives card.opaque_id (contract_opaque_id), latest_card_number.opaque_id, truncated number, expiry. 3. Activate card — After eligibility (e.g. one day for physical, or immediately for instant issuance), POST .../cards/{contract_opaque_id}/activate with truncated_card_number and expiry_date (MM/YY). 4. Enroll 3DS (recommended for e-commerce) — Enroll 3DS endpoint with authentication_method and destination (e.g. SMS_OTP). 5. Set PIN — Use PIN setup iframe API. 6. Expose RHA + webhook — Implement remote host authorization endpoint and webhook endpoint; share URL and (for webhook) signing secret with StraitsX. Then test in sandbox.

Later: update card status, close card, set spend limit, update card configuration via respective CMS APIs.

<!-- Source references:

• https://docs.straitsx.com/v1-CARDS/docs/getting-started

-->

StraitsX Card Issuing API overview

StraitsX Card Issuing APIs let you launch and manage a payment card program. The platform is PCI-DSS and PCI-3DS regulated.

Two main APIs

CMS hosts

RHA and webhook URLs are your endpoints; StraitsX calls you. Use a dedicated API key for RHA (do not reuse webhook signing secret).

When to use

• Integrating card issuance: Use CMS (create user, create card, activate, 3DS, PIN, update status/limits). Use same Bearer token from SSO for all CMS requests.
• Handling live transactions: Implement RHA (authorization endpoint) and webhook (notifications). Verify webhook with X-COP-Signature-256 and respond within 10s to avoid retries.

<!-- Source references:

• https://docs.straitsx.com/v1-CARDS/docs/introduction
• https://docs.straitsx.com/v1-CARDS/docs/card-management-system-cms
• https://docs.straitsx.com/v1-CARDS/docs/remote-host-authorization-rha

-->

Pagination and sorting

List endpoints support page[size], page[number], and sort query parameters.

Pagination

• page[size]: Number of items per page. Default: 10.
• page[number]: Page index. Default: 1.

Example — third page, 10 per page:

?page[size]=10&page[number]=3

Sorting

• sort: Order by field. Prefix + = ascending, - = descending. + must be URL-encoded as %2B in query strings.

Example — ascending by creation date:

?sort=%2BcreatedAt

Descending:

?sort=-createdAt

Usage

• Use consistent page[size] to avoid surprises; respect 429 (rate limit) when paging quickly.
• Combine with filters when the API supports them to narrow result sets before pagination.

<!-- Source references:

• https://docs.straitsx.com/v1-CARDS/docs/pagination-sorting

-->

Usage patterns (Node / Shell)

You can call the StraitsX Card Issuing CMS API in two common ways: Node.js SDK (via Readme API install) and Shell (curl). Both use the same REST endpoints and Bearer auth; choose based on app integration vs. ad-hoc or script use.

Base URL and auth

• Staging: https://merchant.cop-staging.straitsx.com
• Production: Use the URL provided by StraitsX (typically https://merchant.*.straitsx.com)
• Path prefix: /api/v1/ (e.g. Create Issuer Plan is /api/v1/issuing_plans; most other CMS paths are /api/v1/issuing_plans/{issuing_plan_opaque_id}/...)
• Auth: All CMS requests must send Authorization: Bearer <TOKEN> in the header. Obtain TOKEN via SSO client_credentials; see core-authentication.

---

Option 1: Node.js SDK (api install)

Install the official SDK via Readme API; then call @api/straitsx in code. Method names map to the API (e.g. createIssuerPlan → POST Create Issuer Plan).

Install

npx api install "@straitsx/v1-CARDS#3dwuze2vmets10z5"

This adds the @api/straitsx dependency and types; no need to build HTTP requests by hand.

Auth and example (Create Issuer Plan)

import straitsx from '@api/straitsx';

straitsx.auth('TOKEN');

straitsx
  .createIssuerPlan({
    is_start_of_week_sunday: true,
    permission_model: 'BUSINESS_PREPAID',
  })
  .then(({ data }) => console.log(data))
  .catch((err) => console.error(err));

• Other CMS calls: call straitsx.auth('TOKEN') once, then the corresponding method (e.g. createUser, createCard, activateCard). Method arguments match the API body/query.
• Responses are typically { data }; errors via Promise rejection / catch.

---

Option 2: Shell (curl)

Call REST endpoints directly for scripts, CI, or manual checks. Build URL, headers, and body yourself.

Create Issuer Plan example

curl --request POST \
     --url https://merchant.cop-staging.straitsx.com/api/v1/issuing_plans \
     --header 'accept: application/json' \
     --header 'authorization: Bearer TOKEN' \
     --header 'content-type: application/json' \
     --data '
{
  "is_start_of_week_sunday": true,
  "permission_model": "BUSINESS_PREPAID"
}
'

• Replace TOKEN with the access token from SSO.
• In production, replace merchant.cop-staging.straitsx.com with your Merchant API host.

Other CMS endpoints (generic)

• POST: --request POST --url <BASE_URL>/api/v1/... --header 'authorization: Bearer TOKEN' --header 'content-type: application/json' --data '<JSON>'
• GET: --request GET --url '<BASE_URL>/api/v1/...?query=params' --header 'authorization: Bearer TOKEN'
• PUT/DELETE: Same as POST with the appropriate --request and optional --data. Paths and body are in this skill’s feature references (e.g. features-cms-issuer-plan, features-cms-lifecycle) or the official API Reference.

---

Summary

Request and response bodies are the same for both; you can align curl examples in the references with SDK calls.

<!-- Source references:

• https://docs.straitsx.com/v1-CARDS/reference/create-issuer-plan

-->

3DS API

Base path: /api/v1/issuing_plans/{issuing_plan_opaque_id}/users/{customer_opaque_id}/cards/{card_opaque_id}/card_numbers/{card_number_opaque_id}. All requests require Authorization: Bearer <token>. Enroll card numbers for 3DS so that transactions requiring 3DS authentication can be completed.

Enroll Card Number for 3DS

• Path: POST .../3ds_enrollment
• Body (required):
• authentication_method (string) — SMS_OTP, OOB, EMAIL_OTP.
• destination (string) — Required if authentication_method is SMS_OTP (phone number). Omit for OOB (uses card-creation phone).
• Response 200: authentication_method, status.

Get Card Number 3DS Detail

• Path: GET .../3ds_enrollment (or 3DS detail subresource).
• Response 200: 3DS enrollment status and method for the card number.

Update Card Number 3DS Auth Method

• Path: PUT .../3ds_enrollment (or update subresource). Body: new authentication_method, optional destination.

Unenroll Card Number from 3DS

• Path: DELETE .../3ds_enrollment. Removes 3DS enrollment for the card number.

<!-- Source references:

• https://docs.straitsx.com/v1-CARDS/reference/enroll-3ds
• https://docs.straitsx.com/v1-CARDS/reference/get-3ds-detail
• https://docs.straitsx.com/v1-CARDS/reference/update-3ds
• https://docs.straitsx.com/v1-CARDS/reference/unenroll-3ds

-->

Accounting API

Base path: /api/v1/issuing_plans/{issuing_plan_opaque_id}. All requests require Authorization: Bearer <token>.

Get Card Spending

• Path: GET .../bulk/spendings
• Query (required): card_opaque_id[] (array of card opaque IDs), velocity_window (DAY | WEEK | MONTH | YEAR | LIFETIME).
• Response 200: data[] with card_opaque_id, velocity_window, amount, currency (ISO 4217). Order of card_opaque_id in query is non-deterministic in response.

Get Settlement Account Balance

• Path: GET endpoint for settlement account balance (see reference).
• Response 200: Settlement balance (currency, amount).

Get Spendable Account Balance

• Path: GET endpoint for spendable account balance.
• Response 200: Spendable balance available for funding/issuing.

Get VISA Currency Exchange Rates

• Path: GET endpoint for VISA FX rates (see reference).
• Response 200: Exchange rates used for currency conversion (e.g. for international transactions or USD accounts).

<!-- Source references:

• https://docs.straitsx.com/v1-CARDS/reference/get-card-spending
• https://docs.straitsx.com/v1-CARDS/reference/get-settlement-account-balance
• https://docs.straitsx.com/v1-CARDS/reference/get-spendable-account-balance
• https://docs.straitsx.com/v1-CARDS/reference/get-visa-currency-exchange-rates

-->

Unassigned Card Batch Transfer API

For requesting batches of unassigned (instant-issuance) cards. Base path: /api/v1/issuing_plans/{issuing_plan_opaque_id}/card_products/{card_product_opaque_id}. All requests require Authorization: Bearer <token>. Batches are sent each Tuesday 4pm SGT.

Create Unassigned Card Batch Transfer

• Path: POST .../unassigned_card_batch_transfers
• Body (required):
• requested_quantity (integer) — Number of unassigned cards (1–1000). Must not exceed merchant daily limit (e.g. 1000/day).
• region (string) — Alpha-2 region code for embossing routing (e.g. HK, SG, ID).
• address (object) — Delivery address for the batch (no special characters <, >, &, etc.; Latin symbols not allowed).
• Response 200: opaque_id, requested_quantity, embossing_file_name, region. 429 if too many requests.

curl --request POST \
  --url "https://merchant.cop-staging.straitsx.com/api/v1/issuing_plans/{issuing_plan_opaque_id}/card_products/{card_product_opaque_id}/unassigned_card_batch_transfers" \
  --header 'accept: application/json' \
  --header 'authorization: Bearer TOKEN' \
  --header 'content-type: application/json' \
  --data '{"requested_quantity": 10, "region": "SG", "address": {...}}'

Get All Batch Transfers

• Path: GET .../unassigned_card_batch_transfers (or issuer-level list endpoint). Query: pagination, sort.
• Response 200: List of batch transfers with status and details.

Get Single Batch Transfer Details

• Path: GET .../unassigned_card_batch_transfers/{batch_opaque_id} (or similar).
• Response 200: Single batch transfer details (opaque_id, requested_quantity, status, embossing_file_name, region, etc.).

<!-- Source references:

• https://docs.straitsx.com/v1-CARDS/reference/create-unassigned-card-batch-transfer
• https://docs.straitsx.com/v1-CARDS/reference/get-all-unassigned-card-batch-transfer
• https://docs.straitsx.com/v1-CARDS/reference/get-unassigned-card-batch-transfer-details

-->

Card Product API

Base path: /api/v1/issuing_plans/{issuing_plan_opaque_id}. All requests require Authorization: Bearer <token>.

Link Issuer Plan with Card Product

• Path: POST .../card_products/{card_product_opaque_id}/link
• Purpose: After linking, the card product can be used for card creation.
• Response 200: Success.

Get Card Product List

• Path: GET .../card_products
• Response 200: card_products[] — each with opaque_id, name, card_type. Empty if the issuer plan was created but no card products are linked yet.

curl --request GET \
  --url "https://merchant.cop-staging.straitsx.com/api/v1/issuing_plans/{issuing_plan_opaque_id}/card_products" \
  --header 'accept: application/json' \
  --header 'authorization: Bearer TOKEN'

Create Card Product

• Path: POST .../card_products (or as per StraitsX setup; confirm path in dashboard/docs).
• Body: Product definition (name, card type, etc.). See official reference for full params.

Get Merchant BINs List

• Path: GET .../card_products/.../bins or similar (see API reference). Returns BINs available for the merchant.

Card Art List

• Path: GET endpoint for card arts (see API reference). Returns available card art opaque_ids for use in Create Card (card_art_opaque_id).

<!-- Source references:

• https://docs.straitsx.com/v1-CARDS/reference/link-issuer-plan-with-card-product
• https://docs.straitsx.com/v1-CARDS/reference/get-card-product-list
• https://docs.straitsx.com/v1-CARDS/reference/create-card-product
• https://docs.straitsx.com/v1-CARDS/reference/get-merchant-bins-list
• https://docs.straitsx.com/v1-CARDS/reference/card-arts

-->

Card API (operations after create/activate)

Base path: /api/v1/issuing_plans/{issuing_plan_opaque_id}/users/{customer_opaque_id}/cards/{contract_opaque_id}. All requests require Authorization: Bearer <token>.

Get Card Detail

• Path: GET .../cards/{contract_opaque_id} (under user path).
• Response 200: Card object (opaque_id, truncated_card_number, status, card_type, latest_card_number, etc.).

Update Card Status

• Path: PUT .../cards/{contract_opaque_id} (or status subpath; see reference). Body typically includes status (e.g. SUSPENDED, ACTIVE). Some statuses (e.g. PERM_BLOCK) are permanent.

Close Card

• Path: DELETE .../cards/{contract_opaque_id}. Permanently closes the card.

Get Card Balance

• Path: GET .../cards/{contract_opaque_id}/balance.
• Response 200: Balance information (e.g. available, ledger) in account currency.

Get Card Configuration

• Path: GET .../cards/{contract_opaque_id}/configuration.
• Response 200: Card configuration (e.g. limits, settings).

Update Card Configuration

• Path: PUT .../cards/{contract_opaque_id}/configuration. Body: configuration fields to update.

Request Card for Printing

• Path: POST .../cards/{contract_opaque_id}/request_printing (or similar). Triggers physical card production.

Update Card Printing Delivery Address

• Path: PUT endpoint for delivery address. Body: address fields.

Update Card Phone Number

• Path: PUT endpoint for card phone number. Body: contact number.

Card Token

• Get Token List: GET .../cards/{contract_opaque_id}/tokens (or token subresource). Returns tokens (e.g. Apple Pay, Google Pay) for the card.
• Update Card Token Status: PUT to suspend/activate/deactivate a token.
• Update Card Art: PUT to change card art for a token.
• Call Center Activation: PUT for call-center activation flow.

Reissue Card

• Path: PUT .../cards/{contract_opaque_id}/reissue (or similar). Issues a replacement card (e.g. lost/stolen); may require reason/address.

<!-- Source references:

• https://docs.straitsx.com/v1-CARDS/reference/get-card-detail
• https://docs.straitsx.com/v1-CARDS/reference/update-card-status
• https://docs.straitsx.com/v1-CARDS/reference/close-card
• https://docs.straitsx.com/v1-CARDS/reference/get-card-balance
• https://docs.straitsx.com/v1-CARDS/reference/get-card-configuration
• https://docs.straitsx.com/v1-CARDS/reference/update-card-configuration
• https://docs.straitsx.com/v1-CARDS/reference/request-card-for-printing
• https://docs.straitsx.com/v1-CARDS/reference/update-card-printing-delivery-address
• https://docs.straitsx.com/v1-CARDS/reference/update-card-phone-number-1
• https://docs.straitsx.com/v1-CARDS/reference/get-token-list
• https://docs.straitsx.com/v1-CARDS/reference/update-card-token-status
• https://docs.straitsx.com/v1-CARDS/reference/update-card-art
• https://docs.straitsx.com/v1-CARDS/reference/reissue-card

-->

Iframe API (URLs for embedding)

All paths under /api/v1/issuing_plans/{issuing_plan_opaque_id}/users/{customer_opaque_id}/cards/{contract_opaque_id}. All requests require Authorization: Bearer <token>. These endpoints return iframe URLs to embed in your web or mobile app. You must provide a template for the PIN flow appearance before using PIN iframes.

PIN Setup Iframe URL

• Path: GET .../iframe/pin_setup
• Response 200: URL to embed for PIN setup.

PIN Reset Iframe URL

• Path: GET .../iframe/pin_reset (or similar).
• Response 200: URL for PIN reset flow.

PIN Change Iframe URL

• Path: GET .../iframe/pin_change (or similar).
• Response 200: URL for PIN change flow.

Card Iframe URL

• Path: GET endpoint for card iframe (display card details in iframe).
• Response 200: Embeddable card iframe URL.

CVV Iframe — Card Preview

• Path: GET endpoint for CVV iframe (preview). Use for showing CVV in a secure iframe.
• Response 200: CVV preview iframe URL.

CVV Iframe — Card Details

• Path: GET endpoint for CVV iframe (full details). PCI DSS considerations apply; see docs.
• Response 200: CVV details iframe URL.

<!-- Source references:

• https://docs.straitsx.com/v1-CARDS/reference/pin-setup-iframe
• https://docs.straitsx.com/v1-CARDS/reference/pin-reset-iframe
• https://docs.straitsx.com/v1-CARDS/reference/pin-change-iframe
• https://docs.straitsx.com/v1-CARDS/reference/card-iframe
• https://docs.straitsx.com/v1-CARDS/reference/cvv-iframe-preview
• https://docs.straitsx.com/v1-CARDS/reference/cvv-iframe

-->

Issuer Plan API

Base URL path prefix: /api/v1. All requests require Authorization: Bearer <token>. Staging: https://merchant.cop-staging.straitsx.com.

Create Issuer Plan

• Method/Path: POST /api/v1/issuing_plans
• Body (required):
• is_start_of_week_sunday (boolean, required) — Week start: true = Sunday, false = Monday; used for weekly spend limit calculation.
• permission_model (string, required) — One of: BUSINESS_PREPAID, CONSUMER_PREPAID, MODEL_A, MODEL_B, MODEL_C, MODEL_D. Remote Host clients use BUSINESS_PREPAID.
• name (string, optional) — Issuer plan name.
• Response 200: is_start_of_week_sunday, name, opaque_id, permission_model

curl --request POST \
  --url https://merchant.cop-staging.straitsx.com/api/v1/issuing_plans \
  --header 'accept: application/json' \
  --header 'authorization: Bearer TOKEN' \
  --header 'content-type: application/json' \
  --data '{"is_start_of_week_sunday": true, "permission_model": "BUSINESS_PREPAID"}'

Update Issuer Plan

• Method/Path: PUT /api/v1/issuing_plans/{issuing_plan_opaque_id}
• Path params: issuing_plan_opaque_id (required)
• Body (all optional): is_start_of_week_sunday, name, permission_model (same as above)
• Response 200: Same shape as Create

curl --request PUT \
  --url "https://merchant.cop-staging.straitsx.com/api/v1/issuing_plans/{issuing_plan_opaque_id}" \
  --header 'accept: application/json' \
  --header 'authorization: Bearer TOKEN' \
  --header 'content-type: application/json' \
  --data '{"name": "new name"}'

Get Issuer Plan Card List

• Method/Path: GET /api/v1/issuing_plans/{issuing_plan_opaque_id}/cards
• Path params: issuing_plan_opaque_id (required)
• Query (optional): page[size] (default 10), page[number] (default 1), sort (-createdAt | +createdAt), status (ACTIVE, INACTIVE, BLOCKED_BY_FRAUD, etc.), show_encrypted_card_number, show_encrypted_cvv (boolean), has_sku (boolean), card_product_opaque_id
• Response 200: page, total_data, total_pages, data[] (each with opaque_id, truncated_card_number, status, card_type, latest_card_number.expiry_date, etc.)

curl --request GET \
  --url "https://merchant.cop-staging.straitsx.com/api/v1/issuing_plans/{issuing_plan_opaque_id}/cards?page[size]=10&page[number]=1&sort=-createdAt" \
  --header 'accept: application/json' \
  --header 'authorization: Bearer TOKEN'

<!-- Source references:

• https://docs.straitsx.com/v1-CARDS/reference/create-issuer-plan
• https://docs.straitsx.com/v1-CARDS/reference/update-issuer-plan
• https://docs.straitsx.com/v1-CARDS/reference/get-issuer-plan-card-list

-->

CMS Lifecycle APIs

Base path: /api/v1/issuing_plans/{issuing_plan_opaque_id}. All requests require Authorization: Bearer <token>. Staging: https://merchant.cop-staging.straitsx.com.

Create User

• Path: POST .../users
• Body: customer_name (string, required). Remote Host also requires: kyc_full_name, date_of_birth (YYYY/MM/DD), nationality (alpha-2). Optional: email, kyc_proof (object).
• Response 200: user.opaque_id — this is customer_opaque_id for all subsequent calls.

curl --request POST \
  --url "https://merchant.cop-staging.straitsx.com/api/v1/issuing_plans/{issuing_plan_opaque_id}/users" \
  --header 'accept: application/json' \
  --header 'authorization: Bearer TOKEN' \
  --header 'content-type: application/json' \
  --data '{"customer_name": "John Doe", "kyc_full_name": "John Doe", "date_of_birth": "1990/01/01", "nationality": "SG"}'

Create Card

• Path: POST .../users/{customer_opaque_id}/cards
• Body (required): card_product_opaque_id, cardholder_name, cardholder_first_name, cardholder_surname, contact_number, funding_source (e.g. remote-host), address (country, region, city, street, house, postal_code).
• Body (optional): cardholder_second_name, card_is_primary, account_currency (SGD | USD), card_art_opaque_id, stock_keeping_code (for physical pool).
• Query (optional): show_encrypted_card_number, show_encrypted_cvv (boolean; PCI DSS).
• Response 200: card.opaque_id (contract_opaque_id), truncated_card_number, card_type, card_status (INACTIVE), latest_card_number.opaque_id, latest_card_number.expiry_date (MM/YY). For instant issuance: remaining_card_in_pool.

Activate Card

• Path: POST .../users/{customer_opaque_id}/cards/{contract_opaque_id}/activate
• Body (required): truncated_card_number, expiry_date (MM/YY; must match Create Card response).
• Response 200: card.status becomes ACTIVE.

Other CMS endpoints (3DS, PIN iframe, Update Card Status, Close Card, Spend Limit, Card Configuration, Request Card for Printing, etc.) are in the corresponding references: features-cms-user, features-cms-spend-limit, features-cms-card; call patterns in core-usage-patterns.

<!-- Source references:

• https://docs.straitsx.com/v1-CARDS/reference/create-user
• https://docs.straitsx.com/v1-CARDS/reference/create-card
• https://docs.straitsx.com/v1-CARDS/reference/activate-card

-->

OOB (Out-of-Band Authentication) API

Used to complete out-of-band authentication (e.g. after user completes 3DS challenge). You receive transaction_id and authentication_id from the oob_notification webhook; call this API to submit the result.

Obtain OOB

• Path: POST /api/v1/issuing_plans/{issuing_plan_opaque_id}/oob/obtain
• Body (required):
• transaction_id (string) — From webhook.
• authentication_id (string) — From webhook.
• authentication_result (string) — OK, FAILED, FAILED_ATTEMPT, NOT_FINISHED, ERROR.
• authentication_method (string) — BIOMETRICS, LOGIN, OTHER.
• Body (optional): result_reason, entered_password.
• Response 200: Success (empty or confirmation object).

curl --request POST \
  --url "https://merchant.cop-staging.straitsx.com/api/v1/issuing_plans/{issuing_plan_opaque_id}/oob/obtain" \
  --header 'accept: application/json' \
  --header 'authorization: Bearer TOKEN' \
  --header 'content-type: application/json' \
  --data '{"transaction_id":"...","authentication_id":"...","authentication_result":"OK","authentication_method":"BIOMETRICS"}'

<!-- Source references:

• https://docs.straitsx.com/v1-CARDS/reference/obtain-oob

-->

Pin API (server-side)

Base path: /api/v1/issuing_plans/{issuing_plan_opaque_id}/users/{customer_opaque_id}/cards/{contract_opaque_id}. All requests require Authorization: Bearer <token>. For PCI DSS, PIN setup with encrypted PIN typically requires certification; otherwise use the iframe URLs (see features-cms-iframe).

PIN Setup

• Path: POST .../pin/setup
• Body: Encrypted PIN value (format as per StraitsX/PCI DSS docs).
• Response 200: Success. Use only if PCI DSS certified; else use PIN Setup Iframe.

PIN Reset

• Path: PUT .../pin/reset (or similar). Body: parameters required for reset (e.g. new encrypted PIN, verification).
• Response 200: Success.

PIN Change

• Path: PUT .../pin/change. Body: current and new PIN (encrypted as required).
• Response 200: Success.

Reset PIN Retry Counter

• Path: PUT endpoint for resetting the PIN retry counter (e.g. after too many failed attempts). Unlocks PIN attempts for the card.
• Response 200: Success.

<!-- Source references:

• https://docs.straitsx.com/v1-CARDS/reference/pin-setup
• https://docs.straitsx.com/v1-CARDS/reference/pin-reset
• https://docs.straitsx.com/v1-CARDS/reference/pin-change
• https://docs.straitsx.com/v1-CARDS/reference/reset-pin-retry-counter

-->

Spend Limit API

Base path: /api/v1/issuing_plans/{issuing_plan_opaque_id}/users/{customer_opaque_id}/cards/{contract_opaque_id}/limit. All requests require Authorization: Bearer <token>.

• velocity_window: DAY | WEEK | MONTH | YEAR | LIFETIME | TRANSACTION (per-transaction limit). Week/month start at GMT+7 00:00; week start day is from Issuer Plan is_start_of_week_sunday.
• transaction_type: PURCHASE | ATM_CASH_WITHDRAWAL. ATM supports only DAY and MONTH velocity and has max limits (see docs).

Create Card Spending Limit

• Path: POST .../limit
• Body (required): amount_limit (number), currency_code (ISO 4217, e.g. SGD, USD), velocity_window, transaction_type (optional, default PURCHASE)
• Response 200: amount_limit, currency_code, velocity_window, transaction_type, active, etc.

Get Card Spending Limit

• Path: GET .../limit
• Response 200: limits[] — each with transaction_type, amount_limit, velocity_window, currency_code, active

curl --request GET \
  --url "https://merchant.cop-staging.straitsx.com/api/v1/issuing_plans/{issuing_plan_opaque_id}/users/{customer_opaque_id}/cards/{contract_opaque_id}/limit" \
  --header 'accept: application/json' \
  --header 'authorization: Bearer TOKEN'

Update Card Spending Limit

• Path: PUT .../limit
• Body (required): amount_limit, currency_code, velocity_window, transaction_type (same as above)
• Response 200: Updated limit object

Delete Card Spending Limit

• Path: DELETE .../limit
• Body (required): velocity_window, transaction_type (identifies which limit to remove)
• Response 200: Success. Errors if no such limit exists.

<!-- Source references:

• https://docs.straitsx.com/v1-CARDS/reference/create-spend-limit
• https://docs.straitsx.com/v1-CARDS/reference/get-spend-limit
• https://docs.straitsx.com/v1-CARDS/reference/update-spend-limit
• https://docs.straitsx.com/v1-CARDS/reference/delete-spend-limit

-->

Transaction API (CMS)

All paths under /api/v1/issuing_plans/{issuing_plan_opaque_id}. All requests require Authorization: Bearer <token>. Amounts: account_amount/account_currency = card currency; amount/currency = issuer currency (typically SGD); original_amount/original_currency = acquirer.

Get Card Transaction List

• Path: GET .../users/{customer_opaque_id}/cards/{contract_opaque_id}/transactions
• Query: page[size], page[number], sort (-createdAt | +createdAt), transaction_type, show_final_transactions_only (see docs), date filters as per reference.
• Response 200: Paginated list of transactions for the card.

Get Card Transaction Detail

• Path: GET .../users/{customer_opaque_id}/cards/{contract_opaque_id}/transactions/{transaction_id} (or similar).
• Response 200: Single transaction details.

Get Issuer Transaction List

• Path: GET .../transactions (issuer-level). Query: pagination, sort, filters.
• Response 200: Paginated list across the issuer plan.

Get Transaction Detail

• Path: GET endpoint for a single transaction by ID (issuer-level).
• Response 200: Transaction object (amount, currency, type, status, merchant, etc.).

Get Total Transaction Amount

• Path: GET endpoint for total transaction amount (e.g. by card or issuer, with filters).
• Query: Often supports date range, transaction_type, etc.
• Response 200: Aggregated amount(s).

<!-- Source references:

• https://docs.straitsx.com/v1-CARDS/reference/get-card-transaction-list
• https://docs.straitsx.com/v1-CARDS/reference/get-card-transaction-detail
• https://docs.straitsx.com/v1-CARDS/reference/get-issuer-transaction-list
• https://docs.straitsx.com/v1-CARDS/reference/get-transaction-detail
• https://docs.straitsx.com/v1-CARDS/reference/get-total-transaction-amount

-->

User API

Base path: /api/v1/issuing_plans/{issuing_plan_opaque_id}. All requests require Authorization: Bearer <token>.

Create User

• Path: POST .../users
• Body: customer_name (string, required). Remote Host also requires: kyc_full_name, date_of_birth (YYYY/MM/DD), nationality (alpha-2). Optional: email, kyc_proof (object).
• Response 200: user.opaque_id — use as customer_opaque_id for all subsequent calls (Create Card, Activate, etc.).

curl --request POST \
  --url "https://merchant.cop-staging.straitsx.com/api/v1/issuing_plans/{issuing_plan_opaque_id}/users" \
  --header 'accept: application/json' \
  --header 'authorization: Bearer TOKEN' \
  --header 'content-type: application/json' \
  --data '{"customer_name": "John Doe", "kyc_full_name": "John Doe", "date_of_birth": "1990/01/01", "nationality": "SG"}'

Update User

• Path: PUT .../users/{customer_opaque_id}
• Body (optional): customer_name, kyc_full_name, date_of_birth, nationality, email, kyc_proof
• Response 200: Updated user object

Get User List

• Path: GET .../users
• Query: page[size], page[number], sort (-createdAt | +createdAt)
• Response 200: Paginated user list with opaque_id and user fields

Get User Detail

• Path: GET .../users/{customer_opaque_id}
• Response 200: Single user details

Get User Card List

• Path: GET .../users/{customer_opaque_id}/cards
• Query: page[size], page[number], sort, status, show_encrypted_card_number, show_encrypted_cvv, etc.
• Response 200: Paginated list of cards for that user

<!-- Source references:

• https://docs.straitsx.com/v1-CARDS/reference/create-user
• https://docs.straitsx.com/v1-CARDS/reference/update-user
• https://docs.straitsx.com/v1-CARDS/reference/get-user-list
• https://docs.straitsx.com/v1-CARDS/reference/get-user-detail
• https://docs.straitsx.com/v1-CARDS/reference/get-user-card-list

-->

Visa In-App Provisioning API

Enables users to add the card to Apple Pay or Google Pay from your app. Base path under /api/v1/issuing_plans/{issuing_plan_opaque_id}; all requests require Authorization: Bearer <token>.

Apple Pay In-App Provisioning

• Path: POST endpoint for Apple Pay provisioning (see reference; typically under users/cards or token resource).
• Body: Apple Pay provisioning payload (device data, nonce, etc. as per Visa/Apple docs).
• Response 200: Provisioning result; on success the card is added to the user’s Apple Wallet.

Google Pay In-App Provisioning

• Path: POST endpoint for Google Pay provisioning.
• Body: Google Pay provisioning payload (token requestor, device data, etc. as per Visa/Google docs).
• Response 200: Provisioning result; on success the card is added to Google Pay.

Webhook card_token_provisioned notifies you when provisioning succeeds; card_token_provisioning_failed when it fails.

<!-- Source references:

• https://docs.straitsx.com/v1-CARDS/reference/applepay-in-app-provisioning
• https://docs.straitsx.com/v1-CARDS/reference/googlepay-in-app-provisioning

-->

Instant issuance and OOB 3DS

Instant Card Issuance

StraitsX provides a dedicated product opaque ID for instant issuance. Use it in Create Card to issue cards that can be activated and used immediately (no card_activation_ready / iframe_ready webhook delay).

• Response includes remaining_card_in_pool. If pool is empty, Create Card returns XFC400068 card pool is empty (400). StraitsX manages the pool; monitor remaining count.
• Card status flow is the same (INACTIVE → activate via API).

OOB (Out-of-Band) 3DS

For 3DS, user can approve via app (e.g. biometrics) instead of OTP on 3DS page. Flow: user checks out → 3DS starts → ACS shows “approve in app” → StraitsX sends oob_notification webhook → your app prompts user → your app calls Obtain OOB API with result (approved/rejected) → user clicks Finish on 3DS page. Use transaction_id and authentication_id from webhook to call Obtain OOB. For adding card, acquirer_amount is zero.

<!-- Source references:

• .bonfire/cache/straitsx/instant-card-issuance.md, oob-flow.md
• https://docs.straitsx.com/v1-CARDS/docs/instant-card-issuance
• https://docs.straitsx.com/v1-CARDS/docs/oob-flow

-->

Remote Host Authorization and Webhook Notification

Remote Host Authorization (your endpoint)

StraitsX calls your endpoint (e.g. POST https://your-url.com/api/v1/authorization) with the authorization request. You must respond with approve (200) or reject (400).

Authentication

• StraitsX sends Authorization: Bearer <apiKey>. Use a dedicated API key (do not reuse the webhook signing secret). Reject any request without a valid Bearer token.
• Balance inquiries hit this endpoint at high volume; keep responses accurate and fast.

Request body (from StraitsX)

Approve (200)

Return JSON with a balances object:

• currency_code (string, required) — ISO 4217.
• ledger_balance (string, required) — Total balance including pending.
• available_balance (string, required) — Spendable balance.
• transaction_id (string, required) — Same as in the request.
• remarks (string, optional).

Reject (400)

Return JSON with:

• error_code (required): CARD0000 Internal Server Error, CARD0001 Insufficient Balance, CARD0002 Duplicate Transaction ID, CARD0003 Transaction Not Found, CARD0004 Card Not Found, CARD0005 Unauthorized, CARD0006 Card Restrictions.
• message, description (optional).

---

Webhook Notification (your endpoint)

StraitsX POSTs to your webhook URL (e.g. https://your-url.com/api/v1/webhook) with event payloads. Always verify the signature before processing.

Signature verification

• Header: X-COP-Signature-256: sha256={HMAC of raw request body with shared secret}.
• Reject the request if the signature is invalid or missing.

Timeout and retry (event_type=transaction)

• Timeout: 10 seconds per attempt. If you do not respond within 10s, the attempt is treated as failed.
• Retries: Up to 11 attempts with delays: 1s, 2s, 4s, 8s, then 10m×3, 1h×3, 3h.

Event types

For transaction, transaction_type values include: deduction, oct, balance_inquiry, hold, completion, reversal, partial_reversal, debit_verify. Respond with 2xx quickly so StraitsX does not retry unnecessarily.

<!-- Source references:

• https://docs.straitsx.com/v1-CARDS/reference/remote-host-authorization
• https://docs.straitsx.com/v1-CARDS/reference/webhook-notification

-->

Transaction simulation (staging only)

The Transaction Simulation API lets you trigger cardholder-like transactions in staging only. Use it to validate RHA and webhook behavior without real card usage.

Endpoint

• Path: POST /api/v1/issuing_plans/{issuing_plan_opaque_id}/users/{customer_opaque_id}/cards/{contract_opaque_id}/simulate_transactions
• Body (required): type (string) — e.g. ecom_authorization, pos_authorization, reversal, preauthorization_hold, preauthorization_completion, original_credit_transaction, atm_balance_inquiry, etc.
• Body (optional): issuer_amount (float), issuer_currency (default SGD), mid (default 123456789123456), mcc (default 5999), merchant_name (default SIMULATOR), merchant_location (default SINGAPORE), merchant_country_code (default SG), original_transaction_id (required for reversal, partial_reversal, preauth completion/release).
• Response 200: type, transaction_id, rrn, etc. StraitsX then sends RHA request and webhook.

Flow

1. Create a card in staging. 2. Call the simulate_transactions endpoint with type, amount, and optional merchant fields. 3. StraitsX sends an authorization request to your RHA endpoint and then a webhook notification; verify both.

Simulation types (examples)

Request shape

• amount, currency: From acquirer perspective; in RHA/webhook they appear as acquirer_amount, acquirer_currency. Omit currency for SGD.
• Optional: merchant_name, merchant_location, merchant_country_code, mid, mcc, original_transaction_id (for incremental/reversal).

Example (e‑commerce, cross‑border):

{
  "type": "ecom_authorization",
  "amount": 10.00,
  "currency": "USD",
  "merchant_name": "Spotify",
  "merchant_location": "STOCKHOLM",
  "merchant_country_code": "SE"
}

Usage

Use simulation to regression-test RHA approve/decline logic and webhook handling (transaction, reconciliation, pre_authorization_release, etc.). Request a Postman collection from your StraitsX representative for full examples.

<!-- Source references:

• https://docs.straitsx.com/v1-CARDS/docs/transaction-simulation
• https://docs.straitsx.com/v1-CARDS/reference/simulate-transaction

-->

Transaction types and flows

Transaction types (RHA and webhook)

When only webhook is sent (no RHA)

Reversals and refunds: StraitsX sends only a webhook. Use the webhook to update the cardholder balance. For reversal, if you had approved the original auth, deduct the reversed amount (or reverse the deduction).

Hold and completion

Approve hold with available/ledger balance; when completion arrives, approve with the completion amount. Clearing webhook follows. Pre-auth can auto-release; you may receive pre_authorization_release webhook.

Amounts

• Acquirer amount/currency: From merchant side. Issuer amount: Settled with Visa (SGD). Account amount/currency: Charged to cardholder (default SGD). Use account amount for balance updates.

<!-- Source references:

• .bonfire/cache/straitsx/transaction-type.md, case-by-case.md
• https://docs.straitsx.com/v1-CARDS/docs/transaction-type
• https://docs.straitsx.com/v1-CARDS/docs/case-by-case

-->