X-Api-Version
header to 2.4
to use v2.4 of the API.
UniversalCheckoutOptions.apiVersion
property when initializing the checkout.
v2_4
in your PrimerSettings
before initializing the checkout.
v2_4
in your PrimerSettings
before initializing the checkout.
2.4
in your PrimerSettings
before initializing the checkout.
paymentType
field is used to send the correct information to processors for payment method storage, recurring and credential-on-file payments.
In API v2.4 we have changed the way this field is calculated and also upgraded our related recurring payments logic to be more accurate and intuitive. You can read more about how it works in our guide to optimizing recurring payments.
paymentType
based on the type of payment flow. However, if you do not pass one, we will calculate the most likely down stream value required from context.
paymentType
when creating a payment, we will no longer assign it a value. Instead the paymentType
field will remain blank and our improved internal logic will send the best possible information to your end processor(s).
This is in contrast to previous API versions, where if a paymentType
was not passed, a value was calculated and passed back based on whether the payment method had been previously vaulted and whether any intention to vault was passed.
paymentType
initiated by customers using a previously vaulted card were flagged as paymentType : UNSCHEDULED
– these will now remain with a null paymentType
value. This will also ensure that the Payment Initiation Type in the “Payment created” Trigger can be relied on to route these payments correctly.
paymentType
were incorrectly marked as ECOMMERCE
– these will now remain with a null paymentType
value.
paymentType
is passed through or if the incorrect value is used.
paymentType
values being used.paymentType
is passed through.
firstPaymentReason
, has been added to the paymentMethod
object, directly related to the paymentType logic:
firstPaymentReason
allows you to indicate why a payment method is being vaulted when setting paymentType : firstPayment
, with three possible values of CardOnFile
, Recurring
, and Unscheduled
. Pass this field if using a processor that has strict requirements for card storage.paymentType
behavior
paymentType
when creating or patching a client session and creating a payment.firstPaymentReason
would benefit your payments
paymentType: firstPayment
, consider including the new parameter firstPaymentReason
and setting it according to why the payment is being stored.paymentType
parameter.GATEWAY_TIMEOUT
. This will be returned when an external processor returns a timeout error or does not respond within our maximum processor timeout allowance.
GATEWAY_TIMEOUT
Decision Type is not included in fallback trigger reasons to avoid scenarios where a customer may inadvertently be charged twice. Once you have upgraded your workflows, processor timeouts will be excluded from fallback logic.GET
request for the payment status at a later timeGATEWAY_TIMEOUT
value is additive, so should not break any existing implementation. However if your integration is hardcoded to the API ≤v2.3 values for Error Decision Type, or if any of your own internal logic explicitly relies on those values, you will need to update your mappings to ensure no errors occur.GATEWAY_TIMEOUT
value will not appear in your workflow outputs until you update to the latest version of the workflow action. Please ensure you follow these steps before updating.transactions.events
in the Payment Object:
transactionEventId
, used in the reconciliation file/payments/{id}?expand=transactions.events
transactionEventId
to target the partial capture.transactions.events.id
in your system. This ID ensures you reference the right capture when making a refund.
transactions.events
array to the Payment API, within the transaction object.expand=transactions.events
to get transaction event details.processorData.external_ids
, including authorization_id
, from API and webhook payloads.transactionEventId
.transactionEventId
in the refund request to target a specific capture.transactionEventId
:?expand=transactions.events
?expand=transactions.events
processorData.external_ids
in API responses.transactionEventId
transactions.events.id
to internal records.?expand=transactions.events
to retrieve the processorEventId
of the event, replacing the old external_id field.transactionEventId
when issuing refunds.vaultOnAgreement
allows you to vault a payment method when an agreement mandate completes successfully in supporting processors (e.g., ACH via Stripe). Pass true
to store customer payment methods in the Primer Vault for future billing in payment processors that rely on Agreement flows, like ACH via Stripe.