How payments work¶
When your application holds the payment method, a payment moves through three stages: collect the details in the browser, charge them from your server, then let the processor settle them.
1. Collect the details¶
The JS SDK renders the card or bank fields in an iFrame that Aptean hosts. The card number never enters your page, your server or your logs. You get a short-lived, single-use token back. Style the iFrame to match your page.
2. Optionally save them¶
To charge the same card or account again later, turn the token into a
saved payment method. Both a token and a saved payment method are passed to
createPayment as paymentMethodId, so the payment code is the same either way.
3. Charge¶
createPayment charges the payment method. It needs an
idempotency key. By default it captures immediately. Set
immediateCapture: false to pre-authorise and capture later, within
7 days.
4. Follow it through¶
The response tells you Aptean Pay accepted the request. payment.status tells you what happened
to the money: PENDING, COMPLETED, FAILED or CANCELED. See
Payment status.
5. Reverse it if needed¶
| Situation | Use |
|---|---|
| Pre-authorised, not captured | Cancel |
| Captured card payment, not yet settled, merchant has voids enabled | Void |
| Settled, or ACH | Refund |
Card or ACH?¶
| Card | ACH (US bank account) | |
|---|---|---|
| Captured with | Card iFrame | Bank iFrame |
Typical result of createPayment |
COMPLETED within seconds |
PENDING for days while the debit clears |
| Void before settlement | Yes, if enabled for the merchant | No - refund instead |
| Refund | Once COMPLETED |
Once COMPLETED |
| How often to check status | A few times in the first minute | Once a day |
Design your order flow so that an ACH payment sitting in PENDING for several days is normal and
does not look like a failure to the payer or the merchant.
Not holding the payment method?¶
If you would rather the payer enters their details on an Aptean page, two flows avoid the iFrame entirely:
- Payment requests - invoice the payer; they pay in the payer portal when they choose.
- Hosted checkout - redirect the payer to an Aptean-hosted payment page during checkout.