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 A cart that Link cannot pay at, once Link reaches your company, answers
payment_source: "link" is refused with a 400 and charges nothing, so keep the Vault as the shopper’s way to pay: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 itsconversation_id, the cart’s hash in confirm, and the spend request’s id, amount and currency in link_payment:
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:
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:- Write the grant as compact JSON, with
kind,spend_request_idandaccess_tokenin that order:{"kind":"link","spend_request_id":"lsrq_...","access_token":"liat_..."}. The grant is at most 4,096 bytes. - 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_idislink_seal.key_id, and the rest come fromlink_seal.binding. Copy each string as it is, and write each number as an integer with no decimal point. - Make a new P-256 key pair. Use it for this one seal and then discard it.
- Run ECDH between your new private key and the typing service’s public key. The shared secret is the 32-byte x-coordinate.
- 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. - 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.
- Write the envelope.
" 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 inlink_seal.approval_id, with the bearer token and the external_user_id of the confirm, before seal_by:
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 asagentcard_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.
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’sgrant 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.