Network management — Key exchange

Authorizations

apiKey

Request Body^required

Request body for POST /transaction/network-management/{action}. Network management is a control message, not a card transaction: no channel, card, or amount applies.

object

network

Target network. Only visa (the default when omitted) is supported; a mastercard request returns 501 Not Implemented. A request for a network whose product the organization is not entitled to (including an expired trial) returns 403 Forbidden.

string | null

default: visa

type

The DE 70 network-management information code for the key-exchange action (3- or 4-digit, e.g. 101; defaults to the key-change-request code when omitted). Ignored for echo, sign-on, and sign-off.

string

x-request-id

Trace correlation id for logging only. Prefer the X-Request-Id HTTP header.

string

Examples

Sign the connection on

{
  "network": "visa"
}

200

The network-management message completed a full round trip.

Response body for POST /transaction/network-management/{action} on the success (200) path. Adds the resolved action/type to the shared TransactionOperationResponse shape.

object

request_id

required

SMP-generated req_-prefixed correlation id for tracing and log correlation.

string

Example

req_abc123

sent

required

The outbound ISO 8583 message SVE built and SMP transmitted to the fintech backend, as uppercase hexadecimal.

string

parsed_request

required

A rendered view of a built ISO 8583 message: its MTI plus a set-field map keyed as "NN (Field Name)" (2 digits for DE ≤ 99, 3 digits above), ordered ascending by data-element number. Binary data elements are rendered as uppercase hex.

object

mti

required

Four-digit message type indicator, e.g. 0100.

string

Example

fields

required

Set data elements, keyed as "NN (Field Name)" and ordered ascending by data-element number.

object

key

additional properties

string

last_response_hex

Finalized ISO 8583 response message from the fintech backend, as uppercase hexadecimal.

string | null

parsed_response

One of:

object
null

A rendered view of a built ISO 8583 message: its MTI plus a set-field map keyed as "NN (Field Name)" (2 digits for DE ≤ 99, 3 digits above), ordered ascending by data-element number. Binary data elements are rendered as uppercase hex.

object

mti

required

Four-digit message type indicator, e.g. 0100.

string

Example

fields

required

Set data elements, keyed as "NN (Field Name)" and ordered ascending by data-element number.

object

key

additional properties

string

action

required

The network-management action performed, e.g. sign-on, echo, key-exchange.

string

type

required

The DE 70 network-management information code that produced this message, e.g. 0071.

string

Examples

Sign-on accepted

{
  "request_id": "req_ghi789",
  "sent": "08008220000000000000040000000000000009112230450000010071",
  "parsed_request": {
    "mti": "0800",
    "fields": {
      "07 (Transmission Date/Time)": "0911223045",
      "11 (Trace Number)": "000001",
      "70 (Network Management Information Code)": "0071"
    }
  },
  "last_response_hex": "0810822000000200000004000000000000000911223045000001F0F00071",
  "parsed_response": {
    "mti": "0810",
    "fields": {
      "07 (Transmission Date/Time)": "0911223045",
      "11 (Trace Number)": "000001",
      "39 (Response Code)": "00",
      "70 (Network Management Information Code)": "0071"
    }
  },
  "action": "sign-on",
  "type": "0071"
}

400

Malformed request — the body is not valid JSON or does not match the schema, or card is missing or has an empty pan. Unsupported network values return 501, not 400. Engine-side input validation failures (for example a missing amount or PIN) currently surface as 502 engine errors.

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": "Malformed structured transaction request",
  "status": 400,
  "detail": "The request must include a 'card' with a non-empty 'pan'."
}

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": "This endpoint accepts CPS API keys only. JWT bearer support is pending CPS org-id resolution."
}

403

Product not entitled — the organization has no active trial or subscription for the product that serves the requested network. Checked after the 501 network check and again per frame at delivery.

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": "product_not_entitled",
  "title": "Product not entitled",
  "status": 403,
  "detail": "The organization is not entitled to the 'visa' product. Check the product entitlements in the dashboard."
}

429

Rate limit exceeded — either the API key’s configured requests-per-second limit, or the per-organization requests-per-second cap on a product trial (trial_rate_limited). 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."
}

{
  "type": "trial_rate_limited",
  "title": "Rate limit exceeded",
  "status": 429,
  "detail": "The organization's trial of the 'visa' product has exceeded its requests-per-second limit."
}

Headers

Retry-After

integer

Seconds to wait before retrying.

501

Unsupported network — only visa is supported today; a mastercard request (or any other value) fails here until SME structured support lands.

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": "Unsupported network",
  "status": 501,
  "detail": "'mastercard' is not yet supported on the structured transaction routes. Only 'visa' is supported today; Mastercard/SME support is tracked as a follow-up issue."
}

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. Engine-side input validation failures (for example a missing amount or PIN) also surface here as Engine error, not 400.

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; or the product entitlement check at delivery could not be confirmed with CPS. Retry the request.

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."
}

{
  "type": "entitlement_check_unavailable",
  "title": "Entitlement check unavailable",
  "status": 503,
  "detail": "SMP could not confirm product entitlement with CPS. Retry the request."
}

504

The Visa 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."
}

Network management — Key exchange

Authorizations

Request Body required

Examples

Responses

200

Example

Example

Example

Examples

400

Examples

401

Examples

403

Examples

429

Examples

Headers

501

Examples

502

Examples

503

Examples

504

Examples

Request Body^required