Skip to main content

Changelog

This changelog spans all Orchestrapay API versions, newest first.

v202608​

Pin a checkout to a specific gateway, capture a customer address, drive the form from your own button, and localize the hosted card form.

  • Pin a payment intent. POST /v202608/payment-intents accepts an optional payment_form (pf_…), orchestrator (orc_…), or connector (con_…) reference to route the intent to a specific hosted checkout, the same way the dashboard "payment link" flow does. Each is tenant-scoped and must be live (production); the hosted /pay page renders only the pinned gateway. Everything else on the endpoint is unchanged from v202607 (nearest-lower fallback still applies to all other endpoints).
  • Customer address. The customer object now takes an address (line1, line2, city, state, postal_code, country). When address.country is present, the hosted card form pre-fills and hides its country field, so returning customers aren't asked again.
  • Localized hosted card form. The PCI card form is now available in English, French, Arabic, Italian, and Spanish, with full right-to-left layout for Arabic. Pass locale to <PaymentForm> (@orchestrapay/react), or it follows the payment's locale.
  • Trigger Pay from your own UI. <PaymentForm> exposes an imperative ref with submit() — render your own "Buy now" button anywhere and call ref.current.submit() to run the exact same pay action as the built-in button.
  • Pay a single gateway for an existing intent. Render just one gateway (e.g. a PayPal button) for a payment intent by passing an inline single-gateway paymentForm, or by pinning the intent at creation (above) — so the same intent can be paid through different UIs on different pages.
  • Merchant-initiated card charges, documented. The card MIT endpoint (POST /cards/mit) — charge a saved card off-session for recurring, installment, or unscheduled payments — is now documented in Payment Methods.
  • SDK. @orchestrapay/sdk recognises v202608; @orchestrapay/react adds apiVersion="v202608", the imperative submit() handle, and the locale prop.
  • Dispute webhooks. When a customer disputes a payment, the payment intent's webhook endpoints receive dispute.created, dispute.updated, and dispute.closed with the dispute (dp_…), its status, reason, stage, amount, and response deadline. See Dispute Webhook. They are also delivered to v202607 integrations, and @orchestrapay/sdk types them as DisputeWebhookEvent.
  • credential_form_not_supported error code. A gateway that cannot charge a card in the form we hold it (a saved card token or a network token) now reports credential_form_not_supported (433). Some gateways used to report rejected_by_bank, which recorded a bank decline for a card that never reached a bank; others failed with an unexpected technical error. Either way the payment now moves on to the next gateway that can charge the card, if there is one. See Error Codes.
  • Refunds a connector cannot make are refused up front. POST /v202608/refunds answers 400 with apiErrorCode 105 (REFUND_NOT_SUPPORTED, message refund_not_supported) or 106 (PARTIAL_REFUND_NOT_SUPPORTED, message partial_refund_not_supported) when the connector that took the payment cannot make that refund, or when it was switched off on the connector's Capabilities card. No refund is created. See Refunds.
  • Paystack is one gateway. Paystack payments report gateway as paystack, for its card page and its bank transfer alike, in webhooks and API responses. Payment methods (GET /v202607/payment-methods) list each Paystack method as name paystack with a collection_method (redirect for the card page, hosted for the bank transfer). Creating a transaction with paystack@cards or paystack@banks_direct keeps working.
  • Canonical regional hosts. The EU and Egypt API hosts follow the api-<region> convention: api-eu1.orchestrapay.com and api-eg1.orchestrapay.com (US is already api-us1.orchestrapay.com). The SDK derives the host from your key automatically, and the previous api-europe/api-egypt hosts keep working, so no change is required.

v202607​

Typed IDs, a redesigned Payment Intents surface, a Customers API, and structured webhooks.

  • One payment id, end to end. Refunds are now created against the payment_intent (pi_...) you already hold, instead of a separate transaction intent. Responses expose typed, region-coded ids everywhere (pi_, re_, cus_).
  • Payment Intents. Create now returns the hosted url, status, amount, currency, expires_at, and resource_created. New endpoints to retrieve one, list them (cursor pagination with status / customer / currency / created filters), and cancel a pending intent. Create takes a single return_url, a structured webhooks array, and a customer you can upsert inline by your own reference.
  • Customers API. Full CRUD (POST/GET/POST update/GET list/DELETE) keyed on your merchant-issued reference.
  • Payment Forms API. GET /v202607/payment-forms (and GET /v202607/payment-forms/{payment_form}) returns the payment methods on a form, so you can render your own picker without embedding @orchestrapay/react. Each method includes name, title, category, logo_url, and favicon_url. Omit the id to resolve the tenant's default form, falling back to its production connectors, matching the embedded form.
  • Webhooks are now an event envelope: { id, type, created_at, data }, with type as <object>.<event> (e.g. payment.success). Payment webhooks are intent-level: payment.success and payment.canceled are terminal, while payment.attempt_failed signals a failed attempt on a still-open intent. Subscribe per endpoint via webhooks[].events, and authenticate with the Orchestrapay-Webhook-Secret header. Deliveries are at-least-once with exponential-backoff retries for up to 3 days.
  • SDK. @orchestrapay/sdk targets v202607 by default, with paymentIntents (create/retrieve/list/cancel), refunds (create/retrieve/list), and customers (create/retrieve/update/list/del), plus typed webhook events.
  • Subscriptions. Full recurring-billing surface at /v202607: plans, subscriptions (create on a saved pm_…, immediate prorated plan changes via proration_behavior, pause/resume/reactivate, upcoming proration preview), invoices (subtotal/discount/tax/credit breakdown), coupons + promotion-codes, tax-rates, and checkout/sessions (hosted subscribe links). Dunning retries per plan schedule with customer emails and a hosted pay/update-card page; trials save the card with a no-charge setup. Webhook events: subscription.created/updated/canceled, invoice.paid/payment_failed. All in the SDK (subscriptions, plans, invoices, coupons, promotionCodes, checkoutSessions) and documented in the Subscriptions guide. Supersedes the v202606 subscriptions preview. Pricing models: per_unit (seats), tiered (graduated/volume ladders) and metered (usage records) on top of flat, plus products, add-on subscription items, future-dated schedules, multi-currency currency_options, credit-notes (customer-balance adjustments), invoice PDFs, SCA-aware renewals (requires_action invoices with a hosted confirm flow), and billing-portal/sessions (login-free portal links).

v202606​

Subscriptions API. Adds /v202606/subscriptions (plans, subscriptions, invoices). Objects now use a typed string id (e.g. sub_…, plan_…, in_…) and an object discriminator instead of uuid. Invoice id prefix is in_.

v202502​

Initial public API version (payment intents, transactions, refunds).