Before you integrate¶

Most integration problems come from decisions made in the first week. This page lists them, so you can make them deliberately before any code exists.

1. Who holds the payment method?¶

This decides which half of the API you build against.

If...	You build	Start with
Your application charges the payer (checkout in your UI, card on file, recurring billing)	Payments	How payments work
The payer decides when to pay an invoice you raised	Payment requests	Create a payment request
You want no payment UI at all	Hosted checkout	Hosted checkout

Many integrations use more than one: an ERP typically raises payment requests for invoices and takes card-on-file payments. Choose your features walks through the options.

2. Where does each call run?¶

Every API call runs on your server. The tenant secret authorises the call, and anything a browser or mobile app can read is public. The only Aptean Pay code that runs in the browser is the JS SDK, and it does not need the secret.

This also keeps your PCI scope small. Card numbers are typed into an Aptean-hosted iFrame and never reach your page or your server. Do not collect card numbers yourself.

3. How will you store credentials?¶

You get a separate API key, tenant ID and tenant secret per environment, and per merchant if you serve several. Plan for:

Configuration that switches the API host, the JS SDK URL and the credentials together. See Environments and URLs.
A secret store, not source code, for the tenant secret.
A way to hold one set of credentials per merchant if your product is multi-tenant.

4. How will you know a payment finished?¶

Aptean Pay has no webhooks. It does not call your system when a payment completes, fails or settles. You read the payment.

Decide up front:

Which records you will poll, and how often. Card payments resolve in seconds; ACH takes days. See Payment status.
What your UI shows while a payment is PENDING. For ACH this is normal for several days.

5. How will you avoid charging twice?¶

Networks fail mid-request. If a createPayment call times out, you do not know whether the payer was charged. createPayment and createRefund require an idempotency key for this reason.

Generate the key when you create the order or refund in your system and store it with that record, so a retry after a crash reuses it. See Idempotency and Resilience and retries.

6. How will you reconcile?¶

Every payment should point back to something in your system. Set invoiceNumber, orderNumber and customerPONumber on every payment you create. They cannot be added later. Store the Aptean Pay payment.id on your own record as well.

7. What happens when something is reversed?¶

Decide which reversal your users can trigger, and from where:

	When	Money moved?
Cancel	A pre-authorisation you will not capture	No
Void	A card payment that has not settled, for merchants with voids enabled	No
Refund	A completed payment	Yes, back to the payer
Credit memo	Credit to use against a future payment	No

If your code already "tries to cancel, and refunds if that fails", read Cancel or void a payment first. That flow starts voiding once a merchant has voids enabled.

8. Get the details right¶

Amounts are integers in minor units. 1250 is $12.50.
Pre-authorisations expire. Capture within 7 days or the capture is refused.
Partial refunds have a floor of 100 minor units.
Test data is environment-specific. Test numbers only work in staging, and real cards only work in production.

Checklist¶

Chosen payments, payment requests, hosted checkout, or a mix
All API calls run server-side; the tenant secret is in a secret store
Host, SDK URL and credentials come from per-environment configuration
An idempotency key is generated and stored with each payment and refund
A polling plan for PENDING payments, with ACH treated as slow
invoiceNumber / orderNumber / customerPONumber set on every payment
Reversal flows decided (cancel, void, refund, credit memo)
Staging credentials requested. See Onboarding