Create & complete a payment

Payments

Agentcard

Create a payment for a connected customer, wait until it's ready, and hand the card to your agent.

Once a customer’s handle is connected, your agent can pay a merchant on their behalf with a card from their Agentcard Wallet. A payment moves through a short lifecycle; you create it, wait for ready, then retrieve the card handoff.

Base URL: https://api.linqapp.com/api/partner/v3.

1. Create the payment

curl -X POST https://api.linqapp.com/api/partner/v3/payments \
  -H "Authorization: Bearer $LINQ_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "handle": "+14155550123",
    "amount_cents": 2500,
    "currency": "usd",
    "description": "Burger order",
    "merchant": { "name": "DoorDash", "url": "doordash.com" }
  }'

Field	Required	Notes
`handle`	yes	Connected customer — phone (E.164) or email.
`amount_cents`	yes	Integer, minor units (`2500` = $25.00 USD).
`currency`	yes	ISO currency code, lowercase (`usd`).
`description`	no	Shown to the customer.
`merchant.name` / `merchant.url`	no	Where the agent will spend.
`metadata`	no	Your own key/value pairs.

Always send an Idempotency-Key; retrying the same key returns the original payment instead of creating a second one.

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "needs_connection",
  "handle": "+14155550123",
  "amount_cents": 2500,
  "currency": "usd",
  "description": "Burger order",
  "attach_url": "https://zero.linqapp.com/...",
  "approval_url": "https://zero.linqapp.com/..."
}

If the handle isn’t connected yet, status is needs_connection — send the customer to attach_url to add a card, or approval_url to approve with a passkey, to finish connecting.

2. Wait until the payment is `ready`

Don’t poll in a tight loop — react to webhooks, then re-fetch for authoritative status:

curl https://api.linqapp.com/api/partner/v3/payments/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer $LINQ_API_KEY"

Payment statuses:

Status	Meaning
`needs_connection`	The handle isn’t connected — send them through connect first.
`connecting`	Connection in progress.
`awaiting_user_action`	Waiting on the customer (e.g. approval).
`ready`	The card is available — retrieve the handoff.
`authorized`	The merchant placed a hold on the card.
`succeeded`	The charge settled.
`declined`	The charge was declined.
`canceled`	You canceled the payment.
`expired`	The payment lapsed before completing.

3. Retrieve the card and let the agent pay

When status is ready, fetch the handoff and let your agent redeem it at Agentcard. Details never pass through Linq — see Cards & credentials.

curl https://api.linqapp.com/api/partner/v3/payments/550e8400-e29b-41d4-a716-446655440000/credentials \
  -H "Authorization: Bearer $LINQ_API_KEY"

4. Confirm the outcome

You’ll get payment.authorized when the merchant holds the card, then the payment settles to succeeded — poll GET /payments/{id} to confirm, as there is no succeeded webhook. If the charge fails you’ll get payment.declined.

Cancel a payment

Cancel one that hasn’t completed:

curl -X POST https://api.linqapp.com/api/partner/v3/payments/550e8400-e29b-41d4-a716-446655440000/cancel \
  -H "Authorization: Bearer $LINQ_API_KEY"

Notes

Re-fetch the payment on any webhook rather than trusting the event body.
declined, canceled, and expired are terminal — create a new payment to retry.