API changelog and change policy · Paybilt Developers

This changelog records API and documentation changes that affect merchants. Only operations in the authoritative OpenAPI reference are merchant self-service operations. Internal and dashboard operations are context only; merchants cannot call them unless Paybilt adds them to that reference.

Change notice policy

Paybilt provides at least 90 calendar days' public notice before a merchant-impacting breaking change or deprecation takes effect. During that period, merchants can continue using the existing API while they update and test their integrations.

Each notice must identify:

The announcement and effective dates.
The affected API, method, and path.
Whether the change is additive, a deprecation, breaking, documentation-only, or corrective.
The requests or responses merchants must change.
The replacement operation or fields and the steps required to migrate.
The migration steps that can be tested in the sandbox, when published.

Paybilt can release additive changes that do not alter existing requests or responses without the 90-day notice window. The changelog still records them when merchants can use a new operation, field, or status. Paybilt can publish documentation corrections immediately when the corrected text matches the existing OpenAPI reference.

Paybilt may shorten the minimum notice window only for an actively exploited security issue, a legal or regulatory obligation, or a material risk to funds or platform integrity. When disclosure is safe and permitted, the changelog must state why the window changed, which merchant requests or responses are affected, what merchants must do, and the revised effective date.

Sandbox guarantees cover only scenarios explicitly published in the documentation. The presence of an internal or dashboard operation does not make it available in the sandbox or merchant API.

Required entry fields

Every merchant-impacting entry includes:

Classification
Status
Announcement date
Effective date
Affected operations
Merchant impact
Migration
Sandbox coverage

2026-10-19 — Hosted Checkout: when Checkout saves a returning shopper's details

Classification: Documentation-only
Status: Published
Announcement date: 2026-10-19
Effective date: 2026-10-19
Affected operations: The customer.email and customer.billing_info.phone fields on Create Checkout Session.
Merchant impact: No API behavior changed. The guide said Checkout can save a shopper's details to a checkout profile, but not when it does. After an approved payment, Checkout saves or updates the profile when the shopper verified with a one-time code, or when the shopper is new and you sent their phone on the session. After an approved payout, it always does. Otherwise the shopper checks out as a guest, and nothing is saved.
Migration: None. Prefill only contact details the shopper has verified with you: for a new shopper, a phone you send lets Checkout save their details without a one-time code.
Sandbox coverage: No new sandbox scenarios.

See Returning customers and saved details.

2026-10-19 — Hosted Checkout: only the session's `convenience_fee` is charged, and `refund_claimed` marks a completed refund

Classification: Corrective
Status: Released
Announcement date: 2026-10-19
Effective date: 2026-10-19
Affected operations: The convenience_fee field on Create Checkout Session, Refund Session, and the refund_claimed and refund_failure webhooks.
Merchant impact: Documentation only. Hosted Checkout charges only the convenience_fee you send on the session. The guide said a fee configured for a payment method on your site could also apply when you left the field out or sent 0, but sites used for Hosted Checkout don't have one. Checkout sends refund_claimed for every refund method once the refund is approved or claimed, not only when a customer claims it.
Migration: To charge a fee, send convenience_fee on the session; to charge none, leave it out or send 0. Treat a session that becomes refunded or partial_refund, with refund_claimed, as a completed refund.
Sandbox coverage: No new sandbox scenarios.

See Convenience fees and Refund a Checkout session.

2026-10-19 — Gateway: ACH is for payouts only, and RTP payouts are no longer available

Classification: Corrective
Status: Released
Announcement date: 2026-10-19
Effective date: 2026-10-14; ACH payout account numbers of up to 17 digits 2026-10-16
Affected operations: Create ACH Payout, ACH payments (POST /api/v2/payment/ach/), and RTP payouts (POST /api/v2/payout/rtp/).
Merchant impact: ACH payments and RTP payouts weren't available on any production site, and both routes now return HTTP 404. ACH payouts pay an individual's US bank account, with the bank account at the top level of the request, and accept account numbers of 1 to 17 digits, up from 12. The company, account_info, transaction_descriptor, and same_day fields documented before don't apply to ACH payouts, and a request that includes company returns 1168.
Migration: Send ACH payouts with encrypted_account_number, rsa_key_id, routing_number, and account_type (CHECKING or SAVINGS) at the top level, and identify the recipient with first_name and last_name. Use service_level instead of same_day.
Sandbox coverage: No new sandbox scenarios.

See ACH payouts.

2026-10-19 — Checkout SDK: verification flags can only keep or turn off your site's checks

Classification: Corrective
Status: Released
Announcement date: 2026-10-19
Effective date: 2026-10-19
Affected operations: The cvv_verification, avs_verification, and 3ds_verification claims in the Checkout SDK session token.
Merchant impact: Documentation only. The guide said these flags turn checks on, but they can't add a check. true keeps a check your site has on and fails initialization with 400 invalid_request when your site has it off, false turns the check off for the session, and an omitted 3ds_verification uses your site's setting.
Migration: Send true only for checks your site has on for the card transaction type, or ask Paybilt to turn the check on for your site.
Sandbox coverage: No new sandbox scenarios.

See Card verification flags.

2026-10-19 — Gateway: Cancel Transaction rejects what it can't cancel, `currency_code` reports the processed currency, and site blacklists cover payouts

Classification: Corrective
Status: Released
Announcement date: 2026-10-19
Effective date: 2026-10-14; Cancel Transaction 2026-10-16
Affected operations: Cancel Transaction, the currency_code field on Gateway create requests and responses, and payment and payout creates checked against your site blacklist.
Merchant impact: Cancel Transaction now returns HTTP 400 for a transaction it can't cancel; before, it returned 200 and the transaction never changed. Create responses report the currency Paybilt processed the transaction in, not the currency_code you sent. Your site blacklist now blocks payouts as well as payments, applies whether or not blacklist_enabled is on, and no whitelist overrides it.
Migration: Handle 1801 and 1802 from Cancel Transaction, and read errors as a list. Take the currency from the response, not your request. Remove customers from your site blacklist if they should still receive payouts.
Sandbox coverage: No new sandbox scenarios.

Details

Only Interac e-Transfer request-money and send-money transactions and bill payments in pending, sent, or confirming can be cancelled, when the bank processing them supports it. ACH transactions return 1175, other methods return 1801, and a transaction whose bank hasn't returned a reference yet returns 1802. See Cancel an eligible transaction and Resolve cancellation errors.
A currency_code you send is ignored. Create responses, refunds, and callbacks report USD for ACH, RTP, Reward Card payouts, and USD sites, and CAD for everything else. Card 3-D Secure authenticates in the same currency. See Amounts, fees, and currency.
Refunds, captures, and chargebacks aren't checked against your site blacklist. A new 10-digit North American phone number, or an 11-digit one that starts with 1, is stored in E.164 format, such as +14165550123, and lookup and removal match a number with or without +1. blacklist_enabled now only turns on the blacklist operations.

2026-10-19 — Hosted Checkout sessions expire with a webhook, and failure screens link to `failed_return_url`

Classification: Additive
Status: Released
Announcement date: 2026-10-19
Effective date: 2026-10-13
Affected operations: Hosted Checkout sessions created with Create Checkout Session, the session_expired webhook, and the hosted page's failure and expired screens.
Merchant impact: A session that passes its expires_at time now moves to expired, and Checkout sends session_expired. Before, only an unclaimed Interac e-Transfer payout did. When a session ends with a final status that isn't approved, the failure screen now shows a "Return to merchant name" button that goes to failed_return_url; before, the hosted page never used it.
Migration: Handle session_expired in your Checkout webhook receiver, and send a new first udfs value when you create a new session for the order. Set failed_return_url to a page that doesn't assume the payment succeeded; without it, the button goes to return_url.
Sandbox coverage: No new sandbox scenarios.

Details

Within about 15 minutes after expires_at, Checkout moves a pending, processing, or processing_soft session to expired and sends session_expired. An Interac e-Transfer request the shopper hasn't completed is cancelled first. A session whose payment or payout can no longer be cancelled keeps its status. See Session expiry and Checkout webhooks.
Opening an expired session's link shows "This checkout link has expired", with a button to return_url or your site URL. Failures the shopper can retry still show Try again. See Return behavior and Failure screens.

2026-10-19 — Hosted Checkout reference corrections: donations, legacy card routes, and payout events

Classification: Corrective
Status: Released
Announcement date: 2026-10-19
Effective date: 2026-10-19
Affected operations: Hosted Checkout Create Checkout Session and draft sessions, PUT /checkout-session/donation-amount, POST /sdk/credit-card, POST /sdk/pre-auth, and Checkout payout webhooks.
Merchant impact: No API behavior changed. Donation sessions haven't launched, so the guides and the API reference no longer describe them: the donation session type, donation_config, appearance, metadata, and PUT /checkout-session/donation-amount are gone. POST /sdk/credit-card and POST /sdk/pre-auth are no longer listed, because only an older SDK that's being retired calls them. The webhook catalog no longer lists payout_initiated or payout_approved, which Checkout never sends.
Migration: Don't create donation sessions until Paybilt announces them. Use a documented SDK, such as the Checkout SDK, rather than calling the card routes directly. Treat payout_claimed as the completed payout.
Sandbox coverage: No new sandbox scenarios.

Details

An Interac e-Transfer payout sends payout_request_approved, payout_sent, payout_claimed, and session_complete, in that order. A payout request that fails before any money is sent returns the session to pending with a Try again button; an e-Transfer that fails, is declined, or is cancelled after it was sent cancels the session. See Payout sessions.
The preferred flag doesn't choose the method the hosted page shows first; your site's preferred-method setting does. It still decides whether the e-Transfer checks run at creation. See Method order.
The 25,000 CAD e-Transfer cap excludes tax and runs only at creation, so tax can take a session over it, and a payment rejected for that reason shows a generic failure screen. See Interac e-Transfer in Checkout.

2026-10-13 — Hosted Checkout rejects per-method fees and wallet subscriptions, and closes returned payouts

Classification: Breaking
Status: Released
Announcement date: 2026-10-13
Effective date: 2026-10-13
Affected operations: Hosted Checkout Create Checkout Session and session updates, wallet payments on the hosted page, and hosted payout sessions and their webhooks.
Merchant impact: Two kinds of request that Checkout used to accept now fail with 422: a session_methods entry with its own convenience_fee, and a subscription session that lists apple_pay or google_pay. Both behaved incorrectly before. The per-method fee could be charged to a card without being shown to the shopper, and a wallet payment in a subscription session charged once and never created the subscription. A returned payout now closes its session instead of reopening it for another claim. These changes took effect without the 90-day notice window because the earlier behavior could charge shoppers a fee they weren't shown, start subscriptions that never renewed, or pay a recipient twice.
Migration: Remove convenience_fee from session_methods entries and set the fee once in the session-level convenience_fee. Don't list apple_pay or google_pay in subscription sessions; offer credit_card, digital_cheque, or etransfer_request_money instead. After a returned payout, create a new payout session to pay the recipient again.
Sandbox coverage: No new sandbox scenarios.

Details

Set fees with the session-level convenience_fee only. A per-method fee fails with 422, and the error message reads Per-method convenience_fee is not supported; use the session-level convenience_fee. See Hosted Checkout.
Subscription sessions can't list wallets. The request fails with 422, with a message such as apple_pay is not a valid subscription method. See Hosted Checkout and Wallet payments.
A returned payout sets the session to failed for direct_deposit and instant_direct_deposit, and to cancelled for every other method. A failed, declined, or cancelled payout still returns the session to pending so the recipient can claim again, except for etransfer_send_money, which moves to cancelled. A session that's already final is never reopened. See Payout sessions and Checkout webhooks.

2026-10-13 — Corrections to Gateway callbacks, e-Transfer limits, and payouts

Classification: Corrective
Status: Published
Announcement date: 2026-10-13
Effective date: 2026-10-13
Affected operations: Gateway callbacks and the dashboard resend; Interac e-Transfer creates; Bill Payment, Visa Direct and Mastercard Send, and Reward Card payouts; currency_code in create responses; saved-card purchases, pre-authorizations, and card verification.
Merchant impact: No API behavior changed. Paybilt's Gateway team answered the questions our earlier corrections left open, and we updated the guides and API reference to match. If you built from the earlier text, you may run fulfillment twice for a resent callback, or wait on a transaction that won't finish.
Migration: If you de-duplicate Gateway callbacks on stage, switch to txn, tx_action, and status. If you keep an 8007 transaction open waiting for it to finish, create a new transaction instead.
Sandbox coverage: No new sandbox scenarios.

Gateway

De-duplicate callbacks on txn, tx_action, and status, and make each update idempotent. A resent delivery arrives with a new stage, so the key the guides recommended, txn plus stage, lets a resend run fulfillment again. See Gateway webhooks and callbacks.
A transaction blocked with pl_error is final, including the pending-transaction limit 8007. To take the payment, create a new transaction with a new udfs[0]. Real-Time Deep Integration previously said an 8007 flow could still finish. See Interac e-Transfer.
A Bill Payment is complete at tx_action=payout with status=approved, which means the bank accepted the payment. No settlement status follows, and the callback code 5104 isn't sent. See Bill payments.
The Visa Direct and Mastercard Send process call ignores ntf_url, udfs, the amount, and customer details; they come from the create call. See Card payouts.
After a Reward Card pg_error, the API can't tell you whether the card was loaded. Give Paybilt support the txid before you pay the recipient again. See Reward cards.
Reward Card payouts report currency_code as USD, like ACH, RTP, and USD sites. Other transactions use CAD, and their create response echoes the currency_code you sent. See Amounts, fees, and currency.
A saved-card purchase or pre-authorization needs the email the card was saved under, and a different email returns 1131. Card verification can leave out email, and Paybilt looks the card up within your site. The API reference previously said that leaving out email always returns 1131. See Use a stored card.

2026-10-08 — Corrections to webhooks, callbacks, Checkout SDK events, and e-Transfer

Classification: Corrective
Status: Published
Announcement date: 2026-10-08
Effective date: 2026-10-08
Affected operations: Hosted Checkout sessions, session tokens, and webhooks; Checkout SDK callbacks and configuration, and the classic SDK events; Gateway Interac e-Transfer, Visa Direct and Mastercard Send payouts, merchant auth tokens, reports, statements, and callbacks; and the Gateway sandbox tools.
Merchant impact: No API behavior changed. We corrected guides that described behavior differently from how Paybilt handles it, and corrected the API reference to match. If you built from the earlier text, you may be handling some webhooks, callbacks, or errors incorrectly, and some e-Transfer creates may be rejected.
Migration: Check your integration against the corrections below. Most change how you handle results. The e-Transfer udfs requirement and the card payout process call change how you build requests.
Sandbox coverage: No new sandbox scenarios. The e-Transfer sandbox recipes are corrected; see the Interac e-Transfer corrections below.

Hosted Checkout and Checkout SDK

Answer Checkout webhooks with 200 within 5 seconds. Checkout retries only when connecting times out or the connection drops mid-request. A refused connection, a slower response, or any status other than 200 isn't retried, so after an outage, list deliveries with Get Callbacks and resend missed ones with Trigger Webhook. See Checkout webhooks.
payment_status_updated, payout_initiated, and payout_approved aren't currently sent; handle payout_claimed instead. A session that reaches its expiry time sends no event, and session_opened can arrive more than once per session. See Checkout webhooks.
On events driven by a payout status change, merchant_sid can hold an identifier other than your site ID, so match them by session_id. Automatic deliveries don't carry X-Transaction-ID; read session_details.transaction_details instead.
Create Checkout Session returns no session token. If short_url is an empty string, use url. Checkout ignores support_url and support_email sent at creation; the support link comes from your site settings. See Hosted Checkout.
A superseded session token stays valid for 30 seconds by default, not 10. See Checkout authentication.
In the Checkout SDK, onReady also fires after a failed initialization, right after onError. Enable your Pay button only if no onError came first. See Checkout SDK configuration.
The SDK form language comes only from the session token, so a remount can't change it. In React, useCheckoutSDK() connects only to a checkout that mounted before the calling component rendered. See React.
Gateway callbacks and reports show the SDK's metadata and config.udfs as key:value strings in udfs. See Checkout SDK configuration.
In the classic SDK, dispatch OneClickReload after OneClickDestroy before you start a new payment. The SDK then dispatches OneClickInit again, so keep that listener registered. See One-Click SDK (classic).
The hosted and SDK checkouts show Apple Pay in supported browsers besides Safari, such as Chrome on a desktop computer. The wallet's billing contact replaces any billing_info you send, and its shipping contact, when present, replaces shipping_info. See Wallet payments.
The API reference now shows the one token type each Checkout operation accepts. It previously also offered the merchant token on session operations.

Gateway

Visa Direct and Mastercard Send payouts take two calls. The create call returns status=approved with the recipient's saved cards but moves no money; the process call pays out. The create response amount is net of the convenience fee. See Payouts.
A create request that fails validation returns HTTP 400 with status: invalid and no success field, so don't rely on success alone. See Errors.
The merchant auth token operations return HTTP 200 with status: false when they fail, except when the request body isn't a JSON object. Check status. See Generate a merchant auth token.
A callback's code can be null, so branch on tx_action and status. Captures and voids have their own codes, and fraud review uses 5005 and 6016. See Error code reference.
The callback timestamp is when the status changed, in UTC with no time zone suffix, and retries keep it. first_name and last_name can appear for any payment method. See Gateway webhooks and callbacks.
Report types take exact values such as payment, refund, and payout, and an unknown value returns no rows. transaction_list includes only transactions already finalized in accounting. List Statements needs both start_date and end_date, and the range matches each statement's issue date. See Reconciliation playbook.
When your site validates email addresses, Paybilt rejects domains that don't accept mail, such as example.com. The API reference examples now use addresses that pass. See Getting started.
limits_enabled turns the limits API on or off, but your limits apply to transactions either way. phone_validation and zip_validation apply only to KYC uploads, and the e-Transfer auto-cancel and auto-decline delays are in seconds. See Site flags reference.

Interac e-Transfer

Every e-Transfer create requires udfs, including request money and Standard. See Interac e-Transfer.
A declined authorization ends with status=declined, with code 6015 for a payment and 6101 for a payout. The authorization deadline applies only to payments and is counted in seconds; a held payout waits until you decide. See e-Transfer authorization.
In the sandbox, the email tools complete a Standard payment only when message matches the payment's description, and the OutOfBand tool needs a site that auto-accepts out-of-band deposits. See Sandbox recipes.

2026-10-07 — Create Checkout Session request fields in the API reference

Classification: Documentation-only
Status: Published
Announcement date: 2026-10-07
Effective date: 2026-10-07
Affected operations: Hosted Checkout POST /checkout-session (Create Checkout Session)
Merchant impact: No API behavior changed. The API reference now lists each Create Checkout Session request field, including the session_info.session_methods options, express_checkout, three_ds, and the donation fields, instead of showing a free-form object. Its field descriptions and examples follow the rules in Hosted Checkout.
Migration: None.
Sandbox coverage: No new sandbox scenarios.

2026-10-07 — Corrections to request fields, statuses, and callbacks

Classification: Corrective
Status: Published
Announcement date: 2026-10-07
Effective date: 2026-10-07
Affected operations: Gateway payment, payout, card, wallet, Konek, bank, Interac e-Transfer, Transaction lookup, and callback operations; Hosted Checkout sessions, payouts, refunds, and webhooks; Checkout SDK configuration; and Billing operations through the Gateway's subscription proxy.
Merchant impact: No API behavior changed. We compared the guides with how Paybilt processes each request field and corrected the guides where they left out or misstated required fields, defaults, statuses, and callbacks. If you built from the earlier text, some requests may be rejected or some results handled incorrectly. We've corrected the API reference to match. If a guide and the API reference still disagree, follow the guide.
Migration: Check your integration against the corrections below. If you used the earlier Billing path or the earlier Hosted Checkout sandbox host, switch to the ones listed here. The other items change how you build requests or handle results.
Sandbox coverage: No new sandbox scenarios. The Hosted Checkout sandbox is https://checkout-sandbox.paybilt.com; earlier guides showed a sandbox host that doesn't exist.

Billing

Send Billing requests to /api/v3/subscriptions. The /api/v2/subscriptions path reaches a legacy subscription service with a different request contract. See Billing quickstart.
Send Content-Type: application/json and a JSON body on every POST, PUT, PATCH, and DELETE request, including operations that take no fields. With a scoped token, GET, HEAD, and OPTIONS requests need subscriptions:read and every other method needs subscriptions:write.
Create Customer requires email, first_name, and last_name.
Send a unique reference_id with Create Subscription, and resend the same value after a timeout. Billing doesn't support an Idempotency-Key header. See Billing subscriptions.
A price's collection_method doesn't change how renewals are collected, and recurring.trial_period_days doesn't start a trial. Send trial_end to start one.
Billing sends subscription webhooks only to the URLs in the subscription's event_listeners. Subscriptions created through the Checkout SDK have none, so track their renewals from your server. See Checkout SDK subscriptions.

Hosted Checkout and Checkout SDK

Use https://checkout-sandbox.paybilt.com in the sandbox, with REST paths under /api/v2. See Environments.
Payout sessions and every /merchant/* operation need a Payments capability token. See Checkout authentication.
e-Transfer sessions need checkout_items, and creation fails when a CAD cart is over 25,000. See Interac e-Transfer in Checkout.
List apple_pay and google_pay together with credit_card. Checkout removes them when card payments aren't enabled for your site. See Hosted Checkout.
Hosted Checkout doesn't offer Konek. To offer Konek without building the consent flow, use the Checkout SDK. See Konek payments.
payout_claimed is sent when the Gateway reports the payout as approved or claimed. Hosted payout sessions don't send payout_approved or payout_initiated. See Checkout webhooks.
A Checkout refund without an amount, or with null or 0, refunds the whole remaining balance. See Refunds and cancellations.
In the classic Checkout SDK, always pass fields and headerTitles, even as empty objects. Without them the form doesn't render. See One-Click SDK (classic).

Gateway

Paybilt charges the sum of items (quantity times unit_price) plus shipping_cost plus any convenience fee. A top-level amount on a payment is ignored. See Payments.
Standard ACH payments require transaction_descriptor, a top-level account_type, and a top-level routing_number. Standard ACH payouts require company and reject account_type. See Bank payments and Payouts.
Send a Konek capture only after the consent reaches TOKENIZED. The capture returns its final result in the response: approved, or declined with code 7501. If it returns pending, or pg_error with code 7507, check the transaction status before you capture again. See Konek payments.
A card payment held for fraud review has status: fraud_review. See Transaction lifecycle.
To find a transaction by your own reference, search Transaction lookup with {"filters": {"udfs": "<udfs[0] value>"}}. See Cross-capability identifiers.
An Interac e-Transfer create can return HTTP 403 with a txid when a risk check or revalidation stops it. Store the txid and handle its status. See Interac e-Transfer.
If an e-Transfer payout's account_id doesn't match a usable account saved for your site, Paybilt sends a regular e-Transfer to the recipient's email. See Interac e-Transfer payouts.
An e-Transfer payout that sends account_info needs all four of its fields: rsa_key_id as an integer, the RSA-encrypted encrypted_account_number, and the 5-digit transit_number and 3-digit institute_number as strings. See Account-to-account delivery.
Customer limits apply by email only, and limits saved for a phone number aren't applied. See Error code reference.
Webhook signatures cover the body without hmac_signature, serialized with keys sorted at every level, no spaces, and non-ASCII characters left unescaped. Numbers keep their stored form, such as 25.0. See Gateway webhooks and callbacks.

2026-08-07 — Documentation governance baseline

Classification: Documentation-only
Status: Published
Announcement date: 2026-08-07
Effective date: 2026-08-07
Affected operations: None
Merchant impact: No API behavior changed. This entry establishes the public notice and documentation governance policy.
Migration: None
Sandbox coverage: Not applicable

On this page