Skip to main content

Transactions

Process credit card and ACH payments, issue refunds, and manage transaction lifecycle through the PayConnect API.

Overview​

PayConnect supports several transaction types:

ActionDescription
saleCharge a stored payment method immediately
authAuthorize an amount without capturing
authcompleteCapture a previously authorized transaction
refundRefund a completed transaction (full or partial)
voidVoid an authorized transaction before capture

Process a Payment​

Charge a customer's stored payment method (account vault):

curl -X POST https://dev.payconnect.us/api/trx/payment \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "x-correlation-id: YOUR_CORRELATION_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_api_id": "ct_abc123",
    "transaction_amount": 50.00,
    "order_id": "ORD-2026-001",
    "account_vault_id": "av_xyz789",
    "type": "av",
    "description": "Monthly service fee"
  }'

Request Fields​

FieldTypeRequiredDescription
contact_api_idstringYesCustomer contact ID from the payment processor
transaction_amountnumberYesAmount in dollars (e.g., 50.00)
order_idstringYesYour order reference ID
account_vault_idstringNoStored payment method ID (required when type is "av")
typestringNoSet to "av" to charge a stored payment method
descriptionstringNoTransaction description

POST /trx/payment returns 200 with one of two shapes depending on type. For a stored-payment-method sale (type: "av") the response is { "transaction": { ... } } with the completed transaction record. For any other value, the response is a hosted-payment-page URL string the payer opens to complete the payment.

Authorize and Capture​

Split a transaction into two steps — authorize first, capture later.

Step 1: Authorize​

curl -X POST https://dev.payconnect.us/api/trx/auth \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "x-correlation-id: YOUR_CORRELATION_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_api_id": "ct_abc123",
    "transaction_amount": 100.00,
    "account_vault_id": "av_xyz789",
    "order_id": "ORD-2026-002",
    "description": "Pre-authorization for service"
  }'

Step 2: Capture​

curl -X PUT https://dev.payconnect.us/api/trx/auth/TRX_ID \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "x-correlation-id: YOUR_CORRELATION_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "authcomplete",
    "transaction_amount": 100.00
  }'

Void an Authorization​

If you need to cancel an authorization before capture:

curl -X PUT https://dev.payconnect.us/api/trx/auth/TRX_ID \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "x-correlation-id: YOUR_CORRELATION_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "void"
  }'

Refund a Transaction​

Full Refund​

Refund the entire transaction amount:

curl -X POST https://dev.payconnect.us/api/trx/refund/TRX_ID \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "x-correlation-id: YOUR_CORRELATION_ID" \
  -H "Content-Type: application/json"

Partial Refund​

Refund a specific amount:

curl -X POST https://dev.payconnect.us/api/trx/refund/TRX_ID \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_amount": 25.00
  }'

Blind Refund​

Refund to a payment method without referencing the original transaction. This endpoint returns 201 Created (as does terminal transaction create, POST /trx); the referenced full and partial refunds above return 200.

curl -X POST https://dev.payconnect.us/api/trx/refund \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "x-correlation-id: YOUR_CORRELATION_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_api_id": "ct_abc123",
    "transaction_amount": 25.00,
    "account_vault_id": "av_xyz789",
    "order_id": "REFUND-001"
  }'

List Transactions​

Retrieve transactions with optional date filtering. Pagination is zero-based: the first page is page=0 (the default). pageSize defaults to 25 and is clamped to 1–100.

curl -X GET "https://dev.payconnect.us/api/trx?page=0&pageSize=25&start=2026-03-01&end=2026-03-31" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "x-correlation-id: YOUR_CORRELATION_ID"

Response:

{
  "data": [
    {
      "_id": "65a1b2c3d4e5f67890123456",
      "action": "sale",
      "transaction_amount": 50.00,
      "payment_method": "cc",
      "status": "completed",
      "last_four": "4242",
      "order_id": "ORD-2026-001",
      "createdAt": "2026-03-15T10:30:00.000Z"
    }
  ],
  "total": 1,
  "page": 0,
  "pageSize": 25
}

Get Transaction Details​

By Transaction ID​

curl -X GET https://dev.payconnect.us/api/trx/transaction/TRX_ID \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "x-correlation-id: YOUR_CORRELATION_ID"

By Order ID​

curl -X GET https://dev.payconnect.us/api/trx/order/ORD-2026-001 \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "x-correlation-id: YOUR_CORRELATION_ID"

Response (abbreviated — the full response also includes additional settlement and line-item fields such as terminal_id, line_items, info, batch, transaction_batch_id, and customFields):

{
  "transaction_id": "trx_abc123",
  "status": "completed",
  "transaction_amount": 50.00,
  "order_id": "ORD-2026-001",
  "action": "sale"
}

Rerun a Failed Transaction​

Retry a previously failed transaction:

curl -X POST https://dev.payconnect.us/api/trx/rerun/TRX_ID \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "x-correlation-id: YOUR_CORRELATION_ID" \
  -H "Content-Type: application/json"

Transaction Lifecycle​

Sale:      Created → Completed / Failed
Auth:      Created → Authorized → Captured (authcomplete) / Voided
Refund:    Created → Completed / Failed
warning

Refunds can only be processed on completed transactions. Attempting to refund a pending or failed transaction will return an error.

Next Steps​