--- title: "Retrieves events in sorted (by epoch) order" method: GET path: "/events" tags: ["Events"] --- # Retrieves events in sorted (by epoch) order `GET /events` Retrieves a list of events. They are returned in sorted (by epoch) order (default is newest first). You can query one of your sub-account's events buy using the `Account` header. ## Query parameters - `ascending` boolean - `limit` integer — Control how many items are returned in the result list. The max limit we allow is `50`. ## Headers - `Account` string ## Response `200` Successfully retrieved a list of events - EventsResponse - `items` Event[] - `id` string — The unique id of the event - `eventType` 'PaymentSession.approved' | 'PaymentSession.captured' | 'PaymentSession.declined' | 'PaymentSession.voided' | 'PaymentSession.void_failed' | 'PaymentSession.refunded' | 'PaymentSession.refund_failed' | 'PaymentSession.requires_action' | 'Account.created' | 'Account.updated' | 'Account.verification_status_updated' | 'Person.created' | 'Person.updated' | 'Person.deleted' | 'PayoutMethod.created' | 'PayoutMethod.updated' | 'PayoutMethod.deleted' | 'Payout.created' | 'Payout.status_updated' | 'Customer.created' | 'Customer.updated' | 'Customer.deleted' | 'Subscription.created' | 'Subscription.updated' | 'Subscription.cancelled' | 'Subscription.past_due' | 'Subscription.ended' | 'Transfer.created' | 'Transfer.updated' | 'Dispute.created' | 'Dispute.closed' | 'Dispute.challenged' | 'PlatformFee.created' | 'PlatformFee.refunded' | 'InPersonOrder.created' | 'InPersonOrder.updated' | 'InPersonLocation.created' | 'InPersonLocation.updated' | 'Terminal.created' | 'Terminal.updated' | 'Terminal.deleted' — The type of the event. Note that we consider adding new types non-breaking changes so recommend you do not hard-code all values listed here. - `data` union — Contains the full underlying response object at the time the event was emitted. For example, a `PaymentSession.captured` event will contain the entire `PaymentSession` resource in this field. Note that some older events (prior to August 2025) consisted of a more specific model. We have dropped support for this model and typically recommend events older than 30 days be considered archived. - 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. - … - `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 - … - `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. - … - 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. - … - `challenge` union — Details required to perform the 3DS challenge step for browser/web or native iOS & Android flows. - object - … - object - … - `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. - … - `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 - AccountResponse - `id` string — The ID of the account - `type` 'Standard' | 'Sub' — The type of account - `status` 'ActionRequired' | 'Unverified' | 'VerificationPending' | 'Verified', nullable — The overall status of the account - `actionsRequired` object[], nullable — A list of actions required by the user when the status is 'ActionRequired', each accompanied by a description. DEPRECATED - if you wish to determine if actions are required before payouts can be sent out, check: - if `verification.status` is `Required` on this response - if `status` is `Invalid` on any payout methods under /v1/accounts/{id}/payout-methods - `action` 'PayoutDetailsRequired' | 'PayoutMethodRequired' | 'PayoutMethodInvalid' | 'VerificationRequired' | 'AccountLocked' — The possible actions required to take if an account is in the 'ActionRequired' status - `description` string — The description of the action that is required by the user - `frozen` boolean — A flag to determine whether or not the account is frozen. We may temporarily mark an account as frozen if we detect any potential fraudulent activity. Payments can still be taken however payouts will be disabled, contact us to resolve the issue. DEPRECATED - this flag is no longer in use and will always return false, though payouts may still be disabled if we detect fraudulent activity. - `email` string, email, nullable — The account's email address - `onboardingFlow` 'Hosted' | 'NonHosted' - `entityType` 'Business' | 'Individual', nullable - `business` object, nullable — The details of the business - `name` string — The legal name of the business (not the operating/trade name). - `type` 'Corporation' | 'GovernmentEntity' | 'Charity' | 'LimitedPartnership' | 'PrivateCompany' | 'PublicCompany' - `registrationNumber` string, nullable — The registration number of the business, assigned by a government body. - `registrationDate` string, nullable — The date when the business was registered - `registeredAddress` object — The address where the business is registered - `lineOne` string, nullable — First line of the address. It must satisfy the following regex pattern: ^[A-Za-z0-9 !&'()+,-./:;]*$ - `lineTwo` string, nullable — Second line of the address. It must satisfy the following regex pattern: ^[A-Za-z0-9 !&'()+,-./:;]*$ - `city` string, nullable — The address city/town It must satisfy the following regex pattern: ^[A-Za-z0-9 !&'()+,-./:;]*$ - `country` string — The two-character ISO country code - `postalCode` string, nullable — The postal/zip code of the address. It must satisfy the following regex pattern: ^[A-Za-z0-9 -]*$ - `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 Otherwise it must satisfy the following regex pattern: ^[A-Za-z0-9 !&'()+,-./:;]*$ - `contactEmail` string, email — The email address used in case we need to contact you. This takes precedence over the 'email' on the account itself. - `phoneNumber` string, nullable — The phone number of the business, in E.164 format - `tradingName` string, nullable — The trading/operating name of the business - `tradingAddress` object, nullable — The address where the business trades/operates - `lineOne` string, nullable — First line of the address. It must satisfy the following regex pattern: ^[A-Za-z0-9 !&'()+,-./:;]*$ - `lineTwo` string, nullable — Second line of the address. It must satisfy the following regex pattern: ^[A-Za-z0-9 !&'()+,-./:;]*$ - `city` string, nullable — The address city/town It must satisfy the following regex pattern: ^[A-Za-z0-9 !&'()+,-./:;]*$ - `country` string — The two-character ISO country code - `postalCode` string, nullable — The postal/zip code of the address. It must satisfy the following regex pattern: ^[A-Za-z0-9 -]*$ - `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 Otherwise it must satisfy the following regex pattern: ^[A-Za-z0-9 !&'()+,-./:;]*$ - `tradingCountries` string[], nullable — The countries where the business trades/operates - `websiteUrl` string, nullable — The website url of the business - `documents` AccountDocumentResponse[], nullable — The KYB documents - `type` 'BankStatement' | 'BusinessRegistration' | 'CreditCardStatement' | 'DriversLicense' | 'LetterOfAuthorization' | 'NationalId' | 'OfficialGovernmentLetter' | 'Passport' | 'PropertyTaxAssessment' | 'TaxReturn' | 'UtilityBill' — The type of document, these are only applicable for certain entities: - 'LetterOfAuthorization' is only applicable for Persons, when the 'Authorization' category is required - 'BankStatement', 'CreditCardStatement', 'OfficialGovernmentLetter', 'PropertyTaxAssessment', 'TaxReturn', 'UtilityBill' are only applicable for Individuals or Persons, when the 'ProofOfAddress' category is required - 'BusinessRegistration' is only applicable for Businesses, when the 'ProofOfBusiness' category is required - 'DriversLicense', 'NationalId', 'Passport' are only applicable for Individuals or Persons, when the 'ProofOfIdentity' category is required - `category` 'Authorization' | 'ProofOfAddress' | 'ProofOfBusiness' | 'ProofOfIdentity' — The category of document, these are only applicable for certain entities: - `Authorization` is only applicable for Persons - `ProofOfAddress` is only applicable for Individuals or Persons - `ProofOfBusiness` is only applicable for Businesses - `ProofOfIdentity` is only applicable for Individuals or Persons - `front` string — The ID of the uploaded file that shows the front of the document. - `back` string, nullable — The ID of the uploaded file that shows the back of the document. Required if uploading a `DriversLicense` or `NationalId`. - `status` 'Invalid' | 'Pending' | 'Valid' - `invalidReason` string, nullable — The reason for the document being invalid - `country` string, nullable — The two-character ISO 3166 country code of the document. Only present historically on documents with `type`: `Passport`, `DriversLicense`, `NationalId` - `assignedTimestamp` integer — The epoch timestamp (seconds) when the document was first assigned to the account - `lastUpdatedTimestamp` integer — The epoch timestamp (seconds) when the document was last updated - `individual` object, nullable — The details of the individual - `firstName` string — The first name of the individual - `middleNames` string, nullable — The middle names of the individual - `lastName` string — The last name / surname of the individual - `email` string, email — The email address of the individual. This takes precedence over the 'email' on the account itself. - `dateOfBirth` string — The date of birth of the individual, in format YYYY-MM-DD - `countryOfBirth` string, nullable — The two-character ISO 3166 country code of birth of the individual - `gender` 'Female' | 'Male', nullable — The gender of the individual. International regulations require either `Female` or `Male` - `nationalities` string[], nullable — The countries of citizenship or nationality of the individual - `address` object, nullable — The address of the individual - `lineOne` string, nullable — First line of the address. It must satisfy the following regex pattern: ^[A-Za-z0-9 !&'()+,-./:;]*$ - `lineTwo` string, nullable — Second line of the address. It must satisfy the following regex pattern: ^[A-Za-z0-9 !&'()+,-./:;]*$ - `city` string, nullable — The address city/town It must satisfy the following regex pattern: ^[A-Za-z0-9 !&'()+,-./:;]*$ - `country` string — The two-character ISO country code - `postalCode` string, nullable — The postal/zip code of the address. It must satisfy the following regex pattern: ^[A-Za-z0-9 -]*$ - `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 Otherwise it must satisfy the following regex pattern: ^[A-Za-z0-9 !&'()+,-./:;]*$ - `phoneNumber` string, nullable — The phone number of the individual, in E.164 format - `documents` AccountDocumentResponse[], nullable — The KYC documents - `type` 'BankStatement' | 'BusinessRegistration' | 'CreditCardStatement' | 'DriversLicense' | 'LetterOfAuthorization' | 'NationalId' | 'OfficialGovernmentLetter' | 'Passport' | 'PropertyTaxAssessment' | 'TaxReturn' | 'UtilityBill' — The type of document, these are only applicable for certain entities: - 'LetterOfAuthorization' is only applicable for Persons, when the 'Authorization' category is required - 'BankStatement', 'CreditCardStatement', 'OfficialGovernmentLetter', 'PropertyTaxAssessment', 'TaxReturn', 'UtilityBill' are only applicable for Individuals or Persons, when the 'ProofOfAddress' category is required - 'BusinessRegistration' is only applicable for Businesses, when the 'ProofOfBusiness' category is required - 'DriversLicense', 'NationalId', 'Passport' are only applicable for Individuals or Persons, when the 'ProofOfIdentity' category is required - `category` 'Authorization' | 'ProofOfAddress' | 'ProofOfBusiness' | 'ProofOfIdentity' — The category of document, these are only applicable for certain entities: - `Authorization` is only applicable for Persons - `ProofOfAddress` is only applicable for Individuals or Persons - `ProofOfBusiness` is only applicable for Businesses - `ProofOfIdentity` is only applicable for Individuals or Persons - `front` string — The ID of the uploaded file that shows the front of the document. - `back` string, nullable — The ID of the uploaded file that shows the back of the document. Required if uploading a `DriversLicense` or `NationalId`. - `status` 'Invalid' | 'Pending' | 'Valid' - `invalidReason` string, nullable — The reason for the document being invalid - `country` string, nullable — The two-character ISO 3166 country code of the document. Only present historically on documents with `type`: `Passport`, `DriversLicense`, `NationalId` - `assignedTimestamp` integer — The epoch timestamp (seconds) when the document was first assigned to the account - `lastUpdatedTimestamp` integer — The epoch timestamp (seconds) when the document was last updated - `verification` AccountVerification - `status` 'NotRequired' | 'Required' | 'PendingVerification' | 'Verified' - `requiredFields` object[], nullable — A list of fields that must be provided for verification. For `Business` entities this will detail the fields required for the business only, it will not list requirements for persons. - `name` string — The name of the field - `requiredDocuments` object[], nullable — A list of documents that must be provided for verification. For `Business` entities this will detail the documents required for the business only, it will not list requirements for persons. - `category` 'Authorization' | 'ProofOfAddress' | 'ProofOfBusiness' | 'ProofOfIdentity' — The category of document, these are only applicable for certain entities: - `Authorization` is only applicable for Persons - `ProofOfAddress` is only applicable for Individuals or Persons - `ProofOfBusiness` is only applicable for Businesses - `ProofOfIdentity` is only applicable for Individuals or Persons - `types` AccountDocumentType[] — The types of document available to upload in this category. The types will be as follows for each category: - `Authorization`: - `LetterOfAuthorization` - `ProofOfAddress`: - `BankStatement` - `CreditCardStatement` - `OfficialGovernmentLetter` - `PropertyTaxAssessment` - `TaxReturn` - `UtilityBill` - `ProofOfBusiness`: - `BusinessRegistration` - `ProofOfIdentity`: - `DriversLicense` - `NationalId` - `Passport` - `quantity` integer — The minimum number of documents required of this category - `errors` object[], nullable — Details the errors returned if verification was unsuccessful. This could contain documents and/or fields. - `code` 'InvalidDocument' | 'InvalidField' - `id` string — For `InvalidDocument` this will be the file id of the document that is invalid For `InvalidField` this will be the name of the field that is invalid - `description` string — A description of why this document/field was invalid - `persons` object, nullable — Details of the overall requirements for persons in the business. Only present if `entityType` is `Business` - `status` 'NotRequired' | 'Required' | 'PendingVerification' | 'Verified' - `required` object[] — The minimum required persons that must be created for verification. Use the Persons API to create the person and provide the relevant details so we can verify them. - … - `metadata` object, nullable — use this parameter to attach key-value data to the account. These will be sent with any associated account events on your webhooks. You can have a maximum of 5 pieces of metadata. - `settings` object — Settings for the account - `payouts` object - `schedule` object - … - `capabilities` AccountCapabilities - `visaPayments` AccountCapability - `status` 'NotRequested' | 'Pending' | 'Disabled' | 'Enabled' - `requested` boolean - `requiredFields` object[], nullable — A list of fields that must be provided prior to requesting the capability. - … - `disabledReason` string, nullable — If the capability is `Disabled`, this may contain an optional description explaining why. - `requestedTimestamp` integer — The epoch timestamp (seconds) when the capability was requested - `lastUpdatedTimestamp` integer — The epoch timestamp (seconds) when the capability was last updated - `mastercardPayments` AccountCapability - `status` 'NotRequested' | 'Pending' | 'Disabled' | 'Enabled' - `requested` boolean - `requiredFields` object[], nullable — A list of fields that must be provided prior to requesting the capability. - … - `disabledReason` string, nullable — If the capability is `Disabled`, this may contain an optional description explaining why. - `requestedTimestamp` integer — The epoch timestamp (seconds) when the capability was requested - `lastUpdatedTimestamp` integer — The epoch timestamp (seconds) when the capability was last updated - `amexPayments` AccountCapability - `status` 'NotRequested' | 'Pending' | 'Disabled' | 'Enabled' - `requested` boolean - `requiredFields` object[], nullable — A list of fields that must be provided prior to requesting the capability. - … - `disabledReason` string, nullable — If the capability is `Disabled`, this may contain an optional description explaining why. - `requestedTimestamp` integer — The epoch timestamp (seconds) when the capability was requested - `lastUpdatedTimestamp` integer — The epoch timestamp (seconds) when the capability was last updated - `inPersonPayments` AccountCapability - `status` 'NotRequested' | 'Pending' | 'Disabled' | 'Enabled' - `requested` boolean - `requiredFields` object[], nullable — A list of fields that must be provided prior to requesting the capability. - … - `disabledReason` string, nullable — If the capability is `Disabled`, this may contain an optional description explaining why. - `requestedTimestamp` integer — The epoch timestamp (seconds) when the capability was requested - `lastUpdatedTimestamp` integer — The epoch timestamp (seconds) when the capability was last updated - `termsOfService` object, nullable - `acceptance` TermsOfServiceAcceptance - `ipAddress` string — The IP address of the user who accepted the terms & conditions - `userAgent` string, nullable — The User Agent of the user's browser who has accepted the terms & conditions - `when` number — The time (in epoch seconds) when the terms & conditions were accepted. - `createdTimestamp` integer — The epoch timestamp (seconds) when the account was created - PersonResponse - `id` string — The ID of the person - `firstName` string — The first name of the person - `middleNames` string, nullable — The middle names of the person - `lastName` string — The last name / surname of the person - `email` string, email, nullable — The email address of the person - `dateOfBirth` string — The date of birth of the person, in format YYYY-MM-DD - `countryOfBirth` string, nullable — The two-character ISO 3166 country code of birth of the person - `gender` 'Female' | 'Male', nullable — The gender of the person. International regulations require either `Female` or `Male` - `nationalities` string[] — The countries of citizenship or nationality of the person - `address` object — The address of the person - `lineOne` string, nullable — First line of the address. It must satisfy the following regex pattern: ^[A-Za-z0-9 !&'()+,-./:;]*$ - `lineTwo` string, nullable — Second line of the address. It must satisfy the following regex pattern: ^[A-Za-z0-9 !&'()+,-./:;]*$ - `city` string, nullable — The address city/town It must satisfy the following regex pattern: ^[A-Za-z0-9 !&'()+,-./:;]*$ - `country` string — The two-character ISO country code - `postalCode` string, nullable — The postal/zip code of the address. It must satisfy the following regex pattern: ^[A-Za-z0-9 -]*$ - `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 Otherwise it must satisfy the following regex pattern: ^[A-Za-z0-9 !&'()+,-./:;]*$ - `phoneNumber` string, nullable — The phone number of the person, in E.164 format - `businessRoles` BusinessRole[] — The role(s) in the business that the person performs - `verification` PersonVerification — the result of submitting a person for verification - `status` 'NotRequired' | 'Required' | 'PendingVerification' | 'Verified' - `requiredFields` object[], nullable — A list of fields that must be provided for verification. - `name` string — The name of the field - `requiredDocuments` object[], nullable — A list of documents that must be provided for verification. - `category` 'Authorization' | 'ProofOfAddress' | 'ProofOfBusiness' | 'ProofOfIdentity' — The category of document, these are only applicable for certain entities: - `Authorization` is only applicable for Persons - `ProofOfAddress` is only applicable for Individuals or Persons - `ProofOfBusiness` is only applicable for Businesses - `ProofOfIdentity` is only applicable for Individuals or Persons - `types` AccountDocumentType[] — The types of document available to upload in this category - `quantity` integer — The minimum number of documents required of this category - `errors` object[], nullable — Details the errors returned if verification was unsuccessful. This could contain documents and/or fields. - `code` 'InvalidDocument' | 'InvalidField' - `id` string — For `InvalidDocument` this will be the file id of the document that is invalid For `InvalidField` this will be the name of the field that is invalid - `description` string — A description of why this document/field was invalid - `documents` AccountDocumentResponse[], nullable — The KYC documents - `type` 'BankStatement' | 'BusinessRegistration' | 'CreditCardStatement' | 'DriversLicense' | 'LetterOfAuthorization' | 'NationalId' | 'OfficialGovernmentLetter' | 'Passport' | 'PropertyTaxAssessment' | 'TaxReturn' | 'UtilityBill' — The type of document, these are only applicable for certain entities: - 'LetterOfAuthorization' is only applicable for Persons, when the 'Authorization' category is required - 'BankStatement', 'CreditCardStatement', 'OfficialGovernmentLetter', 'PropertyTaxAssessment', 'TaxReturn', 'UtilityBill' are only applicable for Individuals or Persons, when the 'ProofOfAddress' category is required - 'BusinessRegistration' is only applicable for Businesses, when the 'ProofOfBusiness' category is required - 'DriversLicense', 'NationalId', 'Passport' are only applicable for Individuals or Persons, when the 'ProofOfIdentity' category is required - `category` 'Authorization' | 'ProofOfAddress' | 'ProofOfBusiness' | 'ProofOfIdentity' — The category of document, these are only applicable for certain entities: - `Authorization` is only applicable for Persons - `ProofOfAddress` is only applicable for Individuals or Persons - `ProofOfBusiness` is only applicable for Businesses - `ProofOfIdentity` is only applicable for Individuals or Persons - `front` string — The ID of the uploaded file that shows the front of the document. - `back` string, nullable — The ID of the uploaded file that shows the back of the document. Required if uploading a `DriversLicense` or `NationalId`. - `status` 'Invalid' | 'Pending' | 'Valid' - `invalidReason` string, nullable — The reason for the document being invalid - `country` string, nullable — The two-character ISO 3166 country code of the document. Only present historically on documents with `type`: `Passport`, `DriversLicense`, `NationalId` - `assignedTimestamp` integer — The epoch timestamp (seconds) when the document was first assigned to the account - `lastUpdatedTimestamp` integer — The epoch timestamp (seconds) when the document was last updated - `metadata` object, nullable — use this parameter to attach key-value data to the person. These will be sent with any associated account events on your webhooks. You can have a maximum of 5 pieces of metadata. - `createdTimestamp` integer — The epoch timestamp (seconds) when the person was created - `lastUpdatedTimestamp` integer — The epoch timestamp (seconds) when the person was last updated - Customer - `id` string — The ID of the customer - `email` string, email — The customer's email address - `firstName` string, nullable — The first name of the customer - `lastName` string, nullable — The last name of the customer - `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 - `defaultPaymentMethod` string, nullable — The Id of the customer's preferred/default payment method - `metadata` object, nullable — use this parameter to attach key-value data to the customer. These will be sent with any associated customer events on your webhooks. You can have a maximum of 5 pieces of metadata. - `createdTimestamp` integer — The epoch timestamp (seconds) when the customer was created - PaymentMethod - `id` string — The ID of the payment method - `type` 'Card' — The type of the payment method - `card` PaymentMethodCard - `scheme` 'Visa' | 'Mastercard' | 'Amex' - `last4` string — The last 4 digits of the card - `expiryMonth` string — The 2-digit expiry month of the card - `expiryYear` string — The 4-digit expiry year of the card - `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 - `customerId` string, nullable — The Id of the customer this card belongs to (null if the payment-method is single-use) - `createdTimestamp` integer — The epoch timestamp (seconds) when the payment method was created - PayoutMethod - `id` string — The id of the payout method - `type` 'BankAccount' - `displayName` string, nullable — A friendly name for the payout method, for display only - `status` 'Invalid' | 'Valid' - `invalidReason` string, nullable — The reason why the payout method has been marked as 'Invalid' - `currency` string — The three-character ISO 4217 currency code of the payout method - `countryCode` string — The two-character ISO 3166 country code of the payout method - `bankAccount` BankAccount - `bankIdType` 'RoutingNumber' | 'SwiftCode' | 'SortCode' | 'BSBCode' | 'BankCode', nullable - `bankId` string, nullable — The id of the bank that the bank account is with, e.g. sort code / routing number (see `bankIdType`) - `branchIdType` 'TransitNumber', nullable — The types of branch ID for bank accounts. - `branchId` string, nullable — The id of the branch that the bank account is with, see BranchIdType for types. - `bankName` string, nullable — The name of the bank that the bank account is with - `swiftCode` string, nullable — The Swift code / BIC of the bank - `accountNumberType` 'Iban' | 'UnitedKingdom' | 'Domestic' - `last4` string — The last 4 digits of the account number for the bank account. This is the account number or IBAN of the bank account, depending on the currency + country of the payout method - `address` object, nullable — The address of the bank account holder - `lineOne` string, nullable — First line of the address. It must satisfy the following regex pattern: ^[A-Za-z0-9 !&'()+,-./:;]*$ - `lineTwo` string, nullable — Second line of the address. It must satisfy the following regex pattern: ^[A-Za-z0-9 !&'()+,-./:;]*$ - `city` string, nullable — The address city/town It must satisfy the following regex pattern: ^[A-Za-z0-9 !&'()+,-./:;]*$ - `country` string — The two-character ISO country code - `postalCode` string, nullable — The postal/zip code of the address. It must satisfy the following regex pattern: ^[A-Za-z0-9 -]*$ - `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 Otherwise it must satisfy the following regex pattern: ^[A-Za-z0-9 !&'()+,-./:;]*$ - `createdTimestamp` integer — The epoch timestamp (seconds) when the payout method was created - `lastUpdatedTimestamp` integer — The epoch timestamp (seconds) when the payout method was last updated - PayoutResponse - `id` string — The id of the payout - `paymentsTakenDate` string, date — Deprecated - please use the 'payoutId' param on the /balance-transactions endpoint to see transactions in a payout. - `paymentsTakenDateFrom` string, date — Deprecated - please use the 'payoutId' param on the /balance-transactions endpoint to see transactions in a payout. The date on which payments within this payout began, in the format yyyy-MM-dd - `paymentsTakenDateTo` string, date — Deprecated - please use the 'payoutId' param on the /balance-transactions endpoint to see transactions in a payout. The date on which payments within this payout end, in the format yyyy-MM-dd - `amount` integer — The total amount that was paid out, minus any fees - `currency` string — The ISO code of the payout currency - `status` 'Completed' | 'Failed' | 'PendingReview' | 'InProgress' | 'Returned' — The status of the payout - `scheduleType` 'Automatic' | 'Manual' — Whether the payout was issued automatically by Ryft or manually requested. - `payoutMethod` PayoutPayoutMethodResponse, nullable - `id` string — The payout method the payout will be or was sent to - `bankAccount` object — The bank details that the payout will be or was sent to. Note that these may be different to those currently assigned to the payout method id, if the payout method has since been updated. - `bankIdType` 'RoutingNumber' | 'SwiftCode' | 'SortCode' | 'BSBCode' | 'BankCode', nullable - `bankId` string, nullable — The id of the bank that the bank account is with. This is the sort code, swift code or routing number of the bank, depending on the currency + country of the payout method - `bankName` string, nullable — The name of the bank that the bank account is with - `branchIdType` 'TransitNumber', nullable — The types of branch ID for bank accounts. - `branchId` string, nullable — The id of the branch that the bank account is with - `swiftCode` string, nullable — The Swift code / BIC of the bank - `accountNumberType` 'Iban' | 'UnitedKingdom' | 'Domestic' - `last4` string — The last 4 digits of the account number for the bank account. This is the account number or IBAN of the bank account, depending on the currency + country of the payout method - `failureReason` string, nullable — If the payout is in the 'Failed' status, this is an additional reason to explain why - `payoutCalculation` PayoutCalculationResponse — Deprecated - please use the 'payoutId' param on the /balance-transactions endpoint to see transactions in a payout. An object containing a breakdown of how the payout was calculated - `paymentsCapturedAmount` integer — The total amount of money credited via captured payments by you or by your sub account, in the minor units of the payout currency - `paymentsRefundedAmount` integer — The total amount of money debited via refunds of payments by you or by your sub account, in the minor units of the payout currency - `paymentsSplitAmount` integer — The total amount of money debited from you via payments split with your sub accounts, in the minor units of the payout currency Note that this field is only applicable to your own payouts as the standard account, as sub accounts cannot split payments with others - `paymentsSplitRefundedAmount` integer — The total amount of money credited to you via refunds of payments split with your sub accounts, in the minor units of the payout currency Note that this field is only applicable to your own payouts as the standard account, as sub accounts cannot split payments with others - `splitPaymentsAmount` integer — The total amount of money credited via split payments that your sub account has received, in the minor units of the payout currency Note that this field is only applicable to your sub accounts payouts, as they have payments split with them - `splitPaymentsRefundedAmount` integer — The total amount of money debited via refunds of split payments that your sub account has received, in the minor units of the payout currency Note that this field is only applicable to your sub accounts payouts, as they have payments split with them - `platformFeesCollectedAmount` integer — The total amount of money credited to you via platform fees taken from sub accounts, in the minor units of the payout currency. Note that this field is only applicable to your own payouts as the standard account, as sub accounts cannot earn platform fees - `platformFeesRefundedAmount` integer — The total amount of money debited from you via platform fees refunded to sub accounts, in the minor units of the payout currency. Note that this field is only applicable to your own payouts as the standard account, as sub accounts cannot earn platform fees - `platformFeesPaidAmount` integer — The total amount of money debited via platform fees paid to you by your sub accounts, in the minor units of the payout currency. Note that this field is only applicable to your sub accounts payouts, as they pay platform fees - `processingFeesPaidAmount` integer — The total amount of money debited via processing fees paid by either you or your sub accounts, in the minor units of the payout currency. Note that this is applicable to whoever pays the processing fee on payments, and includes fees from chargebacks - `chargebacksAmount` integer — The total amount of money debited via chargebacks raised for your payments, in the minor units of the payout currency. Note that this value excludes chargebacks raised for your sub account payments - see 'platformChargebacksAmount' - `chargebackReversalsAmount` integer — The total amount of money credited via reversals of chargebacks raised for your payments, in the minor units of the payout currency. Note that this value excludes chargebacks raised for your sub account payments - see 'platformChargebackReversalsAmount' - `platformChargebacksAmount` integer — The total amount of money debited via chargebacks raised for your sub accounts payments, in the minor units of the payout currency. - `platformChargebackReversalsAmount` integer — The total amount of money credited via reversals of chargebacks raised for your sub accounts payments, in the minor units of the payout currency. - `transferredInAmount` integer — The total amount of money credited via money transferred into your account, in the minor units of the payout currency. - `transferredOutAmount` integer — The total amount of money debited via money transferred out of your account, in the minor units of the payout currency. - `payoutAmount` integer — The total amount of money paid to you or your sub account, in the minor units of the payout currency - `currency` string — The ISO code of the payout currency - `numberOfPaymentsCaptured` integer — The total number of payments captured by you or your sub account - `numberOfPaymentsRefunded` integer — The total number of payments refunded by you or your sub account - `numberOfPaymentsSplit` integer — The total number of payments split with your sub accounts Note that this field is only applicable to your own payouts as the standard account, as sub accounts cannot split payments with others - `numberOfPaymentsSplitRefunded` integer — The total number of refunds for payments split with your sub accounts Note that this field is only applicable to your own payouts as the standard account, as sub accounts cannot split payments with others - `numberOfSplitPayments` integer — The total number of split payments that your sub account has received Note that this field is only applicable to your sub accounts payouts, as they have payments split with them - `numberOfSplitPaymentsRefunded` integer — The total number of split payments that your sub account has received Note that this field is only applicable to your sub accounts payouts, as they have payments split with them - `numberOfPlatformFeesCollected` integer — The total number of platform fees collected. Note that this field is only applicable to your own payouts as the standard account, as sub accounts cannot earn platform fees - `numberOfPlatformFeesRefunded` integer — The total number of platform fees refunded. Note that this field is only applicable to your own payouts as the standard account, as sub accounts cannot earn platform fees - `numberOfChargebacks` integer — The total number of chargebacks that were raised for your accounts payments. - `numberOfChargebackReversals` integer — The total number of chargebacks that were reversed for your accounts payments. - `numberOfPlatformChargebacks` integer — The total number of chargebacks that were raised for your sub accounts payments. - `numberOfPlatformChargebackReversals` integer — The total number of chargebacks that were reversed for your sub accounts payments. - `numberOfTransfersIn` integer — The total number of transfers made that transferred funds into your account. - `numberOfTransfersOut` integer — The total number of transfers made that transferred funds out of your account. - `numberOfCustomers` integer — The total number of unique customers that made payments to you or your sub accounts - `numberOfNewCustomers` integer, nullable — The total number of unique customers that made their first payments to you or your sub accounts on the date these payments were made - `scheme` 'Ach' | 'Bacs' | 'Certis' | 'Chaps' | 'DataclearingenAch' | 'DirectEntry' | 'ElectronicFundsTransfer' | 'Elixir' | 'Fast' | 'FedAch' | 'Fps' | 'GiroZrt' | 'NorwegianInterbankClearingSystem' | 'Swift' | 'Sepa' | 'SepaInstant' | 'StraksclearingInstant' | 'SwissInterbankClearing' | 'TransFonDSentAch', nullable — The scheme used to payout to your account - `createdTimestamp` integer — The epoch timestamp (seconds) when the payout was created - `scheduledTimestamp` integer — epoch timestamp of when the payout is scheduled to be paid - `completedTimestamp` integer, nullable — epoch timestamp of when the payout moved to the 'Completed' status, i.e. when it was paid out - `metadata` object, nullable — Your custom key-value data for the payout. You can have a maximum of 5 pieces of metadata. - PlatformFee - `id` string — The unique identifier for the platform fee - `paymentSessionId` string — The unique payment session that this platform fee relates to - `amount` integer — The amount of the fee you collected on top of a payment for a linked account - `paymentAmount` integer — The amount of the associated payment - `processingFee` integer — This field is now deprecated. Please use the /balance-transactions endpoint to see the fees paid on these transactions. The processing fee that is taken from the original payment. This amount is then deducted from the amount you collect as your fee from the transaction. - `refundedAmount` integer — The amount of the platform fee that was refunded - `netAmount` integer — This field is now deprecated. Please use the /balance-transactions endpoint to see the net amount for these transactions. The net amount you take once fees have been deducted. - `currency` string — The ISO currency code - `fromAccountId` string — The account that you collected the fee from - `createdTimestamp` integer — The epoch timestamp (seconds) when the payment was created - Subscription - `id` string — The ID of the subscription - `status` 'Pending' | 'Active' | 'Cancelled' | 'PastDue' | 'Ended' | 'Paused' - `description` string, nullable — (optional) description helps you personalise/identify the specific subscription - `customer` object - `id` string — The Id of the customer this subscription belongs to - `paymentMethod` object, nullable - `id` string — The Id of the PaymentMethod belonging to the customer that will be used to pay for the subscription - `paymentSessions` object - `initial` SubscriptionPaymentSession - `id` string — The Id of the PaymentSession - `clientSecret` string, nullable — The client secret of the payment session, only supplied when action is required by the customer Supply this to the frontend (web/iOS/Android) to collect the payment details / handle any required actions (3ds) - `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) - … - `latest` SubscriptionPaymentSession - `id` string — The Id of the PaymentSession - `clientSecret` string, nullable — The client secret of the payment session, only supplied when action is required by the customer Supply this to the frontend (web/iOS/Android) to collect the payment details / handle any required actions (3ds) - `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) - … - `price` RecurringPrice - `amount` integer — The amount (in minor units) that is charged on each recurring payment - `currency` string — The ISO currency code - `interval` RecurringInterval - `unit` 'Days' | 'Months' — The type of interval to wait for between charges - `count` number — The number of intervals between charges. e.g. `type = Days` & `count = 60` would charge the customer every 60 days. - `times` number, nullable — (optional) The total number of charges throughout the lifecycle of the recurring series. Leave `null` for products that continue indefinitely. - `balance` SubscriptionBalance — The full outstanding amount owed by the customer for this subscription. Any outstanding amount will be included in future cycle payments (on top of the recurring price) - `amount` integer — The amount owed (in minor units of the currency in price) - `pausePaymentDetail` object, nullable — Non-null if you have paused payments for the subscription. - `reason` string, nullable — Field describing why the subscription is paused. - `resumeAtTimestamp` number, nullable — The epoch timestamp (seconds) when the subscription should resume collecting payments - `pausedAtTimestamp` number — The epoch timestamp (seconds) when the subscription was paused - `cancelDetail` object, nullable — Non-null if the subscription is cancelled - `reason` string, nullable — Field describing why the subscription is cancelled. - `cancelledAtTimestamp` integer — The epoch timestamp (seconds) when the subscription was cancelled - `billingDetail` object - `totalCycles` number — The total number of billing cycles throughout the lifespan of the subscription. - `currentCycle` number — The subscription's current billing cycle. e.g. given a monthly subscription for a 12 month recurring product, where the current date is 4 months removed from the initial charge will have `currentCycle = 4` - `currentCycleStartTimestamp` number — The (epoch) timestamp representing the start date for the current billing period. - `currentCycleEndTimestamp` number — The (epoch) timestamp representing the end date for the current billing period. - `billingCycleTimestamp` number — The (epoch) timestamp representing the date on which the customer will regularly be billed. e.g. 15th of each month. - `nextBillingTimestamp` number, nullable — The (epoch) timestamp representing the date on which we will next try to bill your customer. This will be equal to the `billingCycleTimestamp` at the start of each new billing cycle, but is updated should we fail to successfully charge the customer. The updated timestamp reflects when our recurring engine will retry payment. When 'null' it means that we are not currently planning to bill the customer again (it is Cancelled, Ended or Paused indefinitely) - `failureDetail` object, nullable — Non-null if the Subscription has become `PastDue` and one or more payment attempts have been unsuccessful. - `paymentAttempts` number — The number of consecutive payment attempts that have failed. - `lastPaymentError` '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. - `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 - `metadata` object, nullable — use this parameter to attach key-value data to the subscription. These will be sent with any subscription events to your webhooks. You can have a maximum of 5 pieces of metadata. - `paymentSettings` object — Settings for controlling fields/options on the underlying Payment Session's created by this subscription. - `statementDescriptor` NullableStatementDescriptor, nullable - `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 ]*$ - `createdTimestamp` integer — The epoch timestamp (seconds) when the subscription was created - Dispute - `id` string — The ID of the dispute - `amount` integer — The amount that is being disputed and the merchant is liable for - `currency` string — The ISO currency code - `status` 'Open' | 'Cancelled' | 'Accepted' | 'Challenged' | 'Lost' | 'Won' | 'Expired' - `category` 'Fraudulent' | 'Authorization' | 'ProcessingError' | 'CardholderDispute' | 'General' — Disputes are grouped into a specific category based on their `reason.code`. These define the overlapping reason across various card schemes (who each have their own codes) - `reason` DisputeReason - `code` string — The reason code provided by the card scheme - `description` string — Description of the `code` - `respondBy` integer — The deadline by which the evidence needs responding by. Note that you cannot attach evidence or challenge the dispute once this date has passed. The dispute will move to `Expired`. - `recommendedEvidence` string[] — The evidence **strongly** recommended for the best chance to challenge and win the dispute. Note that this is based on the underlying `reason.code` of the Dispute and is subject to change should further types of evidence be added or no longer supported. Leverage this field to select the best forms of evidence should you choose to challenge the dispute. - `paymentSession` DisputePaymentSession — Details of the payment session linked to the dispute. - `id` string — The ID of the payment session the dispute relates to. - `paymentType` 'Standard' | 'Unscheduled' | 'MOTO' | 'Recurring' - `paymentMethod` object - `card` object — Details of the card used - … - `evidence` DisputeEvidence, nullable — The text/file evidence you have attached to the dispute. - `text` DisputeEvidenceTextEntries, nullable — Contains any evidence in text format - `billingAddress` string, nullable — Billing address provided by the customer on the original transaction. We will automatically append this if it was provided. - `shippingAddress` string, nullable — Shipping address the product or service were shipped to. Note we recommend also attaching any supporting files you have that confirm shipment to the same address. We will automatically append this if it was provided, however you can amend it if the address after taking payment with Ryft. - `duplicateTransaction` string, nullable — Relevant when category is `Duplicate`. Use this to attach an explanation detailing why the transaction in dispute is unique and not in fact a duplicate of a previous transaction. - `uncategorised` string, nullable — Any miscellanous text evidence you have attached. - `files` DisputeEvidenceFiles, nullable — Contains any evidence in file format - `proofOfDelivery` DisputeEvidenceFile, nullable — Details pointing to an uploaded file containing the relevant evidence - … - `customerSignature` DisputeEvidenceFile, nullable — Details pointing to an uploaded file containing the relevant evidence - … - `receipt` DisputeEvidenceFile, nullable — Details pointing to an uploaded file containing the relevant evidence - … - `shippingConfirmation` DisputeEvidenceFile, nullable — Details pointing to an uploaded file containing the relevant evidence - … - `customerCommunication` DisputeEvidenceFile, nullable — Details pointing to an uploaded file containing the relevant evidence - … - `refundPolicy` DisputeEvidenceFile, nullable — Details pointing to an uploaded file containing the relevant evidence - … - `recurringPaymentAgreement` DisputeEvidenceFile, nullable — Details pointing to an uploaded file containing the relevant evidence - … - `uncategorised` DisputeEvidenceFile, nullable — Details pointing to an uploaded file containing the relevant evidence - … - `customer` DisputeCustomer, nullable — Details of the customer who is making the dispute - `email` string, nullable — The email that was used for the disputed payment - `id` string, nullable — The Ryft ID of the customer - `createdTimestamp` integer, nullable — The epoch timestamp (seconds) when the customer was first recorded/created - `subAccount` DisputeSubAccount, nullable — If this dispute is for a payment under a sub account, then this contains details of that account - `id` string — The Ryft ID of the sub account - `createdTimestamp` integer — The epoch timestamp (seconds) when the dispute was created - `lastUpdatedTimestamp` integer — The epoch timestamp (seconds) when the dispute was last updated - Transfer - `id` string — The unique id of the transfer - `status` 'Pending' | 'Declined' | 'Completed' — The status the transfer is currently in - `amount` integer — The transfer amount (in minor units) - `currency` string — The ISO currency code - `reason` string, nullable — An optional reason describing why the transfer was initiated. - `source` object, nullable — Where the `amount` was taken from - `accountId` string — ID of the Ryft account that funds were taken from - `destination` object, nullable — Where the `amount` will be credited to - `accountId` string — ID of the Ryft account that will receive the funds - `errors` object[], nullable — Details any errors explaining why the transfer was `Declined`. - `code` string — code for the error - `description` string — Text describing the error - `metadata` object, nullable — Your custom key-value data for the transfer. You can have a maximum of 5 pieces of metadata. - `createdTimestamp` integer — The epoch timestamp (seconds) when the transfer was created - `lastUpdatedTimestamp` integer — The epoch timestamp (seconds) when the transfer was last updated - `endpoints` EventEndpoint[] — The webhook endpoints that this event was sent to. Note that this is only present on the `/events` API. - `webhookId` string — The unique id of the webhook endpoint - `acknowledged` boolean — Whether the webhook endpoint has received and acknowledged the event - `attempts` integer — How many times we have attempted to deliver the event to the webhook endpoint - `accountId` string, nullable — The account id in which this event happened. - `createdTimestamp` integer — The epoch timestamp (seconds) when the event was created ## Other responses - `400` — One or more inputs are invalid - `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/revisions/a042f64d4305/schema)