API Changelog
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.
- The
-
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 oftransactions.events
. For more details, please see our detailed migration guide.
- Added
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 status409
when a payment request is submitted with anX-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
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
andpaymentMethod.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 anyamount
value is passed
Payments API
- Added
paymentMethod.isVaulted
boolean field to indicate whether thepaymentMethod.paymentMethodToken
in the response is a vaulted token (and can therefore be used for future payments) or not. This replacesvaultedPaymentMethodToken
. - Added
order.lineItems[].productType
on the request and responseamount
,currencyCode
,customerId
andorderId
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
Client Session API
-
X-API-Version
->2021-09-27
-
Creating a payment using only a payment method token is now possible. The
order
,customer
andmetadata
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 topaymentMethod
to be more consistent throughout -
The customer
billingAddress
andshippingAddress
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
andmetadata
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 topaymentMethod
to be more consistent throughout -
All the payments API endpoints (create, capture, cancel, refund, etc.) are now versioned
-
paymentMethodData
inPaymentMethod
responses (for card payment method types ) all now contain afirst6digits
field in addition to thelast4digits
returned. This is an opt-in field, so it is null by default. -
The customer
billingAddress
andshippingAddress
fields are now all optional