Skip to main content
When a shopper pays with their Stripe Link wallet, your server hands Agentcard the shopper’s Link grant: the id of the spend request the shopper approved, and the shopper’s Link access token. Your server seals the grant before it sends it, so only Agentcard’s typing service can open it: the service that reads Link’s one-time card and types it into the store’s checkout. Agentcard’s API stores the sealed bytes and passes them on, and cannot read them. The Commerce SDK seals for you with sealLinkGrant. If your server runs another language, seal it yourself with the steps on this page. Test vectors let you check your code byte for byte before a shopper ever pays, and a complete Python version is at the end.
Agentcard turns Link payments on for each company. Until they reach yours, a request with payment_source: "link" is refused with a 400 and charges nothing, so keep the Vault as the shopper’s way to pay:
A cart that Link cannot pay at, once Link reaches your company, answers 409 link_payment_unavailable instead, and also charges nothing.

Know when to seal

Once the shopper approves a Link spend request for the most the cart can cost, your server confirms that store’s cart with the approved payment. A confirm under Link names its conversation_id, the cart’s hash in confirm, and the spend request’s id, amount and currency in link_payment:
A cart confirmed with payment_source: "link" answers 202 with status: "link_seal_needed" and a link_seal object. The binding names the approval, the browser that pays, the store, the total and the time the seal stops opening:
Seal only when the binding is for the payment the shopper approved in Link. The typing service pays exactly what the binding names, so a seal for any other binding would let the payment go somewhere the shopper did not approve. Check every line below, and seal nothing when one fails: When a check fails, cancel the spend request in Link and seal nothing. Agentcard charges nothing, and the shopper can pay for that cart with the Vault.

Pin the typing service’s key

Seal only to a key you keep in your own code. Copy this table into your server: Look up link_seal.key_id in your table and seal to the key it finds. Never take a public key from an Agentcard answer: a key your server reads from the network could belong to anyone, and only the typing service can open a seal made to a key you pin. Agentcard adds a new key to this table, beside the current one, before the typing service starts using it. Add each new key to your table when it appears here. A confirm that names a key id your table does not hold gets no seal from you: cancel the spend request in Link. Agentcard charges nothing, and the shopper can pay with the Vault.

Seal the grant

Seal one grant per confirm, with a key pair made for that seal alone:
  1. Write the grant as compact JSON, with kind, spend_request_id and access_token in that order: {"kind":"link","spend_request_id":"lsrq_...","access_token":"liat_..."}. The grant is at most 4,096 bytes.
  2. Write the additional data as a compact JSON array in this order: ["agentcard.typed-card",1,key_id,authorization,session,origin,amountCents,currency,expiresAt]. key_id is link_seal.key_id, and the rest come from link_seal.binding. Copy each string as it is, and write each number as an integer with no decimal point.
  3. Make a new P-256 key pair. Use it for this one seal and then discard it.
  4. Run ECDH between your new private key and the typing service’s public key. The shared secret is the 32-byte x-coordinate.
  5. Derive a 32-byte key with HKDF-SHA-256. The input is the shared secret. The salt is your new public key followed by the typing service’s public key, each as its 65-byte uncompressed point, 130 bytes together. The info is the ASCII text agentcard typed link grant v1.
  6. Encrypt the grant with AES-256-GCM under that key, with a random 12-byte IV and the additional data from step 2. Keep the 16-byte tag at the end of the ciphertext.
  7. Write the envelope.
Every value in the grant and the binding is ASCII, as the table below shows. Write both JSON texts with no spaces, and escape only " as \" and \ as \\. Write /, <, > and & as they are. Go’s json.Marshal writes <, > and & as \u003c escapes, so use a json.Encoder with SetEscapeHTML(false) and trim its trailing newline, or build the two strings by hand. The additional data has to match Agentcard’s spelling byte for byte, or the seal does not open. A value outside these forms is one Agentcard never sends: seal nothing, and cancel the spend request in Link.
Write every byte field in base64url with no = padding, as RFC 4648 section 5 describes. Python’s base64.urlsafe_b64encode adds padding, so strip the trailing = signs. The envelope’s own JSON can list its fields in any order and with any spacing.

Post the sealed grant

Post the envelope to the approval named in link_seal.approval_id, with the bearer token and the external_user_id of the confirm, before seal_by:
The typing service then pays the store, and a purchase.message tells you how the order went. Keep the access token for the Link sign-in only: it never goes into a log line, and your server sends it nowhere but inside the seal.

Read a refusal

Agentcard refuses a seal it cannot use, and charges nothing. Agentcard refuses a seal whose parts are padded, in standard base64 or the wrong length the moment you post it:

Seal in Python

Save the module below as agentcard_link_seal.py. The module seals a grant with the cryptography package, checks the binding against the payment the shopper approved, and pins the typing service’s key. Install the package with pip install cryptography, and run the module on Python 3.9 or later.
Check the binding, then seal and post. A binding Agentcard never sends raises LinkSealError, as does a key id your table does not pin:

Check against test vectors

Each vector below fixes the two values a seal otherwise makes at random: the new key pair and the IV. Seal each vector’s grant to its recipient under its binding, with its ephemeral private key and its iv, and your code must produce its envelope exactly. The ephemeral private key is PKCS #8 DER in base64url: in Python, load_der_private_key(from_b64url(key), password=None). Matching an envelope means each of its six fields holds the same value. The vectors also show plaintext, additional_data, shared_secret_hex, salt and aes_key_hex, so a mismatch tells you which step to look at. Every private key here is a test key made for these vectors. The first vector is a plain grant. The second holds a quote, a backslash and a slash in the access token and a port in the origin, so it checks your JSON escaping. Both include the recipient’s private key, so you can open them too.
The third vector is sealed to the typing service’s production key, which has no published private key. Check it by matching its envelope:
In production, never pass an ephemeral key or an IV: make both fresh for every seal.