Skip to main content
POST
Get credential
The response has two modes, depending on whether your platform has a public key registered with Clink:
  • Registered public key (matched: true): Clink seals the card fields into a key/payload envelope that only your platform can decrypt with the matching private key.
  • No registered public key (matched: false): when plaintext mode is enabled server-side and gateway response redaction is live, Clink returns the DPAN and dynamic CVV in plaintext in the response. The card can be used directly, but these fields reach your backend in plaintext.
Register a public key with Clink to use the encrypted mode; this is recommended for production. The response sends no credential deadline: the validity is dynamicDataExpiration in card (plaintext mode) or in the decrypted payload (sealed mode).

Public key registration

Contact Clink to register your platform’s RSA public key in each environment; it is mapped to your platform client name. The registered key selects the response mode: with a key the credential is sealed to it; without one, Clink returns plaintext card fields only when plaintext mode is enabled server-side and gateway response redaction is live (the MCP-equivalent fallback). With the default gate off, the endpoint fails closed instead. Register the key before production use.
Without a registered public key, when plaintext mode is enabled server-side, the response returns the DPAN and dynamic CVV in plaintext to your backend. Keep these fields out of logs, model input, and ordinary storage, and do not keep them beyond the checkout. Register a public key with Clink (recommended for production) to switch to the sealed key/payload mode. This plaintext fallback matches MCP get_credential. Do not enable plaintext mode in environments where gateway response redaction is not yet active: it is config-gated server-side by portal-plaintext-enabled (default off), and with the gate off the endpoint fails closed with 71211012 (credential_public_key_not_configured) instead of returning plaintext card fields.

Decrypt the sealed response

When matched is true, decrypt key and payload with your platform private key. The decrypted payload contains orderId, paymentExecutionDetailId, clientReferenceId, status, the network credential (DPAN, dynamic CVV, and expiry), and cardholder and address fields. The envelope format and a decryption example are in Decryption. Keep decrypted card fields out of logs, model input, and ordinary records, and use the validity information in the decrypted payload (dynamicDataExpiration) to decide when to use the credential. Save client_reference_id; Report credential result uses it.

Idempotency

client_reference_id is the idempotency key. Retrying with the same client_reference_id returns the same credential: the same sealed envelope when matched is true, and in plaintext mode the same card from the server-side encrypted cache, with no second issuance. Reusing it with different parameters returns 409 with code 71211011 (portal_conflict).

Authorizations

Authorization
string
header
required

Portal user token from POST /agent/cwallet/platform/portal/tokens. Reads require portal:read; writes require portal:write.

Body

application/json
instruction_id
string
required

ACTIVE instruction owned by the token's customer.

Example:

"inst_..."

mandate_id
string
required

Mandate under that instruction that covers the purchase.

Example:

"mand_..."

client_reference_id
string
required

Platform-side reference and idempotency key for this purchase. Store it; the result report uses the same value.

Example:

"platform-ref-001"

amount
string
required

Transaction amount, decimal string in major currency units.

Example:

"12.50"

currency_code
string
required

Three-letter currency code.

Example:

"USD"

merchant_url
string
required

Merchant checkout URL. Must use HTTPS.

Example:

"https://shop.example.com/checkout"

merchant_name
string

Merchant display name. Defaults to the host of merchant_url.

Example:

"Example Store"

merchant_country_code
string
default:US

Merchant country, ISO 3166-1 alpha-2.

Example:

"US"

merchant_order_id
string

Merchant-side order ID, when available.

Example:

"shop-order-1"

products
object[]

Line items for the purchase.

shipping_address
object

Shipping address.

Response

Success

code
integer<int32>

200 on success.

Example:

200

msg
string

Result message.

Example:

"Success"

data
Sealed (matched: true) · object

Returned when your platform has a registered public key. Contains only matched, key, and payload; the IDs are inside the decrypted payload.