​
API v2.4
This version includes improvements to the Client Session API, Payments API and the Payment Methods API.

You must set the X-Api-Version header to 2.4 to use v2.4 of the API.

  • Improved Payment Type Logic → More Accurate & Reliable Processing

    • The paymentType field logic has been refined for better accuracy.
    • If no paymentType is provided, it remains blank, allowing the system to determine the best value internally.
    • Fixes incorrect categorization of one-off and vaulted payments, ensuring proper routing.

  • Extended Timeout Management → Reduced Synchronization Issues & Better Monitoring

    • Payment API timeout increased from 25s to 90s, allowing more time for processor responses.
    • Introduced a new GATEWAY_TIMEOUT decision type for better timeout tracking.

  • Partial Captures & Targeted Refunds → Improved Reconciliation & Marketplace Payments

    • Supports partial captures and targeted refunds, aligning payments with marketplace and logistics workflows.
    • Each partial capture generates a unique transactionEventId, enabling better tracking.

  • New Payment Parameters → Enhanced Compliance & Vaulting Flexibility

    • Added firstPaymentReason to specify why a payment method is vaulted (CardOnFile, Recurring, Unscheduled).
    • Introduced vaultOnAgreement to support vaulting after an agreement mandate is successfully completed. Removed processor data and external IDs from the API responses and webhooks in favour of transactions.events. For more details, please see our detailed migration guide.
​
API v2.3
This version includes improvements to the Payments API.

Set X-Api-Version header to 2.3 to use v2.3 of the API.

​
Payments API

Improvements

  • The Payments API endpoints were modified to return error code IdempotencyKeyAlreadyExists with status 409 when a payment request is submitted with an X-Idempotency-Key that was already sent in a previous request.
  • The payment creation endpoint was improved to return the correct paymentMethodType
  • The payment status webhook was improved to return the correct paymentMethodTypeAPI
​
API v2.2
This version includes improvements to the Client Session API, Payments API and the Payment Methods API.

You must set the X-Api-Version header to 2.2 to use v2.2 of the API.

​
Client Session API

Added order.lineItems.productData on the request and response

​
Payments API

Added order.lineItems.productData on the request and response

​
API v2.1
Version 2.1 includes improvements to the Client Session API, Payments API and the Payment Methods API.

Starting API v2.1, the API Version X-Api-Version is a semantic version without a patch (e.g. 2.1) rather than a date 🎉 Set the X-Api-Version header to 2.1 to use v2.1 of the API.

​
Client Session API

  • Added paymentMethod.paymentType and paymentMethod.descriptor on the request and response of the client session
  • Added order.lineItems[].productType on the request and response of the client session
  • Added GET /client-session to get the content of a client session
  • Added PATCH /client-session to update the content of a client session
  • Additional validation has been put in place to ensure that a currencyCode is always passed if any amount value is passed

​
Payments API

  • Added paymentMethod.isVaulted boolean field to indicate whether the paymentMethod.paymentMethodToken in the response is a vaulted token (and can therefore be used for future payments) or not. This replaces vaultedPaymentMethodToken.
  • Added order.lineItems[].productType on the request and response amount, currencyCode, customerId and orderId are now required fields when making a payment with a vaulted token (i.e. a recurring payment).
  • When paying with a vaulted token, additional validation has been put in place to ensure the customerId matches the customerId associated with the vaulted token.

​
Payment Methods API

  • Added verify in POST /payment-instruments/{paymentMethodToken}/vault to set whether or not the payment method token should be verified before vaulting
  • Added isVerified to the payment method response
​
API v2
Version 2 includes improvements to the Client Session API and the Payments API.

​
Client Session API

  • X-API-Version -> 2021-09-27

  • Creating a payment using only a payment method token is now possible. The order, customer and metadata passed on the Client Session request is then used for the payment.

  • The create Client Session endpoint request was extended to include order, customer, etc.

  • All references to paymentInstrument from the previous Payments API version have been refactored to paymentMethod to be more consistent throughout

  • The customer billingAddress and shippingAddress fields are now all optional

​
Payments API

  • X-API-Version -> 2021-09-27

  • Creating a payment using only a payment method token is now possible. The order, customer and metadata passed on the Client Session request is then used for the payment.

  • The create payment endpoint request was extended to include order, customer, etc. It now more closely resembles the /client-session endpoint

  • The response of all the Payments API endpoints was refactored to match the create payment request structure

  • All references to paymentInstrument from the previous Payments API version have been refactored to paymentMethod to be more consistent throughout

  • All the payments API endpoints (create, capture, cancel, refund, etc.) are now versioned

  • paymentMethodData in PaymentMethod responses (for card payment method types ) all now contain a first6digits field in addition to the last4digits returned. This is an opt-in field, so it is null by default.

  • The customer billingAddress and shippingAddress fields are now all optional