Pre-authorise and capture

A pre-authorisation reserves funds without taking them. You capture later — when the order ships, the work is done, or the final amount is known.

This is a two-step version of Create a payment. Everything on that page applies; the difference is immediateCapture.

Step 1 — pre-authorise

Exactly the createPayment call, with immediateCapture set to false:

{
  "input": {
    "paymentMethodId": "<token or saved payment method id>",
    "amount": 1250,
    "currency": "USD",
    "immediateCapture": false,
    "riskMetadata": {
      "address": { "postalCode": "30328", "country": "US" },
      "phone": { "countryCode": "1", "number": "5551234567" },
      "lineItems": []
    }
  }
}

The payment comes back PENDING with a pending reason of Payment pending capture — funds are held, not taken.

Store payment.id. Without it you can neither capture nor cancel, and the hold will simply expire.

Warning

You have 7 days to capture. Aptean Pay refuses a capture more than 7 days after authorisation, measured from when the authorisation was created: Unable to capture payment, the payment was authorized more than 7 days ago. This is a hard limit in Aptean Pay, independent of how long the card issuer would have held the funds. After that you must take a fresh payment.

Step 2 — capture

Headers

The standard three. capturePayment does not require an idempotency key.

{
  "x-aptean-apim": "<your api key>",
  "x-aptean-tenant": "<your tenant id>",
  "x-aptean-tenant-secret": "<your tenant secret>"
}

The mutation

mutation CapturePayment($input: CapturePaymentInput!) {
  capturePayment(input: $input) {
    code
    message
    error
    payment {
      id
      status
      failureReason
    }
  }
}

Capture the full amount

Pass only the payment id:

{
  "input": {
    "paymentId": "<the pre-authorised payment id>"
  }
}

Capture a smaller amount

Pass amounts to capture less than was authorised — useful when part of an order ships, or the final total came in under the estimate:

{
  "input": {
    "paymentId": "<the pre-authorised payment id>",
    "amounts": {
      "amount": 800,
      "currency": "USD"
    }
  }
}

Warning

You can capture less than you authorised, never more. If the final amount is higher, capture the authorised amount and take a second payment for the difference — or cancel and re-authorise before you ship.

Other capture fields

Field	Type	Notes
invoiceNumber, orderNumber, customerPONumber	String	Set at capture time if you did not know them at authorisation.
customData	JSON	Arbitrary key–value pairs.

The response

{
  "data": {
    "capturePayment": {
      "code": "SUCCESS",
      "message": "Payment captured.",
      "error": null,
      "payment": {
        "id": "300f5a49-68f0-44a0-8f73-d2f42ced4a90",
        "status": "COMPLETED",
        "failureReason": null
      }
    }
  }
}

Statuses you can get on a SUCCESS capture:

Status	Meaning
COMPLETED	Captured.
PENDING	Still processing. Check again shortly.
FAILED	The capture failed — read failureReason.

Common failures

These are the messages Aptean Pay actually returns:

Message	Cause
Unable to capture payment, only payments that are pending with 'pending_capture' can be captured. Current status is …	The payment is not an uncaptured pre-authorisation — most often it was created with immediateCapture: true, or has already been captured or cancelled.
Unable to capture payment, the payment was authorized more than 7 days ago.	Past the 7-day capture window. Take a fresh payment.
Unable to capture payment, exceeding authorized amount.	amounts.amount is greater than the amount authorised.
Unable to capture payment, currency does not match with the authorized payment currency.	amounts.currency differs from the authorisation. It must match.
Unable to capture payment, payment not found.	Wrong paymentId, or the wrong environment.
Unable to capture payment, payment method not found	The underlying payment method has since been deleted.
Cannot perform partial capture, feature is not enabled	Partial capture is not enabled for your tenant. Capture the full amount, or ask Aptean to enable it.

Changed your mind?

If you are not going to capture, cancel the payment to release the hold rather than leaving it to expire. Leaving holds to lapse is poor treatment of the payer's available balance and generates support tickets.