--- title: "Update a payment session by Id" method: PATCH path: "/payment-sessions/{paymentSessionId}" tags: ["Payments"] --- # Update a payment session by Id `PATCH /payment-sessions/{paymentSessionId}` This is used to update a payment session by its Id. Note that this can only be used prior to a successful payment. Once payment has been approved, you cannot update a PaymentSession. ## Path parameters - `paymentSessionId` string, required ## Headers - `Account` string ## Request body - object — The request body for updating a payment session - `amount` integer — The amount of the sale/purchase in minor digits. Minimum and maximum amounts [vary by currency](https://developer.ryftpay.com/documentation/overview/core_concepts/currencies). - `customerEmail` string — The email address of the customer - `platformFee` integer, nullable — The amount (if any) that will be taken and applied to the platform account. This cannot be greater than the "amount" property - `splits` SplitPaymentRequestDetail, nullable — Use this field to facilitate split-payments. This will divide up the `amount` as specified in the forms of split-payments to each sub account once payment is successfully captured. The total of all items must be <= to the `amount` on the payment session. **Cannot** be used in conjunction with `platformFee` or `passThroughProcessingFee`. You must also **not** specify a sub account ID in the `Account` header. **Note** that any splits provided as part of a capture request will overwrite those that were given during authorization. Howver, if you are using multi-capture (i.e. `NotFinal`) then any subsequent splits will not be written to the PaymentSession. Instead you need to store the Id of the capture transaction and refer to that to track each capture. - `items` SplitPaymentRequestItem[] - `accountId` string, required — The ID of the sub account who will receive this split payment amount in the form of a `SplitPayment`. - `amount` integer, required - `description` string — A short description of this split that will be displayed to the account. - `fee` object - `amount` integer - `metadata` object, nullable — The metadata to attach to this part of the split. This will be used to populate `metadata` on the `SplitPayment` once it is subsequently created. You can have a maximum of 3 pieces of metadata. - `metadata` object, nullable — Use this parameter to attach key-value data to the payment. These will be sent with any associated payment events on your webhook. You can have a maximum of 10 pieces of metadata. Keys must be between 1 and 30 characters in length. Values must be between 1 and 250 characters in length. - `captureFlow` 'Automatic' | 'Manual', nullable — By default we will automatically capture payment once the customer authorizes the payment. If you want to manually capture a payment yourself then set this to `Manual`. Typically this is recommended if you wish to authorize a particular amount from a customer for up to 7 days and then capture the funds once you can fulfil the order. - `shippingDetails` ShippingDetails, nullable - `address` object, nullable - `firstName` string — The first name of the customer - `lastName` string — The last name of the customer - `lineOne` string — First line of the address - `lineTwo` string — Second line of the address - `city` string — The address city/town - `country` string, required — The two-character ISO country code - `postalCode` string, required — The postal code/zip of the address - `region` string, nullable — The state/county/province/region Required if the address is in the US/Canada and must be a 2-character ISO state/province code - `phoneNumber` string, nullable — The phone number of the recipient receiving the goods, in E.164 format - `orderDetails` OrderDetails, nullable — The details of the order - `reference` string, nullable — Your unique identifier for the order - `items` OrderLineItem[] - `reference` string, required — Your unique Identifier for the product on this line item - `name` string, required — The title or name of the item - `quantity` integer, required — The number of this item in the order - `unitPrice` integer, required — The unit price of the item in minor units. That is, the price of a single unit (excluding tax). - `taxAmount` integer, required — The total tax amount on this line item. - `totalAmount` integer, required — The total amount of this line item (including tax & any discount). i.e. the total amount the customer is actually being charged for this line on the order. `(unitPrice * quantity) + taxAmount - discountAmount = totalAmount`. **Note** that the `totalAmount` across all items must be less than or equal the `amount` on the PaymentSession. - `discountAmount` integer, nullable — The total amount discounted (if any) in minor units - `productUrl` string, nullable — URL of the purchased item. We recommend you use a stable URL: - one that should not change - does not include parameters that change each time you update product data (timestamps, colours etc.) - `imageUrl` string, nullable — URL of your primary image for the purchased item. We recommend you use a stable URL: - one that should not change - does not include parameters that change each time you update product data (timestamps, colours etc.) - `paymentSettings` PaymentSettingsUpdateRequest — Allows for customisation of various payment settings. - `paymentMethodOptions` PaymentMethodOptionSettingsRequest, nullable — Use of this field is not enabled by default and subject to approval, please contact our support team if you wish to request it. - `disabled` string[] — Use this field to explicitly disable specific options from being used to complete payment. e.g. if you have your own requirements for accepting Amex on only particular transactions. If your customer attempts to pay with a disabled option, the payment session will be updated with `lastError: "payment_method_option_amex_disabled"` You can re-enable a disabled option by removing it from this array. - `threeDs` PaymentThreeDsSettingsRequest, nullable — Allow for customisation of various 3D-secure settings when leveraging Ryft's 3D-secure MPI - `challengeIndicator` 'NoPreference' | 'NoChallengeRequested' | 'ChallengeRequested' | 'TransactionRiskAnalysisAlreadyPerformed', nullable — Optional 3DS challenge preference. - `NoPreference`: No explicit challenge preference is requested. - `NoChallengeRequested`: Request a frictionless flow where possible. - `ChallengeRequested`: Request that the issuer performs a challenge. - `TransactionRiskAnalysisAlreadyPerformed`: Indicates TRA has already been performed before authentication which requests an exemption from the issuer If omitted, no explicit preference is requested. ## Response `200` Successfully retrieved the given paymentSessionId - PaymentSession - `id` string — The unique identifier for the payment - `amount` integer — The amount of the sale/purchase in minor digits - `currency` string — The ISO currency code - `paymentType` 'Standard' | 'Unscheduled' | 'MOTO' | 'Recurring', nullable — The type of the payment. Use this to control whether the payment is classified as a Customer-Initiated Transaction (CIT) or Merchant-Initiated Transaction (MIT). (MIT) - customer is not actively participating in the transaction and has instead given consent for you to charge their stored card off session. (CIT) - customer is actively in your checkout flow and is on hand to react to and complete any supplementary steps to complete the payment (e.g. 3DS). CIT values: - `Standard` - A regular one-off e-commerce payment, made by a customer on your website/app MIT values: - `Unscheduled` - Uses an already stored card on file for a fixed or variable amount that does not occur on a scheduled or regular basis such as recurring payments/subcriptions. `Recurring` is classified as CIT if it is the initial payment in the series and MIT if it is a subsequent (follow up) payment in the series. `MOTO` has now been deprecated in favour of the `entryMode` (`MOTO`) field. - `entryMode` 'Online' | 'MOTO' | 'InPerson', nullable — Indicates how the payment method details were (or will be) obtained by the merchant for this payment. - `Online` - when the payment method is collected with the customer present (e.g. an e-commerce payment within a browser) - `MOTO` - when the payment method is collected via mail order (not e-email) or over the phone - `InPerson` - when the payment is collected in-person over a physical medium (such as card terminal) MOTO is subject to additional approval, contact us if you require this functionality. - `customerEmail` string, nullable — The email address of the customer - `customerDetails` object, nullable — The details of the customer that this payment belongs to - `id` string, nullable — The Id of the customer this payment belongs to. Set this upfront when creating the payment-session if you wish to make use of paying with a customer's saved payment methods - `firstName` string, nullable — The first name of the customer this payment belongs to. - `lastName` string, nullable — The last name of the customer this payment belongs to. - `homePhoneNumber` string, nullable — The home phone number of the customer. In E.164 format - `mobilePhoneNumber` string, nullable — The mobile phone number of the customer. In E.164 format - `metadata` object, nullable — The metadata of the customer this payment belongs to. - `credentialOnFileUsage` CredentialOnFileUsage, nullable — Details the intended usage when using or setting up a customer's card details for subsequent purchases. Ryft will set `credentialOnFileUsage` based on the arguments supplied. - `initiator` 'Customer' | 'Merchant' — Whether the transaction was initiated by the customer or merchant. A Customer-initiated transaction (CIT) is one in which the customer actively participates in completing the transaction with the merchant. This can include: - a first time online purchase where the customer agrees for their card details to be stored for future purchases - a subsequent online purchase with already stored card details (e.g. the customer selecting a saved card during checkout) A Merchant-initiated transaction (MIT) is one in which the customer is not present during the transaction. Instead, the merchant completes the transaction by charging previously stored card details based on the agreement (mandate) which the customer agreed to on the initial transaction. Examples of MIT are: - recurring payments (e.g. subscriptions) - unscheduled payments (e.g. account top up or additional charges) - `sequence` 'Initial' | 'Subsequent' — Indicates the order of this transaction in a series of agreed, repeating processing model - `previousPayment` object, nullable — For recurring/unscheduled payments - details of the initial payment in the series. Required for: - partners who want to externally schedule recurring payments. - partners who process `Unscheduled` payments - `id` string — The Id of the initial Payment Session in the series - `rebillingDetail` RebillingDetail, nullable — Details the parameters specific to recurring payments (e.g. Subscriptions) - `amountVariance` 'Fixed' | 'Variable' — Whether the customer is paying a fixed (non-variable) amount on each payment or an amount which can vary. - `numberOfDaysBetweenPayments` number — The minimum number of days between each payment - `totalNumberOfPayments` number, nullable — The total number of payments to be billed. Can be omitted if the recurring plan is set to run indefinitely - `currentPaymentNumber` number, nullable — Indicates the position in the rebilling sequence for this payment. e.g. if the cardholder is being billed once monthly for 12 months and this payment is for month 7, the value will be 7. - `expiry` number, nullable — The date (in epoch seconds) after which no further subsequent transactions are expected. - `enabledPaymentMethods` string[] — List of payment method types that can be used to complete payment for this PaymentSession. `Card` is the default and will allow all card schemes configured on your account (Visa, Mastercard etc.). Apple Pay & Google Pay are classified as `Card` types and will be displayed provided you have confogured them properly. - `paymentMethod` PaymentSessionPaymentMethod, nullable - `type` 'Card' - `tokenizedDetails` PaymentSessionPaymentMethodTokenizedDetails, nullable — The details of any tokenized payment method used - `id` string — The Id of the tokenized payment method - `stored` boolean — Flag to indicate whether or not the tokenized payment method was stored (against the customer) - `card` object, nullable — Details of the card used - `scheme` 'Visa' | 'Mastercard' | 'Amex' - `last4` string — The last 4 digits of the card used - `binDetails` CardBinDetails, nullable — The specific details obtained from the BIN/IIN of the card. Note that this is not always available. - `issuer` string, nullable — Name of the card issuer - `issuerCountry` string, nullable — The two-character ISO 3166 country code of the card issuer - `fundingType` 'Debit' | 'Credit' | 'Prepaid' | 'DeferredDebit' | 'Charge', nullable — Refers to how money for purchases comes to the card. - `productType` 'Consumer' | 'Corporate', nullable — The category the issuer assigns to the particular card - `wallet` object, nullable — Details of the wallet used (Google Pay / Apple Pay) - `type` 'GooglePay' | 'ApplePay' - `billingAddress` CustomerAddress, nullable - `firstName` string — The first name of the customer - `lastName` string — The last name of the customer - `lineOne` string — First line of the address - `lineTwo` string — Second line of the address - `city` string — The address city/town - `country` string, required — The two-character ISO country code - `postalCode` string, required — The postal code/zip of the address - `region` string, nullable — The state/county/province/region Required if the address is in the US/Canada and must be a 2-character ISO state/province code - `checks` PaymentMethodChecks, nullable - `avsResponseCode` string, nullable — The response from Address Verification Service (AVS) that determines the match or partial match of the customer's billing address. Possible values: - A - Partial Match (street address matches, postal/zip code does not match) - B - Partial Match (street address matches, postal/zip code not verified) - C - No Match (street address and postal/zip code not verified) - D - Full Match (street address and postal/zip code match) - F - Full Match (street address and postal/zip code match) - G - Not Supported (address information not verified) - I - No Match (address information not verified) - M - Full Match (street address and postal/zip code match) - N - No Match (neither street address not postal/zip code match) - P - Partial Match (postal/zip code matches, street address not verified) - R - System Unavailable (unable to perform verification) - S - Not Supported (AVS currently not supported by issuer) - U - System Unavailable (address information not verified due to no data from issuer) - W - Partial Match (postal/zip code matches, street address does not match) - X - Full Match (street address and postal/zip code match) - Y - Full Match (street address and postal/zip code match) - Z - Partial Match (postal/zip code matches, street address does not match) - `cvvResponseCode` string, nullable — The response from the check on the Card Verification Value (CVV/CVV2/CVC) Possible values: - M - Match (Visa and MC) - Y - Match (Amex) - N - No Match - P - Not Processed - S - Should be on card - U - Issuer does not participate - `platformFee` integer, nullable — The amount (if any) that will be taken and applied to the platform account. This cannot be greater than the "amount" property - `splitPaymentDetail` SplitPaymentDetail, nullable - `items` SplitPaymentItem[] - `id` string — The unique identifier for this split payment item. Note that this will be the id of the `SplitPayment` created once payment is captured. - `accountId` string — The ID of the sub account who will receive this split payment amount in the form of a `SplitPayment`. **Must** be unique, i.e. you cannot have > 1 splits to the same account in your request. - `amount` integer - `fee` object - `amount` integer - `description` string — A short description of this split that will be displayed to the account. - `metadata` object, nullable — The metadata to attach to this part of the split. This will be used to populate `metadata` on the `SplitPayment` once it is subsequently created. - `status` 'PendingPayment' | 'PendingAction' | 'Processing' | 'Approved' | 'Captured' | 'Voided' - `metadata` object, nullable — use this parameter to attach key-value data to the payment. These will be sent with any associated payment events on your webhook. - `clientSecret` string, nullable — The client secret is used to complete a payment from your frontend. Do NOT store/log/embed anywhere and ensure it is only surfaced on pages served over TSL - `lastError` 'insufficient_funds' | 'declined_do_not_honour' | 'invalid_card_number' | 'cvv2_failure' | 'restricted_card' | 'blacklisted_card' | 'blacklisted_bin' | 'blacklisted_country' | 'blacklisted_ip' | 'risk_declined' | 'security_violation' | 'expired_card' | 'gateway_reject' | 'suspected_fraud' | 'contact_issuer' | 'not_permitted' | 'invalid_account' | 'pickup_card' | 'stolen_card' | 'issuer_decline' | 'closed_account' | 'account_not_activated' | 'limit_exceeded' | 'withdrawal_limit_exceeded' | 'blocked_by_cardholder' | '3ds_authentication_failure' | '3ds_cardholder_not_participating' | '3ds_authentication_required' | 'payment_method_option_amex_disabled' | 'cvc_required' | 'payment_method_not_available' | 'payment_method_option_amex_not_available' | 'credit_card_not_permitted' | 'issuer_error' | 'system_error' | 'unknown_error', nullable — The most recent error when attempting to Pay. Note that we may add further values without notice. - `refundedAmount` integer — The total amount refunded thus far against the payment-session. Refunds can only be actioned once the payment-session is `Captured`. You can only have one refund in-flight at a time. - `statementDescriptor` StatementDescriptor - `descriptor` string — The statement descriptor that will be shown on the customer's bank statement for this payment. If you don't specify this then the descriptor set on your account will be used instead. It must satisfy the following regex pattern: ^[A-Za-z0-9 ]*[A-Za-z][A-Za-z0-9 ]*$ - `city` string — This is the city that will be shown on the statements of the account's customers. If you don't specify this then the descriptor set on your account will be used instead. It must satisfy the following regex pattern: ^[A-Za-z0-9 ]*[A-Za-z][A-Za-z0-9 ]*$ - `requiredAction` RequiredAction, nullable — The action to take (if any) in order to authorise the payment. This will be non-null if the customer's bank challenge the payment (i.e. 3DS) - `type` 'Redirect' | 'Identify' | 'Challenge' — The type of action - `url` string, nullable — The url to redirect to (if the requiredAction has type `Redirect`) - `identify` union - object, nullable — Contains the details required to perform device data collection during 3DS (for browser/web authentication only) We recommend using our embedded SDK to handle this action for you. - `uniqueId` string, nullable — A uniqueId used to identify the transaction within the 3ds-server - `threeDsMethodUrl` string - `threeDsMethodSignature` string - `sessionId` string - `sessionSecret` string - `threeDsMethodData` string - `scheme` string - `paymentMethodId` string — The Id of the tokenized payment method belonging to this 3DS session - object, nullable — Contains the details required to perform device data collection during 3DS (for native iOS & Android) **Note** that this is subject to change and should only be handled by our native SDKs. - `sessionId` string - `sessionSecret` string - `scheme` string, required - `paymentMethodId` string, required — The Id of the tokenized payment method belonging to this 3DS session - `protocolVersion` string — The 3DS message protocol version the native SDK should target when creating the Ravelin transaction. - `ravelinPublicKey` string — The Ravelin public API key. Used as a Bearer token when initialising the Ravelin 3DS service on iOS / Android. - `challenge` union — Details required to perform the 3DS challenge step for browser/web or native iOS & Android flows. - object - `acsUrl` string, required — Fully qualified URL of the ACS to be used for the 3DS challenge - `cReq` string, required — base64 encoded challenge request message - `threeDSServerTransactionID` string — 3DS Server transaction ID issued for this authentication. - `acsTransactionID` string — ACS transaction ID returned by the issuer's ACS. - `acsRefNumber` string — ACS reference number identifying the issuer's ACS implementation. - `acsSignedContent` string — Signed JWS from the ACS containing the challenge protocol data. - object - `acsUrl` string — Fully qualified URL of the ACS to be used for the 3DS challenge - `cReq` string — base64 encoded challenge request message - `threeDSServerTransactionID` string, required — 3DS Server transaction ID issued for this authentication. - `acsTransactionID` string, required — ACS transaction ID returned by the issuer's ACS. - `acsRefNumber` string, required — ACS reference number identifying the issuer's ACS implementation. - `acsSignedContent` string, required — Signed JWS from the ACS containing the challenge protocol data. - `returnUrl` string — URL to send the customer back to after a redirection (e.g. 3DS). We will always append the paymentSessionId under query param `ps`. - `authorizationType` 'PreAuth' | 'FinalAuth', nullable — Specifies the type of authorization. PreAuth - Used to authorize a non-final amount, where you may want to later capture a different amount or adjust the initial authorized amount. FinalAuth - When the amount authorized is final and identical to the amount later captured. By default we will always use `FinalAuth`. Note that PreAuth is restricted to particular MCC values for Visa, contact us to verify and enable PreAuth if you believe your business is eligible. - `captureFlow` 'Automatic' | 'Manual', nullable — Whether the payment is automatically/manually captured. Defaults to `Automatic`. - `verifyAccount` boolean, nullable — Whether the PaymentSession was used to facilitate an account verification check. - `shippingDetails` ShippingDetails, nullable - `address` object, nullable - `firstName` string — The first name of the customer - `lastName` string — The last name of the customer - `lineOne` string — First line of the address - `lineTwo` string — Second line of the address - `city` string — The address city/town - `country` string, required — The two-character ISO country code - `postalCode` string, required — The postal code/zip of the address - `region` string, nullable — The state/county/province/region Required if the address is in the US/Canada and must be a 2-character ISO state/province code - `phoneNumber` string, nullable — The phone number of the recipient receiving the goods, in E.164 format - `orderDetails` OrderDetails, nullable — The details of the order - `reference` string, nullable — Your unique identifier for the order - `items` OrderLineItem[] - `reference` string, required — Your unique Identifier for the product on this line item - `name` string, required — The title or name of the item - `quantity` integer, required — The number of this item in the order - `unitPrice` integer, required — The unit price of the item in minor units. That is, the price of a single unit (excluding tax). - `taxAmount` integer, required — The total tax amount on this line item. - `totalAmount` integer, required — The total amount of this line item (including tax & any discount). i.e. the total amount the customer is actually being charged for this line on the order. `(unitPrice * quantity) + taxAmount - discountAmount = totalAmount`. **Note** that the `totalAmount` across all items must be less than or equal the `amount` on the PaymentSession. - `discountAmount` integer, nullable — The total amount discounted (if any) in minor units - `productUrl` string, nullable — URL of the purchased item. We recommend you use a stable URL: - one that should not change - does not include parameters that change each time you update product data (timestamps, colours etc.) - `imageUrl` string, nullable — URL of your primary image for the purchased item. We recommend you use a stable URL: - one that should not change - does not include parameters that change each time you update product data (timestamps, colours etc.) - `paymentSettings` PaymentSessionPaymentSettings, nullable — Allows for customisation of various payment settings. - `paymentMethodOptions` PaymentMethodOptionSettings, nullable - `disabled` string[] — Specific payment method options that have been disabled during payment. These options cannot be used to complete payment on this payment session. - `platform` PaymentPlatformSettings, nullable — Only applicable to payments under the platform model. - `paymentFees` PaymentFeeAllocationSettings, nullable — Denotes which Ryft account's are charged particular fees for the payment. - `interchange` object, nullable — The ID of the Ryft account that any interchange fees are deducted from. **Only** applicable for accounts on the `ICC++` pricing model. - `bookTo` string — The ID of the Ryft account the fee is booked to. - `network` object, nullable — The ID of the Ryft account that any network (scheme) fees are deducted from. **Only** applicable for accounts on the `ICC++` pricing model. - `bookTo` string — The ID of the Ryft account the fee is booked to. - `miscPassThrough` object, nullable — The ID of the Ryft account that any miscellanous pass-through fees are deducted from. **Only** applicable for accounts on the `ICC++` pricing model. - `bookTo` string — The ID of the Ryft account the fee is booked to. - `processor` object, nullable — The ID of the Ryft account that the Ryft processing fee is deducted from. **Note** that: - when on `Blended` pricing, this refers to the full blended fee - when on `ICC++` pricing, this refers to the final `+`, i.e. Ryft's markup - `bookTo` string — The ID of the Ryft account the fee is booked to. - `gateway` object, nullable — The ID of the Ryft account that any gateway fees are deducted from. - `bookTo` string — The ID of the Ryft account the fee is booked to. - `combined` object, nullable — The ID of the Ryft account that all the above are deducted from. This field takes precedence over any of the more granular fields. **Note** that: - when on `Blended` pricing, this will book all of: `processor` & `gateway` fees - when on `ICC++` pricing, this will book all of: `interchange`, `network`, `miscPassThrough`, `processor` & `gateway` fees - `bookTo` string — The ID of the Ryft account the fee is booked to. - `threeDs` PaymentThreeDsSettings, nullable — 3DS challenge preference configured for this payment session. - `challengeIndicator` 'NoPreference' | 'NoChallengeRequested' | 'ChallengeRequested' | 'TransactionRiskAnalysisAlreadyPerformed', nullable - `createdTimestamp` integer — The epoch timestamp (seconds) when the payment was created - `lastUpdatedTimestamp` integer — The epoch timestamp (seconds) when the payment was last updated ## Other responses - `404` — The given resource could not be found - `500` — An unexpected error occurred when executing this request --- [API](https://skmtc.net/ryftpay/apis/ryft-payment-api.md) · [All operations](https://skmtc.net/ryftpay/apis/ryft-payment-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ryftpay/ryft-payment-api/versions/a042f64d4305/schema)