sealLinkGrant, as Paying with Stripe Link shows. From any other language, follow the steps on this page. Test values let you check your code byte for byte before a shopper ever pays, and a complete Python version is near the end.
Agentcard turns on Link payments for each company. Until they reach yours, a request with A hotel, a rental car or a flight booked through Agentcard takes Link as well, with one approval in Link for each booking at its quoted total.
payment_source: "link" is refused with a 400 and charges nothing, so keep the card saved with Agentcard as the shopper’s way to pay:Offer Stripe Link
Name the ways to pay you offer on every request toPOST /buy, in the order the shopper sees them. vault is the card the shopper saved with Agentcard, and link is their Stripe Link wallet. While the shopper pays with Link, also send payment_source: "link" and their Link spending limits:
An answer with carts to pay lists each way to pay you offer, and whether it can pay those carts:
fits: false as a disabled button beside its reason_text. Agentcard leaves out a way to pay that a store refuses outright. The vault entry carries setup_needed: true when the shopper has no card saved yet.
Confirm with the Link payment
Once the shopper says yes, ask Link for a payment of the most the cart can cost, one for each store, and wait until the shopper approves it in Link. Then confirm that store’s cart with the approved payment: itsconversation_id, the cart’s hash in confirm, and the payment’s id, amount and currency in link_payment:
202 with status: "link_seal_needed" and a link_seal object. link_seal.binding describes the payment Agentcard is about to make: which approval, which checkout, which store, how much, and until when. seal_by is the time your encrypted approval has to arrive by:
Check the payment first
Encrypt the shopper’s approval only whenbinding describes the payment the shopper approved in Link. Agentcard pays exactly what binding describes, so encrypting for any other payment would let money go somewhere the shopper did not approve. Check every line below, and encrypt nothing when one fails:
When a check fails, cancel the payment in Link and encrypt nothing. Agentcard charges nothing, and the shopper can pay for that cart with the card saved with Agentcard.
Keep Agentcard’s key in your code
Encrypt only to a public key you keep in your own code. Copy this table into your server:
Look up
link_seal.key_id in your table and encrypt 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 Agentcard service that types the card can read text encrypted to a key from this table.
Agentcard adds a new key to this table, beside the current one, before the 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 nothing from you: cancel the payment in Link. Agentcard charges nothing, and the shopper can pay with the card saved with Agentcard.
Encrypt the approval
Encrypt once for each confirm, with a key pair you make for that one message:- Write the approval as compact JSON, with
kind,spend_request_idandaccess_tokenin that order:{"kind":"link","spend_request_id":"lsrq_...","access_token":"liat_..."}. It 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 message and then discard it.
- Run ECDH between your new private key and Agentcard’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 Agentcard’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 approval 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.
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 < 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 Agentcard cannot read the message.
A value outside these forms is one Agentcard never sends: encrypt nothing, and cancel the payment 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.
Send the encrypted approval
Post the envelope to the approval named inlink_seal.approval_id, with the same access token and external_user_id as the confirm, before seal_by:
purchase.message tells you how the order went, and names the Link payment and whether the store charged it, as facts.linkPayment reads it. Keep the shopper’s Link access token out of your logs, and send it nowhere but inside the envelope.
Read a refusal
Agentcard refuses an envelope it cannot use, and charges nothing. An envelope whose parts are padded, in standard base64 or the wrong length is refused the moment you post it:Encrypt in Python
Save the module below asagentcard_link_seal.py. The module encrypts the approval with the cryptography package, checks binding against the payment the shopper approved, and holds Agentcard’s public key in its own text. 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 your code with test values
Each test value set below, called a vector, fixes the two values an encryption otherwise makes at random: the new key pair and the IV. Encrypt each vector’sgrant, the approval, 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 approval. 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.