Skip to main content
​
API v2.4
New Payment Attempts API for Backend-Driven CIT (manual payment approval).
Added support for manual payment approval (Backend-Driven CIT), which lets your backend approve or abort each payment after tokenization and before the payment is created. See the Manual payment approval guide.Client Session API
  • Added approvalMode (AUTO / MANUAL) on the request and response. Set to MANUAL to require explicit approval of each payment attempt. Defaults to AUTO. Set at creation only; it cannot be changed with PATCH /client-session.
  • Added currentAttemptId on the response, pointing to the active payment attempt for MANUAL sessions.
Payment Attempts API (new)
  • Added POST /payment-attempts/{id}/approve to approve a payment attempt and trigger payment creation. Returns paymentAttemptId and paymentId. Requires the transactions:authorize scope.
  • Added POST /payment-attempts/{id}/abort to cancel a pending payment attempt. No payment is created and the tokenized payment method is invalidated.
​
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.
  • Authorization Code → Easier Reconciliation & Chargeback Matching
    • Added transactions[].authorizationCode, the authorization code returned by the processor on a successful authorization. It is returned in Payments API responses and payment webhooks, and omitted when not present. This field is available for selected processors only and is being rolled out processor by processor, so it will be absent for processors that are not yet supported. Treat a missing authorizationCode as “not available” rather than an error. 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 APIImprovements
  • 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 responsePayments 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