Authorize.Net

You are integrating Authorize.Net as a payment gateway into a [Django / Next.js / etc.] application.

## Setup
1. Create an Authorize.Net sandbox account at https://developer.authorize.net/hello-world/sandbox/ and a production merchant account (All-in-One) or a Gateway-Only account bonded to an existing merchant account.
2. From the Merchant Interface, collect three credentials and store them in environment variables — never hardcode:
   - `AUTHNET_API_LOGIN_ID` (Account → Settings → Security Settings → API Credentials & Keys)
   - `AUTHNET_TRANSACTION_KEY` (same screen — generate a new one and save it immediately, it cannot be retrieved later)
   - `AUTHNET_PUBLIC_CLIENT_KEY` (Account → Security Settings → Manage Public Client Key — this is the one used by Accept.js in the browser)
3. Add `AUTHNET_ENVIRONMENT` = `sandbox` or `production` and switch endpoints accordingly:
   - Sandbox: `https://apitest.authorize.net/xml/v1/request.api`
   - Production: `https://api.authorize.net/xml/v1/request.api`
4. Install the official SDK (e.g., `pip install authorizenet` for Python, `npm install authorizenet` for Node.js). Use the SDK rather than hand-rolling XML/JSON — Authorize.Net's API requires strict XML element ordering even when you send JSON.

## Recommended Integration: Accept.js (SAQ A-EP) or Accept Hosted (SAQ A)
For the lowest PCI scope and a modern flow, use Accept Hosted (iframe served from Authorize.Net) or Accept.js (your own form, client-side tokenization). Never submit raw PAN/CVV to your server.

### Accept.js flow
1. Load `https://jstest.authorize.net/v1/Accept.js` (sandbox) or `https://js.authorize.net/v1/Accept.js` (production) in your checkout page.
2. Build your card-entry form with `data-accept` attributes. Mark card fields so they are stripped before submission to your server.
3. On submit, call `Accept.dispatchData({ authData: { apiLoginID, clientKey }, cardData })`. Authorize.Net returns a single-use `opaqueData` payment nonce valid for 15 minutes.
4. Post the nonce (not the card data) to your server, then use the SDK to call `createTransactionRequest` with `payment.opaqueData` populated from the nonce.

### Server-side (Python example)
```python
from authorizenet import apicontractsv1
from authorizenet.apicontrollers import createTransactionController

merchant = apicontractsv1.merchantAuthenticationType(
    name=os.environ['AUTHNET_API_LOGIN_ID'],
    transactionKey=os.environ['AUTHNET_TRANSACTION_KEY'],
)

opaque = apicontractsv1.opaqueDataType(
    dataDescriptor='COMMON.ACCEPT.INAPP.PAYMENT',
    dataValue=nonce_from_client,
)
payment = apicontractsv1.paymentType(opaqueData=opaque)

tx = apicontractsv1.transactionRequestType(
    transactionType='authCaptureTransaction',
    amount=Decimal('20.00'),
    payment=payment,
    refId=internal_order_id,          # stamped into the transaction
)
request = apicontractsv1.createTransactionRequest(
    merchantAuthentication=merchant, transactionRequest=tx,
)
controller = createTransactionController(request)
controller.setenvironment(settings.AUTHNET_URL)
controller.execute()
response = controller.getresponse()
```

## Webhooks (migrate to v2 — v1 is decommissioned April 2026)
1. Create an endpoint on your server and register it under Account → Settings → Webhooks with the events you care about: `net.authorize.payment.authcapture.created`, `net.authorize.customer.subscription.cancelled`, `net.authorize.payment.refund.created`, etc.
2. Authorize.Net authenticates webhook delivery with HTTP Basic Auth (your API Login ID : Transaction Key, Base64-encoded) — validate this header on every request.
3. Verify the payload signature using the X-ANET-Signature header (HMAC-SHA512 of the body with your webhook signature key) — required on v2.
4. Return a 2xx quickly, then process asynchronously. Retry behaviour: Authorize.Net retries on 5xx.
5. Note the known 2026 issue: some webhook payloads have been missing the response code, amount, or transaction ID — always re-fetch the transaction by ID from the API to confirm final state rather than trusting the webhook body blindly.

## Recurring billing: ARB + CIM
- Use CIM (`createCustomerProfileRequest`) to store the card, then reference the customer/payment profile IDs in your app.
- Use ARB (`ARBCreateSubscriptionRequest`) to schedule recurring charges with interval, start date, total occurrences, trial period and trial amount. ARB batches run daily around 08:30 GMT.
- Listen for `net.authorize.customer.subscription.expiring`, `.suspended`, and `.cancelled` webhooks to keep your internal subscription state in sync.

## Security best practices specific to Authorize.Net
- Never ship the Transaction Key to the browser — only the Public Client Key is safe for client-side use.
- For UK/EU customers subject to PSD2 SCA, integrate Cardinal Commerce (or another payer-auth provider) in front of the gateway — Authorize.Net does not natively support 3DS1 or 3DS2.
- Enable Advanced Fraud Detection Suite (AFDS) filters: at minimum, hourly velocity, suspicious transaction, enhanced AVS handling, and IP blocking.
- Set a `refId` on every transaction equal to your internal order/invoice ID — this is the only reliable way to idempotently reconcile when a retry occurs.
- If you use Gateway-Only, request the full fee schedule from your MSP before going live — non-qualified surcharges and network assessments can push effective rates well above the headline number.

## Testing
- Use sandbox credentials and the sandbox endpoint. Test card numbers: `4111 1111 1111 1111` (Visa success), `4222 2222 2222 2222` (decline test), `6011 0000 0000 0012` (Discover).
- Test ARB behaviour by creating subscriptions with short (daily) intervals in the sandbox.
- Simulate webhook delivery using the AuthorizeNet/webhooks-postman-collection repo on GitHub.

## Common gotchas
- JSON elements must appear in the order documented in the API Reference — the server translates JSON to XML internally.
- Each Authorize.Net account is locked to a single currency. Multi-currency checkout requires multiple accounts routed by country.
- Authorize.Net does not natively split payments across multiple merchants — there is no Connect-style marketplace flow.
- The `refId` field is your idempotency lifeline. Use it.