Card Display: Partner Setup Runbook

To show card details in your web app, card display must be enabled on your gateway instance. You send Paynetics the setup details below, Paynetics enables your instance, and you confirm the setup with a test call.

The integration itself is described in the Card Display Partner Guide (PDF). Ask Paynetics for it if you don't have it.

Only instances can use card display. A merchant (x-type: 2) is always refused.

Step 1: Send your setup details

Send these to Paynetics before the setup starts. Missing origins is the most common reason a setup has to be redone.

What	Example	Notes
Instance token and API key	`c211bf55-…`	Identifies the instance to enable for card display
Web origins that will host the card page	`https://app.partner.com`	Every origin, including staging. `www.partner.com` and `partner.com` are different origins
Fields to show	`pan`, `expiry`, `cvv`	Default is card number + expiry. CVV must be requested explicitly
Card artwork (optional)	`https://cdn.partner.com/cards/black.jpg`	Public https image, or `none` for a transparent card. Without artwork, the renderer uses its bundled artwork
Test card token	a card on your instance	Used for the confirmation call in Step 2

Origin rules:

Format is scheme://host[:port]. No path and no trailing slash.
Exact match only, no wildcards. www.partner.com and partner.com both need listing if both serve the page.
Use http:// origins only for test environments.

Artwork rules: must start with https:// (or http://), at most 2048 characters, no spaces or quotes. The image must be publicly reachable. An invalid value is silently ignored, not rejected, so check it in Step 2.

Step 2: Confirm with a test call

Once Paynetics has enabled your instance, make a test call with your instance credentials. A working setup answers code: 0 with a renderer.mount_url.

Bash

export GW="https://<gateway host>" API_KEY="<instance api key>" API_SECRET="<instance api secret>"
export CARD="<test card token>" ORIGIN="https://app.partner.com"

BODY=$(jq -c -n --arg o "$ORIGIN" '{user:{user_id:"support_check"},origin:$o,
  requested_fields:["pan","expiry"],purpose:"support_setup_check",
  ui:{locale:"en",theme:"light"},constraints:{ttl_seconds:60,max_reveals_per_field:1}}')
TS=$(date +%s)
HASH=$(printf '%s' "${API_KEY}${TS}card_display_session_create${BODY}" \
  | openssl dgst -sha256 -hmac "$API_SECRET" | awk '{print $NF}')

curl -s -X POST "$GW/v2/cards/$CARD/display-sessions" \
  -H "x-api-key: $API_KEY" -H "x-timestamp: $TS" -H "x-hash: $HASH" \
  -H "Idempotency-Key: $(uuidgen | tr A-Z a-z)" \
  -H 'Content-Type: application/json' -d "$BODY" | jq .

Check the response:

☐ code is 0
☐ allowed_fields matches the fields you asked for
☐ renderer.mount_url points at the secure renderer host
☐ There is no session_token field (the gateway strips it)

If cvv or artwork was configured for your instance, repeat with "requested_fields": ["pan","expiry","cvv"]. Then check that the artwork shows on your page and let Paynetics know. It can't be checked from the API response.

Limits

Sessions last 30 to 180 seconds (default 120), each field can be revealed 1 to 10 times (default 1), and creation is limited to 20 sessions per minute per instance and 5 per minute per user.

Troubleshooting

Each error code points to what is missing or wrong.

You see	Meaning	Usual cause	Fix
Operation not allowed (auth step)	Operation not granted	Card display is not enabled for your instance yet, or the caller is a merchant	Call as an instance. If you already do, contact Paynetics
`19005`	Card display not enabled	No origins are set for your instance	Send your origins to Paynetics (Step 1)
`19001`	Origin not allowed	Origin not listed, typo, `www` vs bare host, `http` vs `https`, or a recent change not yet active	Send the exact origin you gave in Step 1. If it is listed and still fails, contact Paynetics
`19002`	Field not enabled	Asked for `cvv` without CVV enabled for your instance	Ask Paynetics to enable CVV (Step 1), or leave `cvv` out of `requested_fields`
`19003`	Too many sessions	Over 20/min per instance or 5/min per user	Wait 60 s. If the volume is legitimate, contact Paynetics
`19004`	Idempotency-Key reused	Same key sent with a different body	Use a new UUID per request
`19006`	Service unavailable	The card display service can't be reached	Contact Paynetics
Validation error	Bad request	Origin has a path, unknown field name, missing `user.user_id`	Fix the request

Errors after a session is created show up in the browser, not at the gateway:

Browser shows	Cause	Fix
`BOOTSTRAP_FAILED`	Session expired, already used, or closed	Create a new session for each page view
Blank card area, CSP `frame-ancestors` error in the console	Page is on a different origin than the one in the request	Send the page's real origin. It must be one of the origins you gave in Step 1
`SESSION_CONSUMED`	Field already revealed `max_reveals_per_field` times	Expected. Raise the limit (max 10) if needed
`REVEAL_FAILED`	Renderer couldn't get the card value	Contact Paynetics with the session id and time

When you contact Paynetics, include the instance token, the session id (if there is one), the time of the call and the error code.

Setup checklist

☐ Origins, fields, artwork and a test card token sent to Paynetics (Step 1)
☐ Test call returns code: 0 with a mount_url and no session_token (Step 2)
☐ CVV and artwork checked, if configured (Step 2)
☐ Card shows on your page, and Paynetics is informed
☐ Card Display Partner Guide (PDF) received