Connecting a system

The quickstart runs in sandbox mode. To verify against a real system of record, connect it once and drop test mode, the request barely changes.

1. Connect read-only credentials

Open Dashboard → Connections, pick a system, and paste its credential. Each system needs a different one, the exact credential and scope are listed on its integration page (for example, Stripe takes a restricted API key with read access to refunds and charges).

Postcept runs a read-only probe before saving: a credential that doesn’t authenticate is rejected on the spot, never stored as “connected.” So a connection that shows as live really is, there’s no silent gap between “saved” and “works.” Credentials are encrypted at rest and revocable at any time.

2. Keep it least-privilege

Postcept verifies, it never executes. Connections are read-only by default and scoped to just the objects a postcondition needs, it never asks for the write access that moves money or changes a record. See Security for the full posture.

3. Go from sandbox to live

The only change from the quickstart is dropping test and naming the connector you linked. Same operation id, same claim, now checked against the real system of record.

curl https://api.postcept.com/v1/verifications \
  -H "Authorization: Bearer pcpt_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "operation_id": "op_refund_8F31",
    "agent_id": "SupportAgent-04",
    "connector": "stripe",
    "claim": {
      "refund_id": "re_4md82k",
      "amount_cents": 12000,
      "currency": "usd",
      "customer": "mara.ellis@example.com"
    }
  }'

Keep the operation_id stable across retries and handoffs: it’s how Postcept correlates an action to detect duplicates, and (with an Idempotency-Key) how a safe retry returns the original result instead of re-running.

Carry the operation id into the provider

When your agent creates the refund, put the operation id in the field the provider passes through untouched. That is what lets Postcept list the charge’s refunds in the system of record and prove the same operation was not refunded twice, which the refund contract requires before safe_to_claim_complete can be true.

Stripe      metadata.operation_id
Square      reason
PayPal      custom_id
Braintree   orderId
QuickBooks  DocNumber
Shopify     note
NetSuite    externalId
Adyen       merchantReference

A refund created without the passthrough still verifies its amount, currency and settlement state. The duplicate check then runs on Postcept’s own cross-charge operation index, and safe_to_claim_complete stays false with the reason required_check_unconfirmed:not_duplicate.

4. Staying healthy

Live connections depend on a system you don’t control, so a verification can fail to run if that system is briefly unreachable. Postcept surfaces that as a retryable 503 rather than a false incomplete, see verification results. Rotating a credential re-runs the same read-only check, so a connection never silently goes stale.