Initiate a test transaction

POST

/transaction

• Production
• Non-production. Environments use a single-level environment prefix on the host; the path and payload are identical across environments.

Originates a test authorization. Authenticated with a CPS-issued API key (sk_live_…) as a bearer token.

JWT bearer tokens are rejected with 401 on this endpoint. POST /transaction accepts a CPS-validated API key only. A Logto-issued JWT — even a valid one carrying an organization_id claim — is refused here, because SMP cannot yet map a Logto org to the numeric org_id server-side without trusting a caller-supplied id.

Authorizations

• apiKey

Request Body ^required

object

iso8583

required

The request message as hex. A 0x prefix is accepted and stripped.

string

Example

0200...

network

Selects the engine: visa or mastercard, matched case-insensitively (VISA is accepted). Absent or null selects Visa/SVE; any other value is rejected with 400.

string | null

default: visa

merchant_id

Accepted for forward compatibility but currently ignored — not read, logged, or routed on.

string

Example

12345

terminal_id

Accepted for forward compatibility but currently ignored — not read, logged, or routed on.

string

Example

ABC123

Examples

Minimal Visa request

Substitute <hex> with a real authorization frame — this is a template, not a runnable payload. SMP returns 400 on a non-hex iso8583 value.

{
  "iso8583": "<hex>",
  "network": "visa"
}

Responses

200

The transaction completed a full round trip. A declined transaction (response_code ≠ "00") is a valid business outcome and is still returned at 200.

object

request_id

required

Trace identifier for this request.

string

Example

req_abc123

iso8583

required

The finalized ISO 8583 response, uppercase hex.

string

Example

0210...

status

required

approved when DE 39 = 00, otherwise declined.

string

Allowed values: approved declined

response_code

required

ISO 8583 DE 39 from the finalized response.

string

Example

00

Examples

Approved authorization

{
  "request_id": "req_abc123",
  "iso8583": "0210...",
  "status": "approved",
  "response_code": "00"
}

400

Malformed request — the iso8583 field is not valid hex, or network is neither visa nor mastercard.

RFC 7807 application/problem+json error body, as emitted by ASP.NET Core Results.Problem.

object

type

string format: uri-reference

default: about:blank

title

string

status

integer

detail

string

instance

string format: uri-reference

Examples

{
  "type": "about:blank",
  "title": "Invalid ISO 8583 hex",
  "status": 400,
  "detail": "The iso8583 field in the request body could not be decoded from hexadecimal."
}

{
  "type": "about:blank",
  "title": "Unknown network",
  "status": 400,
  "detail": "'amex' is not a supported network. Accepted values: 'visa', 'mastercard'."
}

401

Authentication failed — missing, malformed, invalid, revoked, or suspended API key, or a JWT bearer token was sent.

RFC 7807 application/problem+json error body, as emitted by ASP.NET Core Results.Problem.

object

type

string format: uri-reference

default: about:blank

title

string

status

integer

detail

string

instance

string format: uri-reference

Examples

{
  "type": "about:blank",
  "title": "Invalid API key",
  "status": 401,
  "detail": "The supplied API key is missing, malformed, invalid, revoked, or suspended."
}

{
  "type": "about:blank",
  "title": "JWT authentication not supported",
  "status": 401,
  "detail": "POST /transaction accepts CPS API keys only. JWT bearer support is pending CPS org-id resolution."
}

429

Rate limit exceeded — the API key’s configured requests-per-second limit. A Retry-After header is returned.

RFC 7807 application/problem+json error body, as emitted by ASP.NET Core Results.Problem.

object

type

string format: uri-reference

default: about:blank

title

string

status

integer

detail

string

instance

string format: uri-reference

Examples

{
  "type": "about:blank",
  "title": "Rate limit exceeded",
  "status": 429,
  "detail": "The API key has exceeded its configured requests-per-second limit."
}

Headers

Retry-After

integer

Seconds to wait before retrying.

502

Delivery error — no active mTLS connection for the org, or a write/read failure (a delivery timeout included) on the outbound leg to your fintech backend; also an engine HTTP error or an undecodable engine response.

RFC 7807 application/problem+json error body, as emitted by ASP.NET Core Results.Problem.

object

type

string format: uri-reference

default: about:blank

title

string

status

integer

detail

string

instance

string format: uri-reference

Examples

{
  "type": "about:blank",
  "title": "Delivery error",
  "status": 502,
  "detail": "No active mTLS connection for the org."
}

{
  "type": "about:blank",
  "title": "Engine error",
  "status": 502,
  "detail": "The network engine returned an HTTP error."
}

503

API-key validation with CPS is unavailable, so the tenant could not be resolved.

RFC 7807 application/problem+json error body, as emitted by ASP.NET Core Results.Problem.

object

type

string format: uri-reference

default: about:blank

title

string

status

integer

detail

string

instance

string format: uri-reference

Examples

{
  "type": "about:blank",
  "title": "API key validation unavailable",
  "status": 503,
  "detail": "SMP could not validate the supplied API key with CPS."
}

504

The Visa/Mastercard engine call itself timed out, hit an open circuit breaker, or failed at the transport level.

RFC 7807 application/problem+json error body, as emitted by ASP.NET Core Results.Problem.

object

type

string format: uri-reference

default: about:blank

title

string

status

integer

detail

string

instance

string format: uri-reference

Examples

{
  "type": "about:blank",
  "title": "Engine timeout",
  "status": 504,
  "detail": "The network engine call timed out."
}