Card SDK

In a Card SDK, OTP (One-Time Password) verification is used to securely display card data — adding an extra layer of security on top of the standard authentication flow.

When a user requests access to sensitive information (PAN, CVV, expiry), an OTP is generated between the partner's host and the SDK. The user supplies the OTP back to the SDK; once it is verified, the SDK grants access to the card details for the duration of that session.

The endpoint below requests a one-time password from Paynetics for a given card / session.

Request OTP

POST /v2/sdk/otp
Operation sdk_otp

Request body

Field Type Description
card string (0,any)
device_id string (0,any)

Example request

{
    "card": "string",
    "device_id": "string"
}

Response

Field Type Description
code integer (0,any)

Example response

{
    "code": 0,
    "data": {
        "otp": "0ba5e81d-c43b-4008-b2d6-0d390f6f8c08"
    }
}

Generate a one-time password for the requested card / session. The OTP is delivered through the configured channel and must be returned to the SDK to unlock access to card details.

Create display session

POST /v2/cards/{card}/display-sessions
Operation card_display_session_create
HMAC Operation - card_display_session_create. Creates a display session for the card and returns the URL to mount the secure iframe. Optional header Idempotency-Key (UUID): the same key with the same body replays the original session; when omitted the gateway generates one per request.

Path parameters

NameExampleDescription
card
string required
e61bac10-5be2-49e6-99e1-82ccfd4cb644 Token from card creation

Headers

NameExampleDescription
Idempotency-Key
string
7c1f0b5e-4d3a-4f9e-9a1c-2b6d8e0f1a23

Request body

Field Type Description
origin string (0,512) required Exact web origin of the page that will embed the iframe: scheme://host[:port], no path.
requested_fields array (0,any) required
panexpirycvv
purpose string (0,128) required Free text for the audit trail, stable per screen.

Example request

{
    "user": {
        "user_id": "usr_12345",
        "session_id": "sess_web_abc",
        "ip": "203.0.113.10",
        "user_agent": "Mozilla/5.0 ...",
        "device_id": "dev_fingerprint_or_uuid"
    },
    "origin": "https://app.partner.example",
    "requested_fields": [
        "pan",
        "expiry"
    ],
    "purpose": "customer_card_details_view",
    "ui": {
        "locale": "en",
        "theme": "light"
    },
    "constraints": {
        "ttl_seconds": 120,
        "max_reveals_per_field": 1
    }
}

Response

Field Type Description
session_id string (0,any)
expires_at string (0,any) RFC 3339, UTC.
allowed_fields array (0,any)
token_type string (0,any)

Example response

{
    "session_id": "01M20AXBS24E696439BASGQGKJ",
    "expires_at": "2026-09-08T11:05:06+00:00",
    "allowed_fields": [
        "pan",
        "expiry"
    ],
    "token_type": "card_display_session",
    "renderer": {
        "iframe_origin": "https://secure.card-display.example",
        "mount_url": "https://secure.card-display.example/card-display/render?session=01M20AXBS24E696439BASGQGKJ",
        "sdk_min_version": "1.0.0"
    }
}

esc
↑↓ navigate ↵ open esc close
Copied