Payments

The Payments API is a RESTful API that enables merchants to process payments and manage the full payment lifecycle — from creation through capture, confirmation, and refund — without requiring the Convenient Checkout UI widget.

Supported payment methods:

Method	Description
Credit / Debit Cards	Visa, Mastercard, Amex, Discover
HSA / FSA Cards	Health spending account cards
ACH	Bank account transfers
Apple Pay	Tokenized mobile wallet
Google Pay	Tokenized mobile wallet

---

Payment Lifecycle

The diagram below illustrates payment state transitions from creation to completion:

For a detailed state reference, see the Payment Lifecycle page.

---

Available Endpoints

Operation	Method	Endpoint	Reference
Create Payment	POST	v2/payments	API Ref
Get Payment by ID	GET	v2/payments/{paymentId}	API Ref
Get by Merchant Txn ID	GET	v2/payments	API Ref
Capture Payment	POST	v2/payments/{paymentId}/capture	API Ref
Cancel Payment	POST	v2/payments/{paymentId}/cancel	API Ref
Refund Payment	POST	v2/payments/{paymentId}/refund	API Ref

note

Create Payment returns HTTP 202 ACCEPTED immediately. The paymentId in the response is used for all subsequent operations. Poll or use webhooks to track final status.

---

Integration Flow

The typical server-to-server payment integration follows these steps:

1. POST v2/payments          → Receive paymentId (202 Accepted)
2. Receive webhook            → PAYMENT_SUCCEEDED / PAYMENT_FAILED
   — or —
   GET  v2/payments/{id}      → Poll for status
3. POST v2/payments/{id}/capture  → (if auth-capture flow)

Step-by-step:

1. Create Payment — Submit payment amount, customer details, and PaymentMethodId. The API returns immediately with a paymentId and initial status.
2. Track Status — Listen for webhook notifications (PAYMENT_SUCCEEDED, PAYMENT_FAILED) or poll GET v2/payments/{paymentId}.
3. Capture (auth-capture only) — Call POST capture once goods/services are ready to be fulfilled.
4. Retrieve via Merchant Transaction ID — Use your own merchantTransactionId to look up a payment if the paymentId is unknown. The merchantTransactionId is also returned in the GET /sessions response.

---

Payment Types

💳

Single Payment

Charge one card for the full transaction amount. Standard flow with no rollback logic.

✂️

Split Tender

Split a transaction across multiple payment methods with automatic rollback on failure.

↩️

Refunds

Full or partial refunds for single and split-tender payments.

🏥

IIAS Payments

Inventory Information Approval System payments for HSA/FSA cards.

🔄

Payment Lifecycle

Full state machine reference — all payment statuses and transitions.

⚖️

Disputes

Handling chargebacks and dispute evidence submission.

---

FAQ

Q: Should I use webhooks or polling to track payment status?
Webhooks are strongly preferred — they provide near-real-time updates and reduce API load. Use polling as a fallback only if your infrastructure cannot receive webhooks.

Q: What happens if my server doesn't receive the webhook?
Poll GET v2/payments/{paymentId} with exponential backoff. Webhooks have a retry policy, but polling is a reliable safety net.

Q: Can I retry a failed payment with the same merchantTransactionId?
Yes, up to 5 times. After 5 attempts the ID is locked and a new one must be used.

Q: Can I use the Payments API alongside the CCG widget?
Yes. The widget handles the UI flow and creates a session; you use the Payments API for server-side operations like capture or refund after session completion.

Q: Where do I find the merchantTransactionId if I only have a session ID?
Call GET v2/sessions/{sessionId} — the payment details including merchantTransactionId are included in the session response.

---

Integration Checklist

• OAuth token obtained with merchant scope
• PaymentMethodId retrieved via wallet/session flow (no raw card numbers)
• merchantTransactionId is unique per transaction
• Webhook endpoint configured and verified for PAYMENT_SUCCEEDED / PAYMENT_FAILED events
• Fallback polling implemented for webhook delivery failures
• Error handling covers declined cards, duplicate IDs, and session expiry
• Tested in staging environment: https://api-stg.uhg.com/api/financial/commerce/nonprodcheckout/
• Split-tender rollback behavior verified (if applicable)