Payment status¶

A successful mutation means Aptean Pay accepted your instruction. It does not always mean the money has moved. This page is about telling the difference.

Two different results¶

Every mutation returns a code, and most also return the object they acted on with its own status. They answer different questions.

Field	Question it answers	Values
`code`	Did Aptean Pay accept my request?	`SUCCESS`, `PENDING`, `ERROR`
`payment.status`	What happened to the money?	`PENDING`, `COMPLETED`, `FAILED`, `CANCELED`

Warning

code: "SUCCESS" with status: "PENDING" is a completely normal and very common response. If your integration treats SUCCESS as "paid", it will report money you do not have. Always read payment.status.

Payment statuses¶

These are the only four statuses a payment can have:

Status	Meaning	What to do
`PENDING`	In flight. Awaiting capture, awaiting the processor, or an ACH debit still clearing.	Check again later. Read `pendingReason` / `pendingReasonCode` to find out which.
`COMPLETED`	Done. The payment succeeded.	Fulfil. This is the only status that means paid.
`FAILED`	It did not work.	Read `failureReason`. Tell the payer; collect a different payment method.
`CANCELED`	Cancelled or voided via `cancelPayment`: a pre-authorisation that was released, or a card payment voided before it settled. No money moved. Any payment requests it paid are open again.	Read `cancelReason`. A voided payment has no refund record.

Why a payment is pending¶

pendingReason distinguishes the cases. The two you will see most:

Payment pending capture — a pre-authorisation waiting for you to capture it. It will not progress on its own, and you have 7 days.
Still processing — with the processor. For a card this resolves in seconds. For ACH it can take days, and it can still end in FAILED.

Warning

Do not release goods against a PENDING ACH payment. An ACH debit can fail after the fact — insufficient funds, a closed account, or the payer disputing it — and by then you have shipped.

Extended statuses¶

Refunds and disputes are tracked separately from the payment's own status, because a refunded payment is still a COMPLETED payment. The payments query accepts extendedPaymentStatus to filter on them:

Value	Meaning
`REFUNDED`	Fully refunded.
`PARTIALLY_REFUNDED`	Some of it has been refunded.
`DISPUTED`	The payer has disputed it with their bank.

Checking a payment¶

There is no webhook. Aptean Pay will not call your server when a payment changes. You find out by asking.

Query by the payment.id you stored:

query {
  payments(
    id: "<your payment id>"
    orderBy: { field: TIMESTAMP, direction: DESC }
  ) {
    nodes {
      id
      amount
      currency
      status
      pendingReason
      failureReason
      cancelReason
    }
  }
}

Note

orderBy is required on payments even when you are fetching a single id. The only supported field is TIMESTAMP.

Payments against a payment request¶

To see everything paid against a payment request:

query {
  paymentRequests(orderBy: { field: TIMESTAMP, direction: DESC }, first: 20) {
    nodes {
      id
      referenceNumber
      payments {
        id
        status
        failureReason
        cancelReason
        pendingReason
      }
    }
  }
}

Useful filters on `payments`¶

startDate / endDate with dateRangeType, status, extendedPaymentStatus, amountRange, customerId, paymentMethodId, batchId, payoutId, and queryString. Paging is first/after and last/before.

How to poll well¶

Since there are no webhooks, polling is the mechanism. Do it considerately:

Only poll what is pending. Track your PENDING payments and query those. Do not sweep your whole history.
Back off. Cards settle in seconds — a few checks over the first minute is plenty. ACH takes days, so check it daily, not every thirty seconds.
Stop. COMPLETED, FAILED and CANCELED are terminal. Nothing further will happen.
Never poll from the browser. It needs your tenant secret. This is server-side work.

Settlement status¶

Alongside status, every payment has settlementStatus and settledTimestamp:

`settlementStatus`	Meaning
`NONE`	Nothing to settle: an uncaptured pre-authorisation, a payment paid entirely with credit, or a payment made before settlement tracking existed.
`PENDING`	Captured and waiting for the processor's settlement batch, normally that night. A card payment in this state can be voided if the merchant has voids enabled.
`SETTLED`	Settled at the processor. It can only be refunded.

Reconciliation¶

The status tells you what Aptean Pay believes. It does not tell you the money has landed in your bank account — that is payouts, which are separate and visible in the merchant portal.

A voided payment ends CANCELED with no refund against it, so count voids by status, not by refunds.

If you are reconciling against your own ledger, set invoiceNumber, orderNumber and customerPONumber on every payment you create. They are the only fields that tie an Aptean Pay payment back to a document in your system, and you cannot add them retrospectively.