billingHelp

Authorize.net

From a merchant account to live payments — API Login ID, Transaction Key, Signature Key, the webhook endpoint, eCheck, subscriptions (ARB) and settlement.

Accounts you need#

  • A merchant account and gateway from Authorize.net (directly or through a reseller or bank). Ask for eCheck.Net if you want US bank payments, and Automated Recurring Billing (ARB) for subscriptions.
  • A free sandbox account from developer.authorize.net for testing. It has its own login and keys.

Copy the keys#

Merchant Interface → Account → Settings (new interface: Account and API Settings) → Security Settings → API Credentials & Keys:

  1. API Login ID — shown on the page.
  2. Transaction Key — choose New Transaction Key. Authorize.net asks for a PIN sent by email. Generating a new key ends the old one, so do it when nothing else uses the account.
  3. Signature Key — choose New Signature Key, again with the PIN. It is 128 hexadecimal characters.

Paste all three into a new Authorize.net credential set with environment Test. Verify calls the merchant details, checks USD and reports whether eCheck is enabled and whether the account is in test mode.

Register the webhook#

Merchant Interface → Account → Settings → Business Settings → Webhooks → Add Endpoint:

  1. Endpoint URL — Authorize.net does not allow a query string, so every Authorize.net set uses the same address:
  1. Status Active, and select these events:
  • net.authorize.payment.authcapture.created
  • net.authorize.payment.authorization.created
  • net.authorize.payment.capture.created
  • net.authorize.payment.priorAuthCapture.created
  • net.authorize.payment.refund.created
  • net.authorize.payment.void.created
  • net.authorize.payment.fraud.held
  • net.authorize.payment.fraud.approved
  • net.authorize.payment.fraud.declined
  • net.authorize.customer.subscription.created
  • net.authorize.customer.subscription.updated
  • net.authorize.customer.subscription.suspended
  • net.authorize.customer.subscription.terminated
  • net.authorize.customer.subscription.cancelled
  • net.authorize.customer.subscription.expired
  • net.authorize.customer.subscription.failed
  1. Save. Deliveries are matched to your set by the Signature Key. Use one credential set per Authorize.net account.

Then Put in service (Test).

Enable what you sell#

  • Accept Hosted (the hosted payment form) needs no setting.
  • eCheck.Net must be enabled on the account; then tick US bank account on the product.
  • ARB must be enabled for subscriptions.
  • The Fraud Detection Suite may hold transactions for review. Held payments stay Processing until you approve or decline them in the Merchant Interface.

Test in the sandbox#

Use card 4111 1111 1111 1111, any future date, any CVV. Sandbox accounts can run in test mode, in which case transactions are not stored; turn test mode off in the sandbox's settings so that webhooks and refunds behave as in production.

Free trials sign up with a $1.00 authorization that is voided at once, so the buyer sees no charge. The first real charge comes when the trial ends.

Settlement, refunds and eCheck timing#

  • Card payments settle once a day at the batch cut-off time. Before that, a payment can only be voided in full. After settlement, partial and full refunds work.
  • eCheck payments stay Processing until settlement (1–3 business days). Authorize.net sends no webhook for settlement, so the hourly job payments.reconcile checks their status and marks them Paid or Failed.
  • Authorize.net does not report processing fees through its API: net equals gross for these payments, and reports mark them.

Go live#

  • [ ] Production API Login ID, Transaction Key and Signature Key in a live set.
  • [ ] Production webhook endpoint added and Active, with the same events.
  • [ ] Account in Live mode (not test mode).
  • [ ] Products switched to the live set.
  • [ ] One small real payment, voided the same day, and another refunded after settlement if you want to test both.

Common errors#

MessageFix
Webhook deliveries answer 409Two credential sets use the same Signature Key. Keep one set per account.
Webhook deliveries answer 400The Signature Key in the set is not the current one (a new key ends the old one).
Partial refund not possible yetThe payment has not settled; void it in full, or refund after settlement.
Hosted page says expiredThe buyer took more than 15 minutes; start a new checkout.

Technical details#

Credentials. Go to Merchant Interface → Account → Security Settings → API Credentials & Keys.

  • API Login ID.
  • Transaction Key: 16 characters, stored sealed. Generating a new key invalidates the old one.
  • Signature Key: 128 hex characters, stored sealed.

Verify calls getMerchantDetails. It checks USD and reports whether eCheck is enabled and whether the account is in test mode.

Webhook. Go to Account → Webhooks → Add Endpoint and paste https://encrypted.com/webhooks/authnet.php. Authorize.net does not allow a query string in webhook URLs, so every Authorize.net set shares this endpoint. Each delivery is matched to its set by the Signature Key, which means you must use one credential set per Authorize.net account; if two sets share a key, deliveries answer 409 and are logged. Select these events:

  • net.authorize.payment.authcapture.created, .authorization.created, .capture.created, .priorAuthCapture.created
  • net.authorize.payment.refund.created, .void.created
  • net.authorize.payment.fraud.held, .fraud.approved, .fraud.declined
  • net.authorize.customer.subscription.created, .updated, .suspended, .terminated, .cancelled, .expired, .failed

The check is X-ANET-Signature: sha512=<HEX>, the HMAC-SHA512 of the raw body. Authorize.net's samples key the HMAC with the Signature Key as text; some integrations hex-decode it first. Both forms are accepted, and both need the key.

One-time flow.

  1. getHostedPaymentPage returns a token.
  2. The buyer's browser lands on our own page, /pay/go/<checkout>, which posts the token to Accept Hosted. That page is the only one whose Content-Security-Policy allows a form to post there. Tokens expire after 15 minutes; an older checkout shows expired.
  3. The order's invoiceNumber is the last 20 characters of our checkout id, and the description carries the full id.

Cards are marked Paid on the auth-capture webhook. eCheck payments stay Processing until settlement. Authorize.net sends no webhook for settlement or returns, so the payments.reconcile job (hourly) asks for the transaction status: settledSuccessfully means Paid; returnedItem, voided or declined means Failed, and the buyer is emailed. Transactions held by the fraud filters stay Processing until they are approved or declined.

Subscriptions (ARB).

  1. The hosted transaction charges the first period and creates a customer payment profile (profile.createProfile).
  2. On its webhook an ARB subscription is created from that profile. It starts one interval later (quarterly = 3 months, annual = 12 months).
  3. Creation is idempotent: if the profile already has a subscription, it is reused rather than duplicated.
  4. ARB renewals arrive as auth-capture webhooks that carry the subscription id.
  5. A declined renewal, or subscription.suspended, means Past due. Cancelled, terminated or expired means Canceled.

Free trial.

  1. The sign-up is a $1.00 authorization only, a card check that is voided straight away, so the buyer is never charged.
  2. ARB starts when the trial ends. ARB's trialOccurrences counts whole intervals, so a 14-day trial is a later start date instead.
  3. Trial sign-ups are card-only.

Refunds.

  • Before settlement, usually within 24 hours, only a void of the full amount is possible. A partial refund is refused with an explanation.
  • After settlement, refundTransaction is sent with the last four digits of the card or account taken from the transaction details.
  • Both are confirmed by the void.created or refund.created webhook.

Fees. The API does not expose processing fees. These payments are recorded with fee_known = 0 (net = gross) and flagged as such in insights.