> For the complete documentation index, see [llms.txt](https://plexo.gitbook.io/rest-api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://plexo.gitbook.io/rest-api/api-reference/models.md). # API Models ## Customers ### CustomerDto ## The CustomerDto object ```json {"openapi":"3.1.1","info":{"title":"Core.API","version":"v2"},"components":{"schemas":{"CustomerDto":{"type":"object","properties":{"id":{"type":["null","string"],"description":"Unique identifier for the customer assigned by Plexo."},"referenceId":{"type":["null","string"],"description":"External reference identifier for the customer from your system."},"metadata":{"type":["null","object"],"additionalProperties":{"type":"string"},"description":"Custom key-value pairs for storing additional customer information."},"description":{"type":["null","string"],"description":"Optional description or notes about the customer."},"email":{"type":["null","string"],"description":"Customer's email address."},"name":{"type":["null","string"],"description":"Customer's full name (computed property)."},"phone":{"type":["null","string"],"description":"Customer's phone number with country code."},"firstName":{"type":["null","string"],"description":"Customer's first name or given name."},"lastName":{"type":["null","string"],"description":"Customer's last name or family name."},"document":{"oneOf":[{"type":"null"},{"description":"Primary identification document (e.g., national ID, driver's license).","$ref":"#/components/schemas/DocumentDto"}]},"identification":{"oneOf":[{"type":"null"},{"description":"Secondary identification document or tax identification number.","$ref":"#/components/schemas/DocumentDto"}]},"birthdate":{"type":["null","string"],"description":"Customer's date of birth.","format":"date-time"},"address":{"oneOf":[{"type":"null"},{"description":"Customer's billing or primary address.","$ref":"#/components/schemas/AddressDto"}]},"shipping":{"oneOf":[{"type":"null"},{"description":"Customer's shipping address and contact information.","$ref":"#/components/schemas/ShippingDto"}]},"status":{"type":["null","string"],"description":"Current status of the customer account."}},"description":"Customer profile used in customer, payment, and session responses."},"DocumentDto":{"type":"object","properties":{"type":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["null","integer","string"],"description":"Type of the identification document.","format":"int32"},"value":{"type":["null","string"],"description":"Document number or identifier value."}},"description":"Represents an identification or legal document for a customer."},"AddressDto":{"type":"object","properties":{"city":{"type":["null","string"],"description":"City or locality name."},"country":{"type":["null","string"],"description":"Two-letter ISO country code (ISO 3166-1 alpha-2)."},"line1":{"type":"string","description":"Primary address line (street address, P.O. box, company name, etc.)."},"line2":{"type":["null","string"],"description":"Secondary address line (apartment, suite, unit, building, floor, etc.)."},"postalCode":{"type":["null","string"],"description":"ZIP or postal code."},"state":{"type":["null","string"],"description":"State, province, prefecture, or region."}},"description":"Represents a physical address for billing or shipping purposes."},"ShippingDto":{"type":"object","properties":{"address":{"description":"Physical delivery address for shipping.","$ref":"#/components/schemas/AddressDto"},"name":{"type":"string","description":"Name of the person receiving the shipment."},"phone":{"type":"string","description":"Contact phone number for delivery coordination."}},"description":"Shipping information for delivering physical goods to a customer."}}}} ``` ## Payments ### PaymentRequestDto ## The PaymentRequestDto object ```json {"openapi":"3.1.1","info":{"title":"Core.API","version":"v2"},"components":{"schemas":{"PaymentRequestDto":{"type":"object","properties":{"merchantId":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"description":"The unique identifier of the merchant receiving the payment.","format":"int32"},"flow":{"type":["null","string"],"description":"The payment processing flow. Determines how the payment is processed."},"referenceId":{"type":"string","description":"Your unique reference identifier for this payment transaction."},"invoiceNumber":{"type":"string","description":"The invoice number associated with this payment."},"paymentMethod":{"description":"The payment method details including card, token, or alternative payment method.","$ref":"#/components/schemas/PaymentMethodRequestDto"},"items":{"type":["null","array"],"items":{"$ref":"#/components/schemas/PaymentRequestItem"},"description":"Optional list of items included in the payment."},"installments":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"description":"Number of installments for the payment.","format":"int32"},"amount":{"description":"The payment amount details including total and currency.","$ref":"#/components/schemas/PaymentAmountDto"},"browserDetails":{"oneOf":[{"type":"null"},{"description":"Browser and device details of the customer initiating the payment.","$ref":"#/components/schemas/BrowserDetailsDto"}]},"statementDescriptor":{"type":["null","string"],"description":"Text to be displayed on the customer's bank or card statement."},"capture":{"oneOf":[{"type":"null"},{"description":"Capture strategy configuration for the payment.","$ref":"#/components/schemas/PaymentCaptureDto"}]},"customerId":{"type":["null","string"],"description":"The unique identifier of the customer making the payment."},"redirectUrl":{"type":["null","string"],"description":"URL to redirect customer after payment completion (for redirect flow)."},"callbackUrl":{"type":["null","string"],"description":"URL to receive asynchronous payment status notifications by callback."},"recurring":{"oneOf":[{"type":"null"},{"description":"Recurring payment configuration for subscription or repeat billing.","$ref":"#/components/schemas/RecurringDto"}]},"metadata":{"type":["null","object"],"additionalProperties":{"type":"string"},"description":"Custom metadata key-value pairs for merchant's internal use."}},"description":"Request body for creating a payment."},"PaymentMethodRequestDto":{"type":"object","properties":{"source":{"type":["null","string"],"description":"The type of payment method source."},"id":{"type":["null","string"],"description":"The payment method identifier (card brand). Required when source='network-token'."},"card":{"oneOf":[{"type":"null"},{"description":"Direct card details. Required when source='card'.","$ref":"#/components/schemas/CardRequestDto"}]},"paymentInstrument":{"oneOf":[{"type":"null"},{"description":"Tokenized payment instrument. Required when source='token'.","$ref":"#/components/schemas/TokenizedCard"}]},"networkToken":{"oneOf":[{"type":"null"},{"description":"Network tokenized card with cryptogram. Required when source='network-token'.","$ref":"#/components/schemas/NetworkTokenizedCardDto"}]},"googlePayToken":{"oneOf":[{"type":"null"},{"description":"Google Pay encrypted token. Required when source='google-pay-token'.","$ref":"#/components/schemas/GooglePayTokenDto"}]},"applePayToken":{"oneOf":[{"type":"null"},{"description":"Apple Pay encrypted token. Required when source='apple-pay-token'.","$ref":"#/components/schemas/ApplePayTokenDto"}]},"clickToPayToken":{"oneOf":[{"type":"null"},{"description":"Mastercard Click to Pay encrypted token. Required when source='click-to-pay-token'.","$ref":"#/components/schemas/ClickToPayTokenDto"}]},"fields":{"type":["null","object"],"additionalProperties":{"type":"string"},"description":"Additional processor-specific fields."}},"description":"Represents the payment method details for a payment transaction."},"CardRequestDto":{"type":"object","properties":{"number":{"type":"string","description":"The card number (PAN - Primary Account Number)."},"expMonth":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"description":"The card expiration month (1-12).","format":"int32"},"expYear":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"description":"The card expiration year (4-digit format).","format":"int32"},"cvc":{"type":["null","string"],"description":"The card security code (CVV/CVC)."},"cardholder":{"oneOf":[{"type":"null"},{"description":"The cardholder information (name, address, etc.).","$ref":"#/components/schemas/CardHolderDto"}]},"tokenizationSettings":{"oneOf":[{"type":"null"},{"description":"Tokenization settings controlling if/how card should be saved.","$ref":"#/components/schemas/TokenizationSettings"}]},"metadata":{"type":["null","object"],"additionalProperties":{"type":"string"},"description":"Additional card metadata (3DS data, etc.)."}},"description":"Represents direct card details for a payment."},"CardHolderDto":{"type":"object","properties":{"firstName":{"type":["null","string"],"description":"The first name of the cardholder."},"lastName":{"type":["null","string"],"description":"The last name of the cardholder."},"email":{"type":["null","string"],"description":"The email address of the cardholder."},"birthdate":{"type":["null","string"],"description":"The birthdate of the cardholder.","format":"date-time"},"identification":{"oneOf":[{"type":"null"},{"description":"The identification details of the cardholder.","$ref":"#/components/schemas/DocumentDto"}]},"billingAddress":{"oneOf":[{"type":"null"},{"description":"The billing address of the cardholder.","$ref":"#/components/schemas/AddressDto"}]},"phoneNumber":{"type":["null","string"],"description":"The phone number of the cardholder."}},"description":"Represents the details of a cardholder."},"DocumentDto":{"type":"object","properties":{"type":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["null","integer","string"],"description":"Type of the identification document.","format":"int32"},"value":{"type":["null","string"],"description":"Document number or identifier value."}},"description":"Represents an identification or legal document for a customer."},"AddressDto":{"type":"object","properties":{"city":{"type":["null","string"],"description":"City or locality name."},"country":{"type":["null","string"],"description":"Two-letter ISO country code (ISO 3166-1 alpha-2)."},"line1":{"type":"string","description":"Primary address line (street address, P.O. box, company name, etc.)."},"line2":{"type":["null","string"],"description":"Secondary address line (apartment, suite, unit, building, floor, etc.)."},"postalCode":{"type":["null","string"],"description":"ZIP or postal code."},"state":{"type":["null","string"],"description":"State, province, prefecture, or region."}},"description":"Represents a physical address for billing or shipping purposes."},"TokenizationSettings":{"type":"object","properties":{"type":{"type":"string","description":"The type of tokenization. Possible values: \"temporal\", \"store\"."},"expiration":{"type":["null","string"],"description":"The expiration date and time of the tokenization.","format":"date-time"}},"description":"Represents the tokenization settings of a card."},"TokenizedCard":{"type":"object","properties":{"token":{"type":"string","description":"The payment instrument token."},"cvc":{"type":["null","string"],"description":"The card security code (CVV/CVC) if required."}},"description":"Represents a tokenized payment instrument for recurring payments."},"NetworkTokenizedCardDto":{"type":"object","properties":{"number":{"type":"string","description":"The network token (replaces PAN)."},"expMonth":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"description":"The token expiration month (1-12).","format":"int32"},"expYear":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"description":"The token expiration year (4-digit format).","format":"int32"},"cryptogram":{"type":"string","description":"The dynamic cryptogram for this transaction."},"cardholder":{"oneOf":[{"type":"null"},{"description":"The cardholder information.","$ref":"#/components/schemas/CardHolderDto"}]},"tokenizationSettings":{"oneOf":[{"type":"null"},{"description":"Tokenization settings (usually not applicable for network tokens).","$ref":"#/components/schemas/TokenizationSettings"}]},"metadata":{"type":["null","object"],"additionalProperties":{"type":"string"},"description":"Additional network token metadata."}},"description":"Represents a network-tokenized card with cryptogram (MDES/VTS)."},"GooglePayTokenDto":{"type":"object","properties":{"token":{"type":"string","description":"Base64-encoded Google Pay token JSON string."},"cvc":{"type":["null","string"],"description":"Card security code (CVV/CVC) to use when a PAN_ONLY Google Pay payment needs CVV instead of 3D Secure."},"cardholder":{"oneOf":[{"type":"null"},{"description":"Cardholder information.","$ref":"#/components/schemas/CardHolderDto"}]},"tokenizationSettings":{"oneOf":[{"type":"null"},{"description":"Tokenization settings (if card should be saved after decryption).","$ref":"#/components/schemas/TokenizationSettings"}]},"metadata":{"type":["null","object"],"additionalProperties":{"type":"string"},"description":"Additional metadata."}},"description":"Represents a Google Pay encrypted payment token."},"ApplePayTokenDto":{"type":"object","properties":{"token":{"type":"string","description":"Apple Pay token JSON string (PKPaymentToken serialized)."},"cardholder":{"oneOf":[{"type":"null"},{"description":"Cardholder information.","$ref":"#/components/schemas/CardHolderDto"}]},"tokenizationSettings":{"oneOf":[{"type":"null"},{"description":"Tokenization settings (if card should be saved after decryption).","$ref":"#/components/schemas/TokenizationSettings"}]},"metadata":{"type":["null","object"],"additionalProperties":{"type":"string"},"description":"Additional metadata."}},"description":"Represents an Apple Pay encrypted payment token."},"ClickToPayTokenDto":{"type":"object","properties":{"token":{"type":"string","description":"Encrypted payload from Mastercard Click to Pay checkout."},"cardholder":{"oneOf":[{"type":"null"},{"description":"Cardholder information (optional, provided by Mastercard).","$ref":"#/components/schemas/CardHolderDto"}]},"tokenizationSettings":{"oneOf":[{"type":"null"},{"description":"Tokenization settings — Phase 5 supports temporal only.","$ref":"#/components/schemas/TokenizationSettings"}]},"metadata":{"type":["null","object"],"additionalProperties":{"type":"string"},"description":"Non-sensitive metadata (sanitized before storage)."}},"description":"Represents a Mastercard Click to Pay encrypted payment token."},"PaymentRequestItem":{"type":"object","properties":{"referenceId":{"type":"string","description":"The reference identifier of the item (e.g., SKU or Id)."},"name":{"type":"string","description":"The name of the item."},"description":{"type":["null","string"],"description":"The description of the item."},"quantity":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"description":"The quantity of the item.","format":"int32"},"price":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["number","string"],"description":"The price per unit of the item.","format":"double"},"discount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["null","number","string"],"description":"The discount applied to the item.","format":"double"},"metadata":{"type":["null","object"],"additionalProperties":{"type":"string"},"description":"The metadata associated with the item."},"tax":{"oneOf":[{"type":"null"},{"description":"The tax amount details for the item.","$ref":"#/components/schemas/TaxAmountDto"}]}},"description":"Represents an item in a payment request."},"TaxAmountDto":{"type":"object","properties":{"type":{"type":["null","string"],"description":"The type of tax. Possible values: \"19210\", \"17934\", \"none\"."},"amount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["number","string"],"description":"The amount of tax.","format":"double"},"rate":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["null","number","string"],"description":"The rate of tax. As decimal value.","format":"double"}},"description":"Represents the tax amount details."},"PaymentAmountDto":{"required":["currency"],"type":"object","properties":{"currency":{"maxLength":3,"minLength":0,"type":"string","description":"The currency of the payment amount.\nThe value should be an ISO Alpha code, such as UYU or USD."},"total":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["number","string"],"description":"The total amount of the payment.","format":"double"},"details":{"oneOf":[{"type":"null"},{"description":"The detailed breakdown of the payment amount.","$ref":"#/components/schemas/PaymentAmountDetailsDto"}]}},"description":"Represents the amount details of a payment."},"PaymentAmountDetailsDto":{"type":"object","properties":{"tax":{"oneOf":[{"type":"null"},{"description":"The tax amount details.","$ref":"#/components/schemas/TaxAmountDto"}]},"taxedAmount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["number","string"],"description":"The taxable amount.","format":"double"},"tipAmount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["null","number","string"],"description":"The tip amount.","format":"double"},"discountAmount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["null","number","string"],"description":"The discount amount.","format":"double"},"shippingAmount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["null","number","string"],"description":"The shipping amount.","format":"double"},"loyaltyProgram":{"oneOf":[{"type":"null"},{"description":"The loyalty program details.","$ref":"#/components/schemas/LoyaltyProgramDto"}]}},"description":"Represents the detailed breakdown of the payment amount."},"LoyaltyProgramDto":{"type":"object","properties":{"amount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["null","number","string"],"format":"double"},"provider":{"type":["null","string"]}}},"BrowserDetailsDto":{"type":"object","properties":{"ipAddress":{"type":["null","string"],"description":"Public IP address observed for the payer's browser or device."},"deviceFingerprint":{"type":["null","string"],"description":"Merchant-generated device fingerprint or browser identifier, when available."},"userAgent":{"type":["null","string"],"description":"Full browser user-agent string from the payer's device."},"device":{"type":["null","string"],"description":"High-level device type, such as desktop, mobile, or tablet."},"operativeSystem":{"type":["null","string"],"description":"Operating system reported by the payer's device, such as iOS, Android, Windows, or macOS."}},"description":"Represents the details of a browser used in a payment transaction."},"PaymentCaptureDto":{"type":"object","properties":{"method":{"type":"string","description":"Controls when the funds will be captured from the customer’s account.\nPossible values: \"automatic\", \"manual\"."},"delay":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["null","integer","string"],"description":"Optional, custom automatic capture delay in seconds.","format":"int32"}},"description":"Represents the details for capturing a payment."},"RecurringDto":{"type":"object","properties":{"parentId":{"type":["null","string"],"description":"The unique identifier of the parent payment."},"action":{"type":"string","description":"The action to be performed. Possible values: \"setup\" or \"execute\"."},"indicator":{"type":["null","string"],"description":"The indicator for the recurring payment."}},"description":"Represents the details for a recurring payment."}}}} ``` ### PaymentMethodRequestDto ## The PaymentMethodRequestDto object ```json {"openapi":"3.1.1","info":{"title":"Core.API","version":"v2"},"components":{"schemas":{"PaymentMethodRequestDto":{"type":"object","properties":{"source":{"type":["null","string"],"description":"The type of payment method source."},"id":{"type":["null","string"],"description":"The payment method identifier (card brand). Required when source='network-token'."},"card":{"oneOf":[{"type":"null"},{"description":"Direct card details. Required when source='card'.","$ref":"#/components/schemas/CardRequestDto"}]},"paymentInstrument":{"oneOf":[{"type":"null"},{"description":"Tokenized payment instrument. Required when source='token'.","$ref":"#/components/schemas/TokenizedCard"}]},"networkToken":{"oneOf":[{"type":"null"},{"description":"Network tokenized card with cryptogram. Required when source='network-token'.","$ref":"#/components/schemas/NetworkTokenizedCardDto"}]},"googlePayToken":{"oneOf":[{"type":"null"},{"description":"Google Pay encrypted token. Required when source='google-pay-token'.","$ref":"#/components/schemas/GooglePayTokenDto"}]},"applePayToken":{"oneOf":[{"type":"null"},{"description":"Apple Pay encrypted token. Required when source='apple-pay-token'.","$ref":"#/components/schemas/ApplePayTokenDto"}]},"clickToPayToken":{"oneOf":[{"type":"null"},{"description":"Mastercard Click to Pay encrypted token. Required when source='click-to-pay-token'.","$ref":"#/components/schemas/ClickToPayTokenDto"}]},"fields":{"type":["null","object"],"additionalProperties":{"type":"string"},"description":"Additional processor-specific fields."}},"description":"Represents the payment method details for a payment transaction."},"CardRequestDto":{"type":"object","properties":{"number":{"type":"string","description":"The card number (PAN - Primary Account Number)."},"expMonth":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"description":"The card expiration month (1-12).","format":"int32"},"expYear":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"description":"The card expiration year (4-digit format).","format":"int32"},"cvc":{"type":["null","string"],"description":"The card security code (CVV/CVC)."},"cardholder":{"oneOf":[{"type":"null"},{"description":"The cardholder information (name, address, etc.).","$ref":"#/components/schemas/CardHolderDto"}]},"tokenizationSettings":{"oneOf":[{"type":"null"},{"description":"Tokenization settings controlling if/how card should be saved.","$ref":"#/components/schemas/TokenizationSettings"}]},"metadata":{"type":["null","object"],"additionalProperties":{"type":"string"},"description":"Additional card metadata (3DS data, etc.)."}},"description":"Represents direct card details for a payment."},"CardHolderDto":{"type":"object","properties":{"firstName":{"type":["null","string"],"description":"The first name of the cardholder."},"lastName":{"type":["null","string"],"description":"The last name of the cardholder."},"email":{"type":["null","string"],"description":"The email address of the cardholder."},"birthdate":{"type":["null","string"],"description":"The birthdate of the cardholder.","format":"date-time"},"identification":{"oneOf":[{"type":"null"},{"description":"The identification details of the cardholder.","$ref":"#/components/schemas/DocumentDto"}]},"billingAddress":{"oneOf":[{"type":"null"},{"description":"The billing address of the cardholder.","$ref":"#/components/schemas/AddressDto"}]},"phoneNumber":{"type":["null","string"],"description":"The phone number of the cardholder."}},"description":"Represents the details of a cardholder."},"DocumentDto":{"type":"object","properties":{"type":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["null","integer","string"],"description":"Type of the identification document.","format":"int32"},"value":{"type":["null","string"],"description":"Document number or identifier value."}},"description":"Represents an identification or legal document for a customer."},"AddressDto":{"type":"object","properties":{"city":{"type":["null","string"],"description":"City or locality name."},"country":{"type":["null","string"],"description":"Two-letter ISO country code (ISO 3166-1 alpha-2)."},"line1":{"type":"string","description":"Primary address line (street address, P.O. box, company name, etc.)."},"line2":{"type":["null","string"],"description":"Secondary address line (apartment, suite, unit, building, floor, etc.)."},"postalCode":{"type":["null","string"],"description":"ZIP or postal code."},"state":{"type":["null","string"],"description":"State, province, prefecture, or region."}},"description":"Represents a physical address for billing or shipping purposes."},"TokenizationSettings":{"type":"object","properties":{"type":{"type":"string","description":"The type of tokenization. Possible values: \"temporal\", \"store\"."},"expiration":{"type":["null","string"],"description":"The expiration date and time of the tokenization.","format":"date-time"}},"description":"Represents the tokenization settings of a card."},"TokenizedCard":{"type":"object","properties":{"token":{"type":"string","description":"The payment instrument token."},"cvc":{"type":["null","string"],"description":"The card security code (CVV/CVC) if required."}},"description":"Represents a tokenized payment instrument for recurring payments."},"NetworkTokenizedCardDto":{"type":"object","properties":{"number":{"type":"string","description":"The network token (replaces PAN)."},"expMonth":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"description":"The token expiration month (1-12).","format":"int32"},"expYear":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"description":"The token expiration year (4-digit format).","format":"int32"},"cryptogram":{"type":"string","description":"The dynamic cryptogram for this transaction."},"cardholder":{"oneOf":[{"type":"null"},{"description":"The cardholder information.","$ref":"#/components/schemas/CardHolderDto"}]},"tokenizationSettings":{"oneOf":[{"type":"null"},{"description":"Tokenization settings (usually not applicable for network tokens).","$ref":"#/components/schemas/TokenizationSettings"}]},"metadata":{"type":["null","object"],"additionalProperties":{"type":"string"},"description":"Additional network token metadata."}},"description":"Represents a network-tokenized card with cryptogram (MDES/VTS)."},"GooglePayTokenDto":{"type":"object","properties":{"token":{"type":"string","description":"Base64-encoded Google Pay token JSON string."},"cvc":{"type":["null","string"],"description":"Card security code (CVV/CVC) to use when a PAN_ONLY Google Pay payment needs CVV instead of 3D Secure."},"cardholder":{"oneOf":[{"type":"null"},{"description":"Cardholder information.","$ref":"#/components/schemas/CardHolderDto"}]},"tokenizationSettings":{"oneOf":[{"type":"null"},{"description":"Tokenization settings (if card should be saved after decryption).","$ref":"#/components/schemas/TokenizationSettings"}]},"metadata":{"type":["null","object"],"additionalProperties":{"type":"string"},"description":"Additional metadata."}},"description":"Represents a Google Pay encrypted payment token."},"ApplePayTokenDto":{"type":"object","properties":{"token":{"type":"string","description":"Apple Pay token JSON string (PKPaymentToken serialized)."},"cardholder":{"oneOf":[{"type":"null"},{"description":"Cardholder information.","$ref":"#/components/schemas/CardHolderDto"}]},"tokenizationSettings":{"oneOf":[{"type":"null"},{"description":"Tokenization settings (if card should be saved after decryption).","$ref":"#/components/schemas/TokenizationSettings"}]},"metadata":{"type":["null","object"],"additionalProperties":{"type":"string"},"description":"Additional metadata."}},"description":"Represents an Apple Pay encrypted payment token."},"ClickToPayTokenDto":{"type":"object","properties":{"token":{"type":"string","description":"Encrypted payload from Mastercard Click to Pay checkout."},"cardholder":{"oneOf":[{"type":"null"},{"description":"Cardholder information (optional, provided by Mastercard).","$ref":"#/components/schemas/CardHolderDto"}]},"tokenizationSettings":{"oneOf":[{"type":"null"},{"description":"Tokenization settings — Phase 5 supports temporal only.","$ref":"#/components/schemas/TokenizationSettings"}]},"metadata":{"type":["null","object"],"additionalProperties":{"type":"string"},"description":"Non-sensitive metadata (sanitized before storage)."}},"description":"Represents a Mastercard Click to Pay encrypted payment token."}}}} ``` ### CardRequestDto ## The CardRequestDto object ```json {"openapi":"3.1.1","info":{"title":"Core.API","version":"v2"},"components":{"schemas":{"CardRequestDto":{"type":"object","properties":{"number":{"type":"string","description":"The card number (PAN - Primary Account Number)."},"expMonth":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"description":"The card expiration month (1-12).","format":"int32"},"expYear":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"description":"The card expiration year (4-digit format).","format":"int32"},"cvc":{"type":["null","string"],"description":"The card security code (CVV/CVC)."},"cardholder":{"oneOf":[{"type":"null"},{"description":"The cardholder information (name, address, etc.).","$ref":"#/components/schemas/CardHolderDto"}]},"tokenizationSettings":{"oneOf":[{"type":"null"},{"description":"Tokenization settings controlling if/how card should be saved.","$ref":"#/components/schemas/TokenizationSettings"}]},"metadata":{"type":["null","object"],"additionalProperties":{"type":"string"},"description":"Additional card metadata (3DS data, etc.)."}},"description":"Represents direct card details for a payment."},"CardHolderDto":{"type":"object","properties":{"firstName":{"type":["null","string"],"description":"The first name of the cardholder."},"lastName":{"type":["null","string"],"description":"The last name of the cardholder."},"email":{"type":["null","string"],"description":"The email address of the cardholder."},"birthdate":{"type":["null","string"],"description":"The birthdate of the cardholder.","format":"date-time"},"identification":{"oneOf":[{"type":"null"},{"description":"The identification details of the cardholder.","$ref":"#/components/schemas/DocumentDto"}]},"billingAddress":{"oneOf":[{"type":"null"},{"description":"The billing address of the cardholder.","$ref":"#/components/schemas/AddressDto"}]},"phoneNumber":{"type":["null","string"],"description":"The phone number of the cardholder."}},"description":"Represents the details of a cardholder."},"DocumentDto":{"type":"object","properties":{"type":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["null","integer","string"],"description":"Type of the identification document.","format":"int32"},"value":{"type":["null","string"],"description":"Document number or identifier value."}},"description":"Represents an identification or legal document for a customer."},"AddressDto":{"type":"object","properties":{"city":{"type":["null","string"],"description":"City or locality name."},"country":{"type":["null","string"],"description":"Two-letter ISO country code (ISO 3166-1 alpha-2)."},"line1":{"type":"string","description":"Primary address line (street address, P.O. box, company name, etc.)."},"line2":{"type":["null","string"],"description":"Secondary address line (apartment, suite, unit, building, floor, etc.)."},"postalCode":{"type":["null","string"],"description":"ZIP or postal code."},"state":{"type":["null","string"],"description":"State, province, prefecture, or region."}},"description":"Represents a physical address for billing or shipping purposes."},"TokenizationSettings":{"type":"object","properties":{"type":{"type":"string","description":"The type of tokenization. Possible values: \"temporal\", \"store\"."},"expiration":{"type":["null","string"],"description":"The expiration date and time of the tokenization.","format":"date-time"}},"description":"Represents the tokenization settings of a card."}}}} ``` ### PaymentDto ## The PaymentDto object ```json {"openapi":"3.1.1","info":{"title":"Core.API","version":"v2"},"components":{"schemas":{"PaymentDto":{"type":"object","properties":{"id":{"type":["null","string"],"description":"The unique identifier of the payment."},"sessionId":{"type":["null","string"],"description":"The session identifier associated with the payment.","format":"uuid"},"referenceId":{"type":"string","description":"The reference identifier for the payment."},"invoiceNumber":{"type":["null","string"],"description":"The invoice number associated with the payment."},"status":{"type":["null","string"],"description":"The status of the payment. Possible values: \"created\", \"pending\", \"approved\", \"authorized\", \"denied\", \"cancelled\", \"refunded\", \"partially-refunded\", \"expired\", \"failed\"."},"flow":{"type":["null","string"],"description":"The flow of the payment. Possible values: \"redirect\", \"direct\", \"pos\"."},"statementDescriptor":{"type":["null","string"],"description":"Extra information about a payout to be displayed on the user’s bank statement."},"processingMethod":{"type":["null","string"],"description":"The processing method of the payment. Possible values: \"checkout\", \"api\", \"api-webservices\", \"verify-funds\"."},"browserDetails":{"oneOf":[{"type":"null"},{"description":"The browser details associated with the payment.","$ref":"#/components/schemas/BrowserDetailsDto"}]},"createdAt":{"type":["null","string"],"description":"The date and time when the payment was created.","format":"date-time"},"updatedAt":{"type":["null","string"],"description":"The date and time when the payment was last updated.","format":"date-time"},"processedAt":{"type":["null","string"],"description":"The date and time when the payment was processed.","format":"date-time"},"expiresAt":{"type":["null","string"],"description":"The date and time when the payment expires.","format":"date-time"},"customer":{"oneOf":[{"type":"null"},{"description":"The customer details associated with the payment.","$ref":"#/components/schemas/CustomerDto"}]},"merchant":{"description":"The merchant details associated with the payment.","$ref":"#/components/schemas/PaymentMerchantDto"},"client":{"description":"The client details associated with the payment.","$ref":"#/components/schemas/PaymentClientDto"},"paymentMethod":{"description":"The payment method details associated with the payment.","$ref":"#/components/schemas/TransactionPaymentMethodDto"},"paymentFacilitator":{"oneOf":[{"type":"null"},{"description":"The payment facilitator details associated with the payment.","$ref":"#/components/schemas/PaymentFacilitatorMerchantDto"}]},"installments":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"description":"The number of installments for the payment.","format":"int32"},"amount":{"description":"The amount details associated with the payment.","$ref":"#/components/schemas/PaymentAmountDto"},"items":{"type":["null","array"],"items":{"$ref":"#/components/schemas/PaymentRequestItem"},"description":"The items associated with the payment request."},"capture":{"oneOf":[{"type":"null"},{"description":"The capture details associated with the payment.","$ref":"#/components/schemas/PaymentCaptureDto"}]},"code":{"oneOf":[{"type":"null"},{"description":"The code details associated with the payment.","$ref":"#/components/schemas/PaymentCodeDto"}]},"redirectUrl":{"type":["null","string"],"description":"The URL to which the user is redirected after payment."},"callbackUrl":{"type":["null","string"],"description":"The callback URL for payment notifications."},"optionalMetadata":{"type":["null","string"],"description":"Optional metadata associated with the payment."},"metadata":{"type":["null","object"],"additionalProperties":{"type":"string"},"description":"Additional metadata associated with the payment."},"recurring":{"oneOf":[{"type":"null"},{"description":"The recurring payment details.","$ref":"#/components/schemas/RecurringDto"}]},"threeDS":{"oneOf":[{"type":"null"},{"description":"The 3D Secure details associated with the payment.","$ref":"#/components/schemas/TransactionThreeDSDto"}]},"fraudManagement":{"oneOf":[{"type":"null"},{"description":"The fraud management details associated with the payment.","$ref":"#/components/schemas/TransactionFraudManagementDto"}]},"transactions":{"type":["null","array"],"items":{"$ref":"#/components/schemas/PaymentTransactionDto"},"description":"The transactions associated with the payment."},"actions":{"type":["null","array"],"items":{"$ref":"#/components/schemas/PaymentActions"},"description":"The actions associated with the payment (e.g., 3DS Redirect actions)."},"timeoutCancellation":{"oneOf":[{"type":"null"},{"description":"Timeout cancellation tracking information for this payment.","$ref":"#/components/schemas/TimeoutCancellationDto"}]}},"description":"Payment returned by the Payments API."},"BrowserDetailsDto":{"type":"object","properties":{"ipAddress":{"type":["null","string"],"description":"Public IP address observed for the payer's browser or device."},"deviceFingerprint":{"type":["null","string"],"description":"Merchant-generated device fingerprint or browser identifier, when available."},"userAgent":{"type":["null","string"],"description":"Full browser user-agent string from the payer's device."},"device":{"type":["null","string"],"description":"High-level device type, such as desktop, mobile, or tablet."},"operativeSystem":{"type":["null","string"],"description":"Operating system reported by the payer's device, such as iOS, Android, Windows, or macOS."}},"description":"Represents the details of a browser used in a payment transaction."},"CustomerDto":{"type":"object","properties":{"id":{"type":["null","string"],"description":"Unique identifier for the customer assigned by Plexo."},"referenceId":{"type":["null","string"],"description":"External reference identifier for the customer from your system."},"metadata":{"type":["null","object"],"additionalProperties":{"type":"string"},"description":"Custom key-value pairs for storing additional customer information."},"description":{"type":["null","string"],"description":"Optional description or notes about the customer."},"email":{"type":["null","string"],"description":"Customer's email address."},"name":{"type":["null","string"],"description":"Customer's full name (computed property)."},"phone":{"type":["null","string"],"description":"Customer's phone number with country code."},"firstName":{"type":["null","string"],"description":"Customer's first name or given name."},"lastName":{"type":["null","string"],"description":"Customer's last name or family name."},"document":{"oneOf":[{"type":"null"},{"description":"Primary identification document (e.g., national ID, driver's license).","$ref":"#/components/schemas/DocumentDto"}]},"identification":{"oneOf":[{"type":"null"},{"description":"Secondary identification document or tax identification number.","$ref":"#/components/schemas/DocumentDto"}]},"birthdate":{"type":["null","string"],"description":"Customer's date of birth.","format":"date-time"},"address":{"oneOf":[{"type":"null"},{"description":"Customer's billing or primary address.","$ref":"#/components/schemas/AddressDto"}]},"shipping":{"oneOf":[{"type":"null"},{"description":"Customer's shipping address and contact information.","$ref":"#/components/schemas/ShippingDto"}]},"status":{"type":["null","string"],"description":"Current status of the customer account."}},"description":"Customer profile used in customer, payment, and session responses."},"DocumentDto":{"type":"object","properties":{"type":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["null","integer","string"],"description":"Type of the identification document.","format":"int32"},"value":{"type":["null","string"],"description":"Document number or identifier value."}},"description":"Represents an identification or legal document for a customer."},"AddressDto":{"type":"object","properties":{"city":{"type":["null","string"],"description":"City or locality name."},"country":{"type":["null","string"],"description":"Two-letter ISO country code (ISO 3166-1 alpha-2)."},"line1":{"type":"string","description":"Primary address line (street address, P.O. box, company name, etc.)."},"line2":{"type":["null","string"],"description":"Secondary address line (apartment, suite, unit, building, floor, etc.)."},"postalCode":{"type":["null","string"],"description":"ZIP or postal code."},"state":{"type":["null","string"],"description":"State, province, prefecture, or region."}},"description":"Represents a physical address for billing or shipping purposes."},"ShippingDto":{"type":"object","properties":{"address":{"description":"Physical delivery address for shipping.","$ref":"#/components/schemas/AddressDto"},"name":{"type":"string","description":"Name of the person receiving the shipment."},"phone":{"type":"string","description":"Contact phone number for delivery coordination."}},"description":"Shipping information for delivering physical goods to a customer."},"PaymentMerchantDto":{"type":"object","properties":{"id":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"description":"The unique identifier of the merchant.","format":"int32"},"name":{"type":"string","description":"The name of the merchant."},"settings":{"oneOf":[{"type":"null"},{"description":"The settings associated with the merchant.","$ref":"#/components/schemas/MerchantSettingsDto"}]},"clientId":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["null","integer","string"],"description":"The unique identifier of the client associated with the merchant.","format":"int32"}},"description":"Represents the merchant details for a payment."},"MerchantSettingsDto":{"type":"object","properties":{"merchantIdentificationNumber":{"type":["null","string"],"description":"Gets or sets the merchant identification number assigned by the payment processor/acquirer."},"terminalNumber":{"type":["null","string"],"description":"Gets or sets the terminal identification number for point-of-sale transactions."},"statementDescriptor":{"type":["null","string"],"description":"Gets or sets the text that appears on customer's card statements."},"rut":{"type":["null","string"],"description":"Gets or sets the merchant's tax identification number (RUT in Uruguay)."},"merchantCategoryCode":{"type":["null","string"],"description":"Gets or sets the Merchant Category Code (MCC) that classifies the merchant's business type."},"banks":{"type":["null","array"],"items":{"type":"string"},"description":"Gets or sets the list of bank codes supported for bank transfers or debit transactions."},"crossBankTransfers":{"type":["null","boolean"],"description":"Gets or sets whether cross-bank transfers are enabled for this merchant."},"checkoutInstallments":{"type":["null","array"],"items":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"format":"int32"},"description":"Gets or sets the available installment plans for checkout payments."},"metadata":{"type":["null","object"],"additionalProperties":{"type":"string"},"description":"Gets or sets custom metadata as key-value pairs for integration-specific configuration."},"paymentProcessor":{"oneOf":[{"type":"null"},{"description":"Gets or sets the payment processor/acquirer configuration for this payment method.","$ref":"#/components/schemas/PaymentProcessorDto"}]},"paymentFacilitator":{"oneOf":[{"type":"null"},{"description":"Gets or sets the payment facilitator (PayFac) configuration for sub-merchant management.","$ref":"#/components/schemas/PaymentFacilitatorMerchantDto"}]},"fraudManagement":{"oneOf":[{"type":"null"},{"description":"Gets or sets the fraud management system configuration.","$ref":"#/components/schemas/FraudManagementSettingsDto"}]},"threeDS":{"oneOf":[{"type":"null"},{"description":"Gets or sets the 3D Secure (3DS) authentication configuration.","$ref":"#/components/schemas/ThreeDSSettingsDto"}]}},"description":"Contains configuration settings for a merchant's payment processing capabilities."},"PaymentProcessorDto":{"type":"object","properties":{"id":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["null","integer","string"],"description":"Gets or sets the unique numeric identifier for this processor configuration.","format":"int32"},"acquirer":{"type":"string","description":"Gets or sets the payment processor/acquirer identifier."},"settings":{"oneOf":[{"type":"null"},{"description":"Gets or sets processor-specific configuration settings and credentials.","$ref":"#/components/schemas/PaymentProcessorSettingsDto"}]},"default":{"type":["null","boolean"],"description":"Gets or sets whether this is the default processor for the payment method."}},"description":"Represents a payment processor/acquirer configuration for routing transactions."},"PaymentProcessorSettingsDto":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/PaymentProcessorFieldDto"},"description":"Gets or sets the merchant configuration fields required by the payment processor."},"fingerprint":{"oneOf":[{"type":"null"},{"description":"Gets or sets device fingerprinting configuration for fraud detection.","$ref":"#/components/schemas/FingerprintSettingsDto"}]},"cardholderFields":{"type":["null","array"],"items":{"$ref":"#/components/schemas/CardholderFieldDto"},"description":"Gets or sets the cardholder information fields required by the payment processor."},"currencies":{"type":["null","array"],"items":{"$ref":"#/components/schemas/CurrencyDto"},"description":"Gets or sets the currencies supported by this payment processor."},"isoConnection":{"type":["null","boolean"],"description":"Gets or sets whether this processor uses ISO 8583 protocol for transaction communication."},"externalToken":{"type":["null","boolean"],"description":"Gets or sets whether the processor provides its own tokenization service."}},"description":"Contains configuration requirements and capabilities for a payment processor/acquirer."},"PaymentProcessorFieldDto":{"type":"object","properties":{"id":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"format":"int32"},"label":{"type":"string"},"name":{"type":"string"},"description":{"type":["null","string"]},"required":{"type":"boolean"}}},"FingerprintSettingsDto":{"type":"object","properties":{"name":{"type":"string"}}},"CardholderFieldDto":{"type":"object","properties":{"id":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"description":"Gets or sets the unique numeric identifier for this field.","format":"int32"},"label":{"type":"string","description":"Gets or sets the display label for this field in user interfaces."},"name":{"type":"string","description":"Gets or sets the field name/identifier used in API requests."},"description":{"type":["null","string"],"description":"Gets or sets an optional description providing guidance for completing this field."},"required":{"type":"boolean","description":"Gets or sets whether this field is mandatory for payment processing."}},"description":"Represents a required or optional field for cardholder information in payment forms."},"CurrencyDto":{"type":"object","properties":{"id":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"format":"int32"},"isoCode":{"type":"string"},"name":{"type":"string"},"plural":{"type":"string"},"symbol":{"type":"string"}}},"PaymentFacilitatorMerchantDto":{"type":"object","properties":{"id":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"description":"Gets or sets the unique identifier of the payment facilitator sub-merchant.","format":"int32"},"name":{"type":["null","string"],"description":"Gets or sets the name of the payment facilitator sub-merchant."},"merchantId":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"description":"Gets or sets the unique identifier of the parent merchant account.","format":"int32"}},"description":"Represents a sub-merchant operating under a Payment Facilitator (PayFac) model."},"FraudManagementSettingsDto":{"type":"object","properties":{"provider":{"type":"string","description":"Gets or sets the fraud management provider/service."},"enabled":{"type":"boolean","description":"Gets or sets whether fraud management screening is enabled for this payment method."}},"description":"Configuration settings for fraud detection and prevention services."},"ThreeDSSettingsDto":{"type":"object","properties":{"provider":{"type":"string","description":"Gets or sets the 3D Secure provider/service used for authentication."},"enabled":{"type":"boolean","description":"Gets or sets whether 3D Secure authentication is enabled for this payment method."},"rules":{"oneOf":[{"type":"null"},{"description":"Gets or sets the rule-based configuration for when 3DS authentication is required.","$ref":"#/components/schemas/ThreedsRulesDto"}]},"metadata":{"type":["null","object"],"additionalProperties":{"type":"string"},"description":"Gets or sets custom metadata for provider-specific 3DS configuration."}},"description":"Configuration settings for 3D Secure (3DS) authentication."},"ThreedsRulesDto":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Gets or sets whether rule-based 3DS triggering is enabled."},"tier":{"type":"string","description":"Gets or sets the 3DS tier/level that determines authentication requirements."}},"description":"Rule-based configuration for 3D Secure authentication triggering."},"PaymentClientDto":{"type":"object","properties":{"id":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"description":"The unique identifier of the payment client.","format":"int32"},"name":{"type":"string","description":"The name of the payment client."},"owner":{"type":"string","description":"The owner of the payment client."}},"description":"Represents the payment details of a client."},"TransactionPaymentMethodDto":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier of the payment method."},"legacyId":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"description":"The legacy identifier of the payment method.","format":"int32"},"name":{"type":"string","description":"The name of the payment method."},"type":{"type":"string","description":"The type of the payment method. Possible values: \"bank-transfer\", \"buynow-paylater\", \"card\", \"cash\"."},"source":{"type":["null","string"],"description":"The source of the payment method. Possible values: \"token\", \"card\", \"network-token\", \"google-pay-token\", \"apple-pay-token\", \"click-to-pay-token\"."},"originalSource":{"type":["null","string"],"description":"The original source of the payment method, preserving wallet provenance when a stored token is used.\nFor direct wallet payments this matches Source. For stored-token payments originally created from a wallet,\nthis field retains the wallet origin.\nPossible values: \"google-pay-token\", \"apple-pay-token\", \"click-to-pay-token\", or null for non-wallet sources."},"card":{"oneOf":[{"type":"null"},{"description":"The card details associated with the payment method.","$ref":"#/components/schemas/CardDto"}]},"processor":{"oneOf":[{"type":"null"},{"description":"The payment processor details associated with the payment method.","$ref":"#/components/schemas/TransactionPaymentProcessorDto"}]}},"description":"Represents the details of a transaction payment method."},"CardDto":{"type":"object","properties":{"name":{"type":"string","description":"Masked card number, BIN (Bank Identification Number), and last 4 digits."},"bin":{"type":["null","string"],"description":"The BIN (Bank Identification Number) of the card."},"last4":{"type":["null","string"],"description":"The last 4 digits of the card."},"expMonth":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"description":"The expiration month of the card.","format":"int32"},"expYear":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"description":"The expiration year of the card.","format":"int32"},"cardholder":{"description":"The cardholder details.","$ref":"#/components/schemas/CardHolderDto"},"type":{"type":["null","string"],"description":"The type of the card. Possible values: \"credit\", \"debit\", \"prepaid\"."},"origin":{"type":["null","string"],"description":"The origin of the card. Possible values: \"uruguay\", \"international\"."},"token":{"type":["null","string"],"description":"The token of the card."},"uniqueIdAlias":{"type":["null","string"],"description":"The unique identifier of the card."},"issuer":{"oneOf":[{"type":"null"},{"description":"The issuer details of the card.","$ref":"#/components/schemas/CardIssuer"}]},"tokenization":{"oneOf":[{"type":"null"},{"description":"The tokenization settings of the card.","$ref":"#/components/schemas/TokenizationSettings"}]}},"description":"Represents the details of a card."},"CardHolderDto":{"type":"object","properties":{"firstName":{"type":["null","string"],"description":"The first name of the cardholder."},"lastName":{"type":["null","string"],"description":"The last name of the cardholder."},"email":{"type":["null","string"],"description":"The email address of the cardholder."},"birthdate":{"type":["null","string"],"description":"The birthdate of the cardholder.","format":"date-time"},"identification":{"oneOf":[{"type":"null"},{"description":"The identification details of the cardholder.","$ref":"#/components/schemas/DocumentDto"}]},"billingAddress":{"oneOf":[{"type":"null"},{"description":"The billing address of the cardholder.","$ref":"#/components/schemas/AddressDto"}]},"phoneNumber":{"type":["null","string"],"description":"The phone number of the cardholder."}},"description":"Represents the details of a cardholder."},"CardIssuer":{"type":"object","properties":{"id":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"description":"Gets or sets the unique identifier for the card issuer.","format":"int32"},"name":{"type":["null","string"],"description":"Gets or sets the full name of the issuing bank."},"shortName":{"type":["null","string"],"description":"Gets or sets the abbreviated name or common name of the issuing bank."},"pictureUrl":{"type":["null","string"],"description":"Gets or sets the URL to the issuer's logo image."},"externalId":{"type":["null","string"],"description":"Gets or sets the external identifier used by payment processors or card networks."},"country":{"type":["null","string"],"description":"Gets or sets the issuer country name derived from BIN locality data."},"countryCode":{"type":["null","string"],"description":"Gets or sets the ISO 3166-1 alpha-2 country code of the issuer."}},"description":"Represents a bank or financial institution that issues payment cards."},"TokenizationSettings":{"type":"object","properties":{"type":{"type":"string","description":"The type of tokenization. Possible values: \"temporal\", \"store\"."},"expiration":{"type":["null","string"],"description":"The expiration date and time of the tokenization.","format":"date-time"}},"description":"Represents the tokenization settings of a card."},"TransactionPaymentProcessorDto":{"type":"object","properties":{"id":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["null","integer","string"],"format":"int32"},"acquirer":{"type":"string"}}},"PaymentAmountDto":{"required":["currency"],"type":"object","properties":{"currency":{"maxLength":3,"minLength":0,"type":"string","description":"The currency of the payment amount.\nThe value should be an ISO Alpha code, such as UYU or USD."},"total":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["number","string"],"description":"The total amount of the payment.","format":"double"},"details":{"oneOf":[{"type":"null"},{"description":"The detailed breakdown of the payment amount.","$ref":"#/components/schemas/PaymentAmountDetailsDto"}]}},"description":"Represents the amount details of a payment."},"PaymentAmountDetailsDto":{"type":"object","properties":{"tax":{"oneOf":[{"type":"null"},{"description":"The tax amount details.","$ref":"#/components/schemas/TaxAmountDto"}]},"taxedAmount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["number","string"],"description":"The taxable amount.","format":"double"},"tipAmount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["null","number","string"],"description":"The tip amount.","format":"double"},"discountAmount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["null","number","string"],"description":"The discount amount.","format":"double"},"shippingAmount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["null","number","string"],"description":"The shipping amount.","format":"double"},"loyaltyProgram":{"oneOf":[{"type":"null"},{"description":"The loyalty program details.","$ref":"#/components/schemas/LoyaltyProgramDto"}]}},"description":"Represents the detailed breakdown of the payment amount."},"TaxAmountDto":{"type":"object","properties":{"type":{"type":["null","string"],"description":"The type of tax. Possible values: \"19210\", \"17934\", \"none\"."},"amount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["number","string"],"description":"The amount of tax.","format":"double"},"rate":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["null","number","string"],"description":"The rate of tax. As decimal value.","format":"double"}},"description":"Represents the tax amount details."},"LoyaltyProgramDto":{"type":"object","properties":{"amount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["null","number","string"],"format":"double"},"provider":{"type":["null","string"]}}},"PaymentRequestItem":{"type":"object","properties":{"referenceId":{"type":"string","description":"The reference identifier of the item (e.g., SKU or Id)."},"name":{"type":"string","description":"The name of the item."},"description":{"type":["null","string"],"description":"The description of the item."},"quantity":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"description":"The quantity of the item.","format":"int32"},"price":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["number","string"],"description":"The price per unit of the item.","format":"double"},"discount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["null","number","string"],"description":"The discount applied to the item.","format":"double"},"metadata":{"type":["null","object"],"additionalProperties":{"type":"string"},"description":"The metadata associated with the item."},"tax":{"oneOf":[{"type":"null"},{"description":"The tax amount details for the item.","$ref":"#/components/schemas/TaxAmountDto"}]}},"description":"Represents an item in a payment request."},"PaymentCaptureDto":{"type":"object","properties":{"method":{"type":"string","description":"Controls when the funds will be captured from the customer’s account.\nPossible values: \"automatic\", \"manual\"."},"delay":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["null","integer","string"],"description":"Optional, custom automatic capture delay in seconds.","format":"int32"}},"description":"Represents the details for capturing a payment."},"PaymentCodeDto":{"type":"object","properties":{"base64Image":{"type":["null","string"],"description":"Base64-encoded PNG image of the payment code."},"url":{"type":["null","string"],"description":"Optional URL where the payment code can be accessed or where it redirects after scanning."},"type":{"type":"string","description":"The type of payment code generated."},"value":{"type":"string","description":"The raw payment reference or encoded data contained within the code."},"expiration":{"type":["null","string"],"description":"The expiration timestamp of the payment code, if applicable.","format":"date-time"}},"description":"Represents a generated payment code (barcode or QR code) with encoded payment information."},"RecurringDto":{"type":"object","properties":{"parentId":{"type":["null","string"],"description":"The unique identifier of the parent payment."},"action":{"type":"string","description":"The action to be performed. Possible values: \"setup\" or \"execute\"."},"indicator":{"type":["null","string"],"description":"The indicator for the recurring payment."}},"description":"Represents the details for a recurring payment."},"TransactionThreeDSDto":{"type":"object","properties":{"status":{"type":["null","string"]},"threeDSSessionId":{"type":["null","string"]},"eci":{"type":["null","string"]},"threeDSVersion":{"type":["null","string"]},"liabilityShifted":{"type":"boolean"}}},"TransactionFraudManagementDto":{"type":"object","properties":{"status":{"type":["null","string"]},"score":{"type":["null","string"]},"statusMessage":{"type":["null","string"]},"provider":{"type":["null","string"]}}},"PaymentTransactionDto":{"type":"object","properties":{"id":{"type":["null","string"],"description":"The unique identifier of the transaction."},"compatId":{"type":["null","string"],"description":"The compatibility identifier of the transaction."},"parentId":{"type":["null","string"],"description":"The unique identifier of the parent transaction."},"traceId":{"type":["null","string"],"description":"The trace identifier of the transaction."},"batchId":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["null","integer","string"],"description":"The batch identifier of the transaction.","format":"int64"},"referenceId":{"type":"string","description":"The reference identifier of the transaction."},"type":{"type":"string","description":"The type of the transaction. Possible values: \"purchase\", \"authorization\", \"refund\", \"partial-refund\", \"cancellation\", \"capture\"."},"status":{"type":["null","string"],"description":"The status of the transaction. Possible values: \"created\", \"pending\", \"approved\", \"denied\", \"expired\", \"failed\"."},"createdAt":{"type":["null","string"],"description":"The date and time when the transaction was created.","format":"date-time"},"processedAt":{"type":["null","string"],"description":"The date and time when the transaction was processed.","format":"date-time"},"expiresAt":{"type":["null","string"],"description":"The date and time when the transaction expires.","format":"date-time"},"resultCode":{"type":["null","string"],"description":"The result code of the transaction."},"resultMessage":{"type":["null","string"],"description":"The result message of the transaction."},"authorization":{"type":["null","string"],"description":"The authorization code of the transaction."},"ticket":{"type":["null","string"],"description":"The ticket number of the transaction."},"metadata":{"type":["null","object"],"additionalProperties":{"type":"string"},"description":"The metadata associated with the transaction."},"amount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["null","number","string"],"description":"The amount of the transaction.","format":"double"},"tipAmount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["null","number","string"],"description":"The tip amount of the transaction.","format":"double"},"taxedAmount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["null","number","string"],"description":"The taxed amount of the transaction.","format":"double"},"currency":{"type":["null","string"],"description":"The currency of the transaction."},"description":{"type":["null","string"],"description":"The description of the transaction."},"reason":{"type":["null","string"],"description":"The reason for the transaction."},"extendedData":{"type":["null","string"],"description":"The extended data of the transaction."},"code":{"oneOf":[{"type":"null"},{"description":"The payment code details of the transaction.","$ref":"#/components/schemas/PaymentCodeDto"}]},"taxReturn":{"oneOf":[{"type":"null"},{"description":"The tax return details of the transaction.","$ref":"#/components/schemas/TransactionTaxReturnDto"}]},"threeDS":{"oneOf":[{"type":"null"},{"description":"The 3D Secure details of the transaction.","$ref":"#/components/schemas/TransactionThreeDSDto"}]},"fraudManagement":{"oneOf":[{"type":"null"},{"description":"The fraud management details of the transaction.","$ref":"#/components/schemas/TransactionFraudManagementDto"}]}},"description":"Represents the details of a transaction."},"TransactionTaxReturnDto":{"type":"object","properties":{"amount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["number","string"],"description":"The amount of the tax return.","format":"double"},"law":{"type":"string","description":"The law under which the tax return is processed."}},"description":"Represents the tax return details of a transaction."},"PaymentActions":{"type":"object","properties":{"rel":{"type":"string","description":"Relation or mode label for the action."},"href":{"type":"string","description":"URL to call or present to the payer."},"method":{"type":"string","description":"HTTP verb or hosted-session mode indicator."}},"description":"Action metadata returned with payments and hosted session responses."},"TimeoutCancellationDto":{"type":"object","properties":{"attempted":{"type":"boolean","description":"Indicates whether any cancellation attempt was made."},"attemptCount":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"description":"The total number of cancellation attempts made.","format":"int32"},"status":{"type":["null","string"],"description":"The current/final status of the timeout cancellation process.\nPossible values: \"pending\", \"completed\", \"failed\"."},"lastAttemptAt":{"type":["null","string"],"description":"The date and time of the last cancellation attempt.","format":"date-time"},"attempts":{"type":"array","items":{"$ref":"#/components/schemas/TimeoutCancellationAttemptDto"},"description":"The history of all cancellation attempts."}},"description":"Represents timeout cancellation tracking information for a payment.\nContains a history of all cancellation attempts."},"TimeoutCancellationAttemptDto":{"type":"object","properties":{"attemptNumber":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"description":"The attempt number (1-based).","format":"int32"},"attemptedAt":{"type":"string","description":"The date and time when this attempt was made.","format":"date-time"},"status":{"type":["null","string"],"description":"The status of this attempt.\nPossible values: \"pending\", \"completed\", \"failed\"."},"resultCode":{"type":["null","string"],"description":"The result code from the processor (if available)."},"resultMessage":{"type":["null","string"],"description":"The result message from the processor (if available)."}},"description":"Represents a single timeout cancellation attempt for a payment."}}}} ``` ### PaymentCaptureDto ## The PaymentCaptureDto object ```json {"openapi":"3.1.1","info":{"title":"Core.API","version":"v2"},"components":{"schemas":{"PaymentCaptureDto":{"type":"object","properties":{"method":{"type":"string","description":"Controls when the funds will be captured from the customer’s account.\nPossible values: \"automatic\", \"manual\"."},"delay":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["null","integer","string"],"description":"Optional, custom automatic capture delay in seconds.","format":"int32"}},"description":"Represents the details for capturing a payment."}}}} ``` ### PaymentActions ## The PaymentActions object ```json {"openapi":"3.1.1","info":{"title":"Core.API","version":"v2"},"components":{"schemas":{"PaymentActions":{"type":"object","properties":{"rel":{"type":"string","description":"Relation or mode label for the action."},"href":{"type":"string","description":"URL to call or present to the payer."},"method":{"type":"string","description":"HTTP verb or hosted-session mode indicator."}},"description":"Action metadata returned with payments and hosted session responses."}}}} ``` ### ErrorResponse ## The ErrorResponse object ```json {"openapi":"3.1.1","info":{"title":"Core.API","version":"v2"},"components":{"schemas":{"ErrorResponse":{"type":"object","properties":{"type":{"type":["null","string"]},"title":{"type":["null","string"]},"status":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["null","integer","string"],"format":"int32"},"detail":{"type":["null","string"]},"instance":{"type":["null","string"]},"code":{"type":"string","description":"Gets the error code identifier in kebab-case format."},"declineCode":{"type":["null","string"],"description":"Gets the ISO 8583 decline code when a payment is declined by the acquirer."},"message":{"type":["null","string"],"description":"Gets the human-readable error message with troubleshooting guidance."},"traceId":{"type":["null","string"],"description":"Gets the correlation/trace ID for request tracking and debugging."},"params":{"type":["null","object"],"additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Gets field-level validation errors with details for each invalid parameter."}},"description":"Standard error payload returned when a request cannot be completed."}}}} ``` ## Sessions ### SessionRequest ## The SessionRequest object ```json {"openapi":"3.1.1","info":{"title":"Core.API","version":"v2"},"components":{"schemas":{"SessionRequest":{"type":"object","properties":{"merchantId":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"description":"The merchant ID for this session.","format":"int32"},"referenceId":{"type":"string","description":"Your unique reference ID for this session."},"type":{"type":"string","description":"Session type: \"checkout\" or \"tokenization\"."},"token":{"type":["null","string"],"description":"Existing payment instrument token to use (optional)."},"settings":{"oneOf":[{"type":"null"},{"description":"Session configuration including UI, callbacks, and behavior settings.","$ref":"#/components/schemas/SessionSettings"}]},"customerId":{"type":["null","string"],"description":"The customer ID to associate with this session (optional)."},"paymentRequest":{"oneOf":[{"type":"null"},{"description":"Payment details (required for checkout sessions).","$ref":"#/components/schemas/CheckoutPaymentRequest"}]},"browserDetails":{"oneOf":[{"type":"null"},{"description":"Browser and device information for fraud detection (optional).","$ref":"#/components/schemas/BrowserDetailsDto"}]}},"description":"Request to create a new checkout or tokenization session."},"SessionSettings":{"type":"object","properties":{"paymentMethodTypes":{"type":["null","array"],"items":{"type":"string"},"description":"Allowed payment method types (e.g., \"card\", \"bank_transfer\")."},"paymentMethods":{"type":["null","array"],"items":{"type":"string"},"description":"Allowed payment methods (card brands: \"VISA\", \"MASTERCARD\", \"OCA\", etc.)."},"tokenization":{"oneOf":[{"type":"null"},{"description":"Tokenization-specific settings (required for tokenization sessions).","$ref":"#/components/schemas/TokenizationSettingsRequest"}]},"checkout":{"oneOf":[{"type":"null"},{"description":"Checkout-specific settings (optional for checkout sessions).","$ref":"#/components/schemas/CheckoutSettingsRequest"}]},"callbacks":{"oneOf":[{"type":"null"},{"description":"Callback URLs for session events (optional).","$ref":"#/components/schemas/Callbacks"}]},"redirects":{"oneOf":[{"type":"null"},{"description":"Redirect behavior configuration (optional).","$ref":"#/components/schemas/RedirectSettings"}]},"ui":{"oneOf":[{"type":"null"},{"description":"UI customization settings (optional).","$ref":"#/components/schemas/SessionUISettings"}]}},"description":"Configuration settings for a session."},"TokenizationSettingsRequest":{"type":"object","properties":{"type":{"type":"string","description":"Token storage type: \"store\" or \"temporal\"."},"allowedCardTypes":{"type":["null","array"],"items":{"type":"string"},"description":"Allowed card types for tokenization (optional)."},"features":{"type":["null","array"],"description":"Enabled tokenization features (optional)."},"fields":{"oneOf":[{"type":"null"},{"description":"Field visibility and validation settings (optional).","$ref":"#/components/schemas/TokenizationSettingsFields"}]},"verifyFunds":{"oneOf":[{"type":"null"},{"description":"Fund verification settings for zero-amount authorization (optional).","$ref":"#/components/schemas/VerifyFundsDto"}]},"cardHolder":{"oneOf":[{"type":"null"},{"description":"Pre-filled cardholder information (optional).","$ref":"#/components/schemas/CardHolderDto"}]}},"description":"Settings for tokenization sessions."},"TokenizationSettingsFields":{"type":"object","properties":{"cardholder":{"description":"Cardholder name field settings.","$ref":"#/components/schemas/TokenizationSettingsFieldValues"},"identification":{"description":"Identification document field settings.","$ref":"#/components/schemas/TokenizationSettingsFieldValues"},"billingAddress":{"description":"Billing address field settings.","$ref":"#/components/schemas/TokenizationSettingsFieldValues"}},"description":"Field visibility and behavior settings for tokenization forms."},"TokenizationSettingsFieldValues":{"type":"object","properties":{"visible":{"type":"string","description":"Gets or sets when the field is shown in the hosted tokenization UI."},"readOnly":{"type":"boolean","description":"Gets or sets whether the field is read-only."}},"description":"Represents the visibility state for a tokenization settings field."},"VerifyFundsDto":{"type":"object","properties":{"amount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["number","string"],"description":"Amount to authorize for verification (typically $1.00).","format":"double"},"currency":{"type":"string","description":"Currency code for the verification amount."}},"description":"Settings for card verification via zero-amount or small-amount authorization."},"CardHolderDto":{"type":"object","properties":{"firstName":{"type":["null","string"],"description":"The first name of the cardholder."},"lastName":{"type":["null","string"],"description":"The last name of the cardholder."},"email":{"type":["null","string"],"description":"The email address of the cardholder."},"birthdate":{"type":["null","string"],"description":"The birthdate of the cardholder.","format":"date-time"},"identification":{"oneOf":[{"type":"null"},{"description":"The identification details of the cardholder.","$ref":"#/components/schemas/DocumentDto"}]},"billingAddress":{"oneOf":[{"type":"null"},{"description":"The billing address of the cardholder.","$ref":"#/components/schemas/AddressDto"}]},"phoneNumber":{"type":["null","string"],"description":"The phone number of the cardholder."}},"description":"Represents the details of a cardholder."},"DocumentDto":{"type":"object","properties":{"type":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["null","integer","string"],"description":"Type of the identification document.","format":"int32"},"value":{"type":["null","string"],"description":"Document number or identifier value."}},"description":"Represents an identification or legal document for a customer."},"AddressDto":{"type":"object","properties":{"city":{"type":["null","string"],"description":"City or locality name."},"country":{"type":["null","string"],"description":"Two-letter ISO country code (ISO 3166-1 alpha-2)."},"line1":{"type":"string","description":"Primary address line (street address, P.O. box, company name, etc.)."},"line2":{"type":["null","string"],"description":"Secondary address line (apartment, suite, unit, building, floor, etc.)."},"postalCode":{"type":["null","string"],"description":"ZIP or postal code."},"state":{"type":["null","string"],"description":"State, province, prefecture, or region."}},"description":"Represents a physical address for billing or shipping purposes."},"CheckoutSettingsRequest":{"type":"object","properties":{"installments":{"type":["null","object"],"additionalProperties":{"type":"array","items":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"format":"int32"}},"description":"Installment options per payment method (optional)."},"amountMode":{"description":"Amount mode for the checkout session.","$ref":"#/components/schemas/AmountModeEnum"},"flexibleAmount":{"oneOf":[{"type":"null"},{"description":"Flexible amount constraints for the checkout session (optional).","$ref":"#/components/schemas/FlexibleAmountSettings"}]},"disableThreeds":{"type":"boolean","description":"Disables 3DS for payments created from this checkout session."},"walletIntegrations":{"oneOf":[{"type":"null"},{"description":"Wallet integration availability for the checkout session (optional, server-enriched).","$ref":"#/components/schemas/SessionWalletIntegrationsDto"}]}},"description":"Checkout-specific configuration settings."},"AmountModeEnum":{"description":"Defines the amount mode for checkout sessions."},"FlexibleAmountSettings":{"type":"object","properties":{"allowedCurrencies":{"type":["null","array"],"items":{"type":"string"},"description":"Allowed currencies for flexible amount mode (required)."},"minAmount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["null","number","string"],"description":"Minimum allowed amount (optional).","format":"double"},"maxAmount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["null","number","string"],"description":"Maximum allowed amount (optional).","format":"double"},"suggestedAmount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["null","number","string"],"description":"Suggested amount to display as a hint to the customer (optional).","format":"double"}},"description":"Constraints for flexible amount checkout sessions."},"SessionWalletIntegrationsDto":{"type":"object","properties":{"googlePay":{"oneOf":[{"type":"null"},{"description":"Google Pay availability for this session.","$ref":"#/components/schemas/SessionWalletDto"}]},"applePay":{"oneOf":[{"type":"null"},{"description":"Apple Pay availability for this session.","$ref":"#/components/schemas/SessionWalletDto"}]},"clickToPay":{"oneOf":[{"type":"null"},{"description":"Click to Pay (Mastercard SRC) availability for this session.","$ref":"#/components/schemas/SessionClickToPayDto"}]}},"description":"Wallet integrations availability for a checkout session."},"SessionWalletDto":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether this wallet is enabled for this checkout session."},"mode":{"type":["null","string"],"description":"The integration mode: \"hosted\", \"api\", or \"both\"."},"dynamicShipping":{"type":"boolean","description":"Enables the Dynamic Shipping feature in Google Pay checkout for this session."}},"description":"Represents the availability and mode of a single wallet type in a checkout session."},"SessionClickToPayDto":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether Click to Pay is enabled for this session."},"mode":{"type":["null","string"],"description":"Integration mode: \"hosted\" | \"api\" | \"both\"."},"openApiClientId":{"type":["null","string"],"description":"Open API client identifier for SDK initialization."},"srcClientId":{"type":["null","string"],"description":"Open API client identifier using the Mastercard SDK field name expected by checkout."},"srcDpaId":{"type":["null","string"],"description":"SRC DPA identifier for SDK initialization."},"supportedCardBrands":{"type":["null","array"],"items":{"type":"string"},"description":"Supported card brands for SDK initialization."},"dpaName":{"type":["null","string"],"description":"Registered DPA name required by the Mastercard JavaScript runtime."},"displayName":{"type":["null","string"],"description":"Display name to show in the Click to Pay UI."},"originDomains":{"type":["null","array"],"items":{"type":"string"},"description":"Allowed origin domains for SDK initialization."}},"description":"Click to Pay runtime block included in checkout session responses.\nContains only the fields the frontend SDK needs to initialize Click to Pay."},"Callbacks":{"type":"object","properties":{"paymentCallbackUrl":{"type":["null","string"],"description":"Callback URL for payment events triggered by checkout sessions."},"tokenizationCallbackUrl":{"type":["null","string"],"description":"Callback URL for tokenization events triggered by tokenization sessions."}},"description":"Callback URLs for session events."},"RedirectSettings":{"type":"object","properties":{"defaultUrl":{"type":"string","description":"Default URL to redirect after successful completion."},"cancelUrl":{"type":["null","string"],"description":"URL to redirect when customer cancels (optional)."},"useParamOverride":{"type":["null","boolean"],"description":"Allow redirect URL override via query parameters (optional)."},"redirectOnError":{"type":["null","boolean"],"description":"Redirect to DefaultUrl even on errors (optional)."},"skipResultPage":{"type":["null","boolean"],"description":"Skip the result page and redirect immediately (optional)."}},"description":"Redirect behavior configuration for sessions."},"SessionUISettings":{"type":"object","properties":{"colors":{"type":["null","object"],"additionalProperties":{"type":"string"},"description":"Custom color scheme (optional)."},"theme":{"type":["null","string"],"description":"Theme mode: \"default\" or \"default_dark\" (optional)."},"autoDarkTheme":{"type":["null","boolean"],"description":"Automatically switch theme based on user's browser preferences (optional)."},"logoUrl":{"type":["null","string"],"description":"URL of your logo to display (optional)."},"hideElements":{"type":["null","array"],"items":{"type":"string"},"description":"UI elements to hide (optional)."}},"description":"UI customization settings for the hosted session page."},"CheckoutPaymentRequest":{"type":"object","properties":{"flow":{"type":["null","string"],"description":"Payment flow type (optional)."},"referenceId":{"type":"string","description":"Your unique reference ID for this payment."},"invoiceNumber":{"type":"string","description":"Invoice or order number."},"items":{"type":["null","array"],"items":{"$ref":"#/components/schemas/PaymentRequestItem"},"description":"Line items for this payment (optional)."},"installments":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["null","integer","string"],"description":"Number of installments for this payment (optional).","format":"int32"},"amount":{"oneOf":[{"type":"null"},{"description":"Payment amount details.","$ref":"#/components/schemas/PaymentAmountDto"}]},"statementDescriptor":{"type":["null","string"],"description":"Text to appear on customer's card statement (optional)."},"metadata":{"type":["null","object"],"additionalProperties":{"type":"string"},"description":"Custom metadata key-value pairs (optional)."}},"description":"Payment details for a checkout session."},"PaymentRequestItem":{"type":"object","properties":{"referenceId":{"type":"string","description":"The reference identifier of the item (e.g., SKU or Id)."},"name":{"type":"string","description":"The name of the item."},"description":{"type":["null","string"],"description":"The description of the item."},"quantity":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"description":"The quantity of the item.","format":"int32"},"price":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["number","string"],"description":"The price per unit of the item.","format":"double"},"discount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["null","number","string"],"description":"The discount applied to the item.","format":"double"},"metadata":{"type":["null","object"],"additionalProperties":{"type":"string"},"description":"The metadata associated with the item."},"tax":{"oneOf":[{"type":"null"},{"description":"The tax amount details for the item.","$ref":"#/components/schemas/TaxAmountDto"}]}},"description":"Represents an item in a payment request."},"TaxAmountDto":{"type":"object","properties":{"type":{"type":["null","string"],"description":"The type of tax. Possible values: \"19210\", \"17934\", \"none\"."},"amount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["number","string"],"description":"The amount of tax.","format":"double"},"rate":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["null","number","string"],"description":"The rate of tax. As decimal value.","format":"double"}},"description":"Represents the tax amount details."},"PaymentAmountDto":{"required":["currency"],"type":"object","properties":{"currency":{"maxLength":3,"minLength":0,"type":"string","description":"The currency of the payment amount.\nThe value should be an ISO Alpha code, such as UYU or USD."},"total":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["number","string"],"description":"The total amount of the payment.","format":"double"},"details":{"oneOf":[{"type":"null"},{"description":"The detailed breakdown of the payment amount.","$ref":"#/components/schemas/PaymentAmountDetailsDto"}]}},"description":"Represents the amount details of a payment."},"PaymentAmountDetailsDto":{"type":"object","properties":{"tax":{"oneOf":[{"type":"null"},{"description":"The tax amount details.","$ref":"#/components/schemas/TaxAmountDto"}]},"taxedAmount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["number","string"],"description":"The taxable amount.","format":"double"},"tipAmount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["null","number","string"],"description":"The tip amount.","format":"double"},"discountAmount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["null","number","string"],"description":"The discount amount.","format":"double"},"shippingAmount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["null","number","string"],"description":"The shipping amount.","format":"double"},"loyaltyProgram":{"oneOf":[{"type":"null"},{"description":"The loyalty program details.","$ref":"#/components/schemas/LoyaltyProgramDto"}]}},"description":"Represents the detailed breakdown of the payment amount."},"LoyaltyProgramDto":{"type":"object","properties":{"amount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["null","number","string"],"format":"double"},"provider":{"type":["null","string"]}}},"BrowserDetailsDto":{"type":"object","properties":{"ipAddress":{"type":["null","string"],"description":"Public IP address observed for the payer's browser or device."},"deviceFingerprint":{"type":["null","string"],"description":"Merchant-generated device fingerprint or browser identifier, when available."},"userAgent":{"type":["null","string"],"description":"Full browser user-agent string from the payer's device."},"device":{"type":["null","string"],"description":"High-level device type, such as desktop, mobile, or tablet."},"operativeSystem":{"type":["null","string"],"description":"Operating system reported by the payer's device, such as iOS, Android, Windows, or macOS."}},"description":"Represents the details of a browser used in a payment transaction."}}}} ``` ### SessionSettings ## The SessionSettings object ```json {"openapi":"3.1.1","info":{"title":"Core.API","version":"v2"},"components":{"schemas":{"SessionSettings":{"type":"object","properties":{"paymentMethodTypes":{"type":["null","array"],"items":{"type":"string"},"description":"Allowed payment method types (e.g., \"card\", \"bank_transfer\")."},"paymentMethods":{"type":["null","array"],"items":{"type":"string"},"description":"Allowed payment methods (card brands: \"VISA\", \"MASTERCARD\", \"OCA\", etc.)."},"tokenization":{"oneOf":[{"type":"null"},{"description":"Tokenization-specific settings (required for tokenization sessions).","$ref":"#/components/schemas/TokenizationSettingsRequest"}]},"checkout":{"oneOf":[{"type":"null"},{"description":"Checkout-specific settings (optional for checkout sessions).","$ref":"#/components/schemas/CheckoutSettingsRequest"}]},"callbacks":{"oneOf":[{"type":"null"},{"description":"Callback URLs for session events (optional).","$ref":"#/components/schemas/Callbacks"}]},"redirects":{"oneOf":[{"type":"null"},{"description":"Redirect behavior configuration (optional).","$ref":"#/components/schemas/RedirectSettings"}]},"ui":{"oneOf":[{"type":"null"},{"description":"UI customization settings (optional).","$ref":"#/components/schemas/SessionUISettings"}]}},"description":"Configuration settings for a session."},"TokenizationSettingsRequest":{"type":"object","properties":{"type":{"type":"string","description":"Token storage type: \"store\" or \"temporal\"."},"allowedCardTypes":{"type":["null","array"],"items":{"type":"string"},"description":"Allowed card types for tokenization (optional)."},"features":{"type":["null","array"],"description":"Enabled tokenization features (optional)."},"fields":{"oneOf":[{"type":"null"},{"description":"Field visibility and validation settings (optional).","$ref":"#/components/schemas/TokenizationSettingsFields"}]},"verifyFunds":{"oneOf":[{"type":"null"},{"description":"Fund verification settings for zero-amount authorization (optional).","$ref":"#/components/schemas/VerifyFundsDto"}]},"cardHolder":{"oneOf":[{"type":"null"},{"description":"Pre-filled cardholder information (optional).","$ref":"#/components/schemas/CardHolderDto"}]}},"description":"Settings for tokenization sessions."},"TokenizationSettingsFields":{"type":"object","properties":{"cardholder":{"description":"Cardholder name field settings.","$ref":"#/components/schemas/TokenizationSettingsFieldValues"},"identification":{"description":"Identification document field settings.","$ref":"#/components/schemas/TokenizationSettingsFieldValues"},"billingAddress":{"description":"Billing address field settings.","$ref":"#/components/schemas/TokenizationSettingsFieldValues"}},"description":"Field visibility and behavior settings for tokenization forms."},"TokenizationSettingsFieldValues":{"type":"object","properties":{"visible":{"type":"string","description":"Gets or sets when the field is shown in the hosted tokenization UI."},"readOnly":{"type":"boolean","description":"Gets or sets whether the field is read-only."}},"description":"Represents the visibility state for a tokenization settings field."},"VerifyFundsDto":{"type":"object","properties":{"amount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["number","string"],"description":"Amount to authorize for verification (typically $1.00).","format":"double"},"currency":{"type":"string","description":"Currency code for the verification amount."}},"description":"Settings for card verification via zero-amount or small-amount authorization."},"CardHolderDto":{"type":"object","properties":{"firstName":{"type":["null","string"],"description":"The first name of the cardholder."},"lastName":{"type":["null","string"],"description":"The last name of the cardholder."},"email":{"type":["null","string"],"description":"The email address of the cardholder."},"birthdate":{"type":["null","string"],"description":"The birthdate of the cardholder.","format":"date-time"},"identification":{"oneOf":[{"type":"null"},{"description":"The identification details of the cardholder.","$ref":"#/components/schemas/DocumentDto"}]},"billingAddress":{"oneOf":[{"type":"null"},{"description":"The billing address of the cardholder.","$ref":"#/components/schemas/AddressDto"}]},"phoneNumber":{"type":["null","string"],"description":"The phone number of the cardholder."}},"description":"Represents the details of a cardholder."},"DocumentDto":{"type":"object","properties":{"type":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["null","integer","string"],"description":"Type of the identification document.","format":"int32"},"value":{"type":["null","string"],"description":"Document number or identifier value."}},"description":"Represents an identification or legal document for a customer."},"AddressDto":{"type":"object","properties":{"city":{"type":["null","string"],"description":"City or locality name."},"country":{"type":["null","string"],"description":"Two-letter ISO country code (ISO 3166-1 alpha-2)."},"line1":{"type":"string","description":"Primary address line (street address, P.O. box, company name, etc.)."},"line2":{"type":["null","string"],"description":"Secondary address line (apartment, suite, unit, building, floor, etc.)."},"postalCode":{"type":["null","string"],"description":"ZIP or postal code."},"state":{"type":["null","string"],"description":"State, province, prefecture, or region."}},"description":"Represents a physical address for billing or shipping purposes."},"CheckoutSettingsRequest":{"type":"object","properties":{"installments":{"type":["null","object"],"additionalProperties":{"type":"array","items":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"format":"int32"}},"description":"Installment options per payment method (optional)."},"amountMode":{"description":"Amount mode for the checkout session.","$ref":"#/components/schemas/AmountModeEnum"},"flexibleAmount":{"oneOf":[{"type":"null"},{"description":"Flexible amount constraints for the checkout session (optional).","$ref":"#/components/schemas/FlexibleAmountSettings"}]},"disableThreeds":{"type":"boolean","description":"Disables 3DS for payments created from this checkout session."},"walletIntegrations":{"oneOf":[{"type":"null"},{"description":"Wallet integration availability for the checkout session (optional, server-enriched).","$ref":"#/components/schemas/SessionWalletIntegrationsDto"}]}},"description":"Checkout-specific configuration settings."},"AmountModeEnum":{"description":"Defines the amount mode for checkout sessions."},"FlexibleAmountSettings":{"type":"object","properties":{"allowedCurrencies":{"type":["null","array"],"items":{"type":"string"},"description":"Allowed currencies for flexible amount mode (required)."},"minAmount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["null","number","string"],"description":"Minimum allowed amount (optional).","format":"double"},"maxAmount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["null","number","string"],"description":"Maximum allowed amount (optional).","format":"double"},"suggestedAmount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["null","number","string"],"description":"Suggested amount to display as a hint to the customer (optional).","format":"double"}},"description":"Constraints for flexible amount checkout sessions."},"SessionWalletIntegrationsDto":{"type":"object","properties":{"googlePay":{"oneOf":[{"type":"null"},{"description":"Google Pay availability for this session.","$ref":"#/components/schemas/SessionWalletDto"}]},"applePay":{"oneOf":[{"type":"null"},{"description":"Apple Pay availability for this session.","$ref":"#/components/schemas/SessionWalletDto"}]},"clickToPay":{"oneOf":[{"type":"null"},{"description":"Click to Pay (Mastercard SRC) availability for this session.","$ref":"#/components/schemas/SessionClickToPayDto"}]}},"description":"Wallet integrations availability for a checkout session."},"SessionWalletDto":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether this wallet is enabled for this checkout session."},"mode":{"type":["null","string"],"description":"The integration mode: \"hosted\", \"api\", or \"both\"."},"dynamicShipping":{"type":"boolean","description":"Enables the Dynamic Shipping feature in Google Pay checkout for this session."}},"description":"Represents the availability and mode of a single wallet type in a checkout session."},"SessionClickToPayDto":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether Click to Pay is enabled for this session."},"mode":{"type":["null","string"],"description":"Integration mode: \"hosted\" | \"api\" | \"both\"."},"openApiClientId":{"type":["null","string"],"description":"Open API client identifier for SDK initialization."},"srcClientId":{"type":["null","string"],"description":"Open API client identifier using the Mastercard SDK field name expected by checkout."},"srcDpaId":{"type":["null","string"],"description":"SRC DPA identifier for SDK initialization."},"supportedCardBrands":{"type":["null","array"],"items":{"type":"string"},"description":"Supported card brands for SDK initialization."},"dpaName":{"type":["null","string"],"description":"Registered DPA name required by the Mastercard JavaScript runtime."},"displayName":{"type":["null","string"],"description":"Display name to show in the Click to Pay UI."},"originDomains":{"type":["null","array"],"items":{"type":"string"},"description":"Allowed origin domains for SDK initialization."}},"description":"Click to Pay runtime block included in checkout session responses.\nContains only the fields the frontend SDK needs to initialize Click to Pay."},"Callbacks":{"type":"object","properties":{"paymentCallbackUrl":{"type":["null","string"],"description":"Callback URL for payment events triggered by checkout sessions."},"tokenizationCallbackUrl":{"type":["null","string"],"description":"Callback URL for tokenization events triggered by tokenization sessions."}},"description":"Callback URLs for session events."},"RedirectSettings":{"type":"object","properties":{"defaultUrl":{"type":"string","description":"Default URL to redirect after successful completion."},"cancelUrl":{"type":["null","string"],"description":"URL to redirect when customer cancels (optional)."},"useParamOverride":{"type":["null","boolean"],"description":"Allow redirect URL override via query parameters (optional)."},"redirectOnError":{"type":["null","boolean"],"description":"Redirect to DefaultUrl even on errors (optional)."},"skipResultPage":{"type":["null","boolean"],"description":"Skip the result page and redirect immediately (optional)."}},"description":"Redirect behavior configuration for sessions."},"SessionUISettings":{"type":"object","properties":{"colors":{"type":["null","object"],"additionalProperties":{"type":"string"},"description":"Custom color scheme (optional)."},"theme":{"type":["null","string"],"description":"Theme mode: \"default\" or \"default_dark\" (optional)."},"autoDarkTheme":{"type":["null","boolean"],"description":"Automatically switch theme based on user's browser preferences (optional)."},"logoUrl":{"type":["null","string"],"description":"URL of your logo to display (optional)."},"hideElements":{"type":["null","array"],"items":{"type":"string"},"description":"UI elements to hide (optional)."}},"description":"UI customization settings for the hosted session page."}}}} ``` ### CheckoutSettingsRequest ## The CheckoutSettingsRequest object ```json {"openapi":"3.1.1","info":{"title":"Core.API","version":"v2"},"components":{"schemas":{"CheckoutSettingsRequest":{"type":"object","properties":{"installments":{"type":["null","object"],"additionalProperties":{"type":"array","items":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"format":"int32"}},"description":"Installment options per payment method (optional)."},"amountMode":{"description":"Amount mode for the checkout session.","$ref":"#/components/schemas/AmountModeEnum"},"flexibleAmount":{"oneOf":[{"type":"null"},{"description":"Flexible amount constraints for the checkout session (optional).","$ref":"#/components/schemas/FlexibleAmountSettings"}]},"disableThreeds":{"type":"boolean","description":"Disables 3DS for payments created from this checkout session."},"walletIntegrations":{"oneOf":[{"type":"null"},{"description":"Wallet integration availability for the checkout session (optional, server-enriched).","$ref":"#/components/schemas/SessionWalletIntegrationsDto"}]}},"description":"Checkout-specific configuration settings."},"AmountModeEnum":{"description":"Defines the amount mode for checkout sessions."},"FlexibleAmountSettings":{"type":"object","properties":{"allowedCurrencies":{"type":["null","array"],"items":{"type":"string"},"description":"Allowed currencies for flexible amount mode (required)."},"minAmount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["null","number","string"],"description":"Minimum allowed amount (optional).","format":"double"},"maxAmount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["null","number","string"],"description":"Maximum allowed amount (optional).","format":"double"},"suggestedAmount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["null","number","string"],"description":"Suggested amount to display as a hint to the customer (optional).","format":"double"}},"description":"Constraints for flexible amount checkout sessions."},"SessionWalletIntegrationsDto":{"type":"object","properties":{"googlePay":{"oneOf":[{"type":"null"},{"description":"Google Pay availability for this session.","$ref":"#/components/schemas/SessionWalletDto"}]},"applePay":{"oneOf":[{"type":"null"},{"description":"Apple Pay availability for this session.","$ref":"#/components/schemas/SessionWalletDto"}]},"clickToPay":{"oneOf":[{"type":"null"},{"description":"Click to Pay (Mastercard SRC) availability for this session.","$ref":"#/components/schemas/SessionClickToPayDto"}]}},"description":"Wallet integrations availability for a checkout session."},"SessionWalletDto":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether this wallet is enabled for this checkout session."},"mode":{"type":["null","string"],"description":"The integration mode: \"hosted\", \"api\", or \"both\"."},"dynamicShipping":{"type":"boolean","description":"Enables the Dynamic Shipping feature in Google Pay checkout for this session."}},"description":"Represents the availability and mode of a single wallet type in a checkout session."},"SessionClickToPayDto":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether Click to Pay is enabled for this session."},"mode":{"type":["null","string"],"description":"Integration mode: \"hosted\" | \"api\" | \"both\"."},"openApiClientId":{"type":["null","string"],"description":"Open API client identifier for SDK initialization."},"srcClientId":{"type":["null","string"],"description":"Open API client identifier using the Mastercard SDK field name expected by checkout."},"srcDpaId":{"type":["null","string"],"description":"SRC DPA identifier for SDK initialization."},"supportedCardBrands":{"type":["null","array"],"items":{"type":"string"},"description":"Supported card brands for SDK initialization."},"dpaName":{"type":["null","string"],"description":"Registered DPA name required by the Mastercard JavaScript runtime."},"displayName":{"type":["null","string"],"description":"Display name to show in the Click to Pay UI."},"originDomains":{"type":["null","array"],"items":{"type":"string"},"description":"Allowed origin domains for SDK initialization."}},"description":"Click to Pay runtime block included in checkout session responses.\nContains only the fields the frontend SDK needs to initialize Click to Pay."}}}} ``` ### CheckoutPaymentRequest ## The CheckoutPaymentRequest object ```json {"openapi":"3.1.1","info":{"title":"Core.API","version":"v2"},"components":{"schemas":{"CheckoutPaymentRequest":{"type":"object","properties":{"flow":{"type":["null","string"],"description":"Payment flow type (optional)."},"referenceId":{"type":"string","description":"Your unique reference ID for this payment."},"invoiceNumber":{"type":"string","description":"Invoice or order number."},"items":{"type":["null","array"],"items":{"$ref":"#/components/schemas/PaymentRequestItem"},"description":"Line items for this payment (optional)."},"installments":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["null","integer","string"],"description":"Number of installments for this payment (optional).","format":"int32"},"amount":{"oneOf":[{"type":"null"},{"description":"Payment amount details.","$ref":"#/components/schemas/PaymentAmountDto"}]},"statementDescriptor":{"type":["null","string"],"description":"Text to appear on customer's card statement (optional)."},"metadata":{"type":["null","object"],"additionalProperties":{"type":"string"},"description":"Custom metadata key-value pairs (optional)."}},"description":"Payment details for a checkout session."},"PaymentRequestItem":{"type":"object","properties":{"referenceId":{"type":"string","description":"The reference identifier of the item (e.g., SKU or Id)."},"name":{"type":"string","description":"The name of the item."},"description":{"type":["null","string"],"description":"The description of the item."},"quantity":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"description":"The quantity of the item.","format":"int32"},"price":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["number","string"],"description":"The price per unit of the item.","format":"double"},"discount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["null","number","string"],"description":"The discount applied to the item.","format":"double"},"metadata":{"type":["null","object"],"additionalProperties":{"type":"string"},"description":"The metadata associated with the item."},"tax":{"oneOf":[{"type":"null"},{"description":"The tax amount details for the item.","$ref":"#/components/schemas/TaxAmountDto"}]}},"description":"Represents an item in a payment request."},"TaxAmountDto":{"type":"object","properties":{"type":{"type":["null","string"],"description":"The type of tax. Possible values: \"19210\", \"17934\", \"none\"."},"amount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["number","string"],"description":"The amount of tax.","format":"double"},"rate":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["null","number","string"],"description":"The rate of tax. As decimal value.","format":"double"}},"description":"Represents the tax amount details."},"PaymentAmountDto":{"required":["currency"],"type":"object","properties":{"currency":{"maxLength":3,"minLength":0,"type":"string","description":"The currency of the payment amount.\nThe value should be an ISO Alpha code, such as UYU or USD."},"total":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["number","string"],"description":"The total amount of the payment.","format":"double"},"details":{"oneOf":[{"type":"null"},{"description":"The detailed breakdown of the payment amount.","$ref":"#/components/schemas/PaymentAmountDetailsDto"}]}},"description":"Represents the amount details of a payment."},"PaymentAmountDetailsDto":{"type":"object","properties":{"tax":{"oneOf":[{"type":"null"},{"description":"The tax amount details.","$ref":"#/components/schemas/TaxAmountDto"}]},"taxedAmount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["number","string"],"description":"The taxable amount.","format":"double"},"tipAmount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["null","number","string"],"description":"The tip amount.","format":"double"},"discountAmount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["null","number","string"],"description":"The discount amount.","format":"double"},"shippingAmount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["null","number","string"],"description":"The shipping amount.","format":"double"},"loyaltyProgram":{"oneOf":[{"type":"null"},{"description":"The loyalty program details.","$ref":"#/components/schemas/LoyaltyProgramDto"}]}},"description":"Represents the detailed breakdown of the payment amount."},"LoyaltyProgramDto":{"type":"object","properties":{"amount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["null","number","string"],"format":"double"},"provider":{"type":["null","string"]}}}}}} ``` ### TokenizationSettingsRequest ## The TokenizationSettingsRequest object ```json {"openapi":"3.1.1","info":{"title":"Core.API","version":"v2"},"components":{"schemas":{"TokenizationSettingsRequest":{"type":"object","properties":{"type":{"type":"string","description":"Token storage type: \"store\" or \"temporal\"."},"allowedCardTypes":{"type":["null","array"],"items":{"type":"string"},"description":"Allowed card types for tokenization (optional)."},"features":{"type":["null","array"],"description":"Enabled tokenization features (optional)."},"fields":{"oneOf":[{"type":"null"},{"description":"Field visibility and validation settings (optional).","$ref":"#/components/schemas/TokenizationSettingsFields"}]},"verifyFunds":{"oneOf":[{"type":"null"},{"description":"Fund verification settings for zero-amount authorization (optional).","$ref":"#/components/schemas/VerifyFundsDto"}]},"cardHolder":{"oneOf":[{"type":"null"},{"description":"Pre-filled cardholder information (optional).","$ref":"#/components/schemas/CardHolderDto"}]}},"description":"Settings for tokenization sessions."},"TokenizationSettingsFields":{"type":"object","properties":{"cardholder":{"description":"Cardholder name field settings.","$ref":"#/components/schemas/TokenizationSettingsFieldValues"},"identification":{"description":"Identification document field settings.","$ref":"#/components/schemas/TokenizationSettingsFieldValues"},"billingAddress":{"description":"Billing address field settings.","$ref":"#/components/schemas/TokenizationSettingsFieldValues"}},"description":"Field visibility and behavior settings for tokenization forms."},"TokenizationSettingsFieldValues":{"type":"object","properties":{"visible":{"type":"string","description":"Gets or sets when the field is shown in the hosted tokenization UI."},"readOnly":{"type":"boolean","description":"Gets or sets whether the field is read-only."}},"description":"Represents the visibility state for a tokenization settings field."},"VerifyFundsDto":{"type":"object","properties":{"amount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["number","string"],"description":"Amount to authorize for verification (typically $1.00).","format":"double"},"currency":{"type":"string","description":"Currency code for the verification amount."}},"description":"Settings for card verification via zero-amount or small-amount authorization."},"CardHolderDto":{"type":"object","properties":{"firstName":{"type":["null","string"],"description":"The first name of the cardholder."},"lastName":{"type":["null","string"],"description":"The last name of the cardholder."},"email":{"type":["null","string"],"description":"The email address of the cardholder."},"birthdate":{"type":["null","string"],"description":"The birthdate of the cardholder.","format":"date-time"},"identification":{"oneOf":[{"type":"null"},{"description":"The identification details of the cardholder.","$ref":"#/components/schemas/DocumentDto"}]},"billingAddress":{"oneOf":[{"type":"null"},{"description":"The billing address of the cardholder.","$ref":"#/components/schemas/AddressDto"}]},"phoneNumber":{"type":["null","string"],"description":"The phone number of the cardholder."}},"description":"Represents the details of a cardholder."},"DocumentDto":{"type":"object","properties":{"type":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["null","integer","string"],"description":"Type of the identification document.","format":"int32"},"value":{"type":["null","string"],"description":"Document number or identifier value."}},"description":"Represents an identification or legal document for a customer."},"AddressDto":{"type":"object","properties":{"city":{"type":["null","string"],"description":"City or locality name."},"country":{"type":["null","string"],"description":"Two-letter ISO country code (ISO 3166-1 alpha-2)."},"line1":{"type":"string","description":"Primary address line (street address, P.O. box, company name, etc.)."},"line2":{"type":["null","string"],"description":"Secondary address line (apartment, suite, unit, building, floor, etc.)."},"postalCode":{"type":["null","string"],"description":"ZIP or postal code."},"state":{"type":["null","string"],"description":"State, province, prefecture, or region."}},"description":"Represents a physical address for billing or shipping purposes."}}}} ``` ### SessionDto ## The SessionDto object ```json {"openapi":"3.1.1","info":{"title":"Core.API","version":"v2"},"components":{"schemas":{"SessionDto":{"type":"object","properties":{"id":{"type":"string","description":"Unique session identifier."},"referenceId":{"type":"string","description":"Your reference ID provided during session creation."},"type":{"type":"string","description":"Session type: \"checkout\" or \"tokenization\"."},"paymentId":{"type":["null","string"],"description":"Payment ID if a payment was created (checkout sessions only)."},"expiresAt":{"type":"string","description":"Session expiration date and time (UTC).","format":"date-time"},"status":{"type":"string","description":"Current session status."},"client":{"description":"Client information for this session.","$ref":"#/components/schemas/PaymentClientDto"},"merchant":{"description":"Merchant information for this session.","$ref":"#/components/schemas/MerchantDto"},"customer":{"oneOf":[{"type":"null"},{"description":"Customer information if associated with a customer (optional).","$ref":"#/components/schemas/CustomerDto"}]},"settings":{"description":"Session configuration and settings.","$ref":"#/components/schemas/SessionSettings"},"paymentInstrument":{"oneOf":[{"type":"null"},{"description":"Payment instrument details if a card was tokenized or selected (optional).","$ref":"#/components/schemas/PaymentInstrumentTokenDto"}]},"browserDetails":{"oneOf":[{"type":"null"},{"description":"Browser and device details collected during the session (optional).","$ref":"#/components/schemas/BrowserDetailsDto"}]},"paymentRequest":{"oneOf":[{"type":"null"},{"description":"Payment request details for checkout sessions (optional).","$ref":"#/components/schemas/CheckoutPaymentRequest"}]},"actions":{"type":"array","items":{"$ref":"#/components/schemas/PaymentActions"},"description":"Available actions for this session."}},"description":"Hosted checkout or tokenization session returned by the Sessions API."},"PaymentClientDto":{"type":"object","properties":{"id":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"description":"The unique identifier of the payment client.","format":"int32"},"name":{"type":"string","description":"The name of the payment client."},"owner":{"type":"string","description":"The owner of the payment client."}},"description":"Represents the payment details of a client."},"MerchantDto":{"type":"object","properties":{"id":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["null","integer","string"],"description":"Gets or sets the unique identifier for the merchant.","format":"int32"},"clientId":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"description":"Gets or sets the unique identifier of the client (organization) that owns this merchant.","format":"int32"},"name":{"type":"string","description":"Gets or sets the merchant's display name."},"disabled":{"type":"boolean","description":"Gets or sets whether the merchant account is disabled."},"profile":{"oneOf":[{"type":"null"},{"description":"Gets or sets the merchant's business profile information.","$ref":"#/components/schemas/MerchantProfileDto"}]},"paymentMethods":{"type":"array","items":{"$ref":"#/components/schemas/MerchantPaymentMethodDto"},"description":"Gets or sets the list of payment methods configured for this merchant."}},"description":"Represents a merchant account within the Plexo payment platform."},"MerchantProfileDto":{"type":"object","properties":{"fantasyName":{"type":["null","string"],"description":"Gets or sets the merchant's trading or brand name."},"contactEmails":{"type":["null","array"],"items":{"type":"string"},"description":"Gets or sets the merchant's contact email addresses."},"website":{"type":["null","string"],"description":"Gets or sets the merchant's website URL."},"logoUrl":{"type":["null","string"],"description":"Gets or sets the public CDN URL for the merchant logo, when one has been uploaded."},"logoContentType":{"type":["null","string"],"description":"Gets or sets the uploaded logo MIME type."},"logoUploadedAt":{"type":["null","string"],"description":"Gets or sets the timestamp when the current logo was uploaded.","format":"date-time"},"legalName":{"type":["null","string"],"description":"Gets or sets the merchant's registered legal business name."},"legalId":{"type":["null","string"],"description":"Gets or sets the merchant's tax identification number."},"legalAddress":{"type":["null","string"],"description":"Gets or sets the merchant's registered business address."},"contactEmail":{"type":["null","string"],"description":"Gets or sets the primary contact email for the merchant, if available."}},"description":"Contains business profile and legal information for a merchant."},"MerchantPaymentMethodDto":{"type":"object","properties":{"id":{"type":["null","string"],"description":"Gets or sets the unique identifier for the payment method."},"legacyId":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["null","integer","string"],"description":"Gets or sets the legacy numeric identifier for the payment method.","format":"int32"},"name":{"type":["null","string"],"description":"Gets or sets the display name of the payment method."},"pictureUrl":{"type":["null","string"],"description":"Gets or sets the URL to the payment method's logo image."},"type":{"type":["null","string"],"description":"Gets or sets the payment method type classification."},"settings":{"description":"Gets or sets the configuration settings for this payment method.","$ref":"#/components/schemas/MerchantSettingsDto"},"errors":{"type":["null","array"],"items":{"$ref":"#/components/schemas/PaymentMethodValidationError"},"description":"Gets or sets validation errors for this payment method configuration."}},"description":"Represents a payment method configured for a merchant."},"MerchantSettingsDto":{"type":"object","properties":{"merchantIdentificationNumber":{"type":["null","string"],"description":"Gets or sets the merchant identification number assigned by the payment processor/acquirer."},"terminalNumber":{"type":["null","string"],"description":"Gets or sets the terminal identification number for point-of-sale transactions."},"statementDescriptor":{"type":["null","string"],"description":"Gets or sets the text that appears on customer's card statements."},"rut":{"type":["null","string"],"description":"Gets or sets the merchant's tax identification number (RUT in Uruguay)."},"merchantCategoryCode":{"type":["null","string"],"description":"Gets or sets the Merchant Category Code (MCC) that classifies the merchant's business type."},"banks":{"type":["null","array"],"items":{"type":"string"},"description":"Gets or sets the list of bank codes supported for bank transfers or debit transactions."},"crossBankTransfers":{"type":["null","boolean"],"description":"Gets or sets whether cross-bank transfers are enabled for this merchant."},"checkoutInstallments":{"type":["null","array"],"items":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"format":"int32"},"description":"Gets or sets the available installment plans for checkout payments."},"metadata":{"type":["null","object"],"additionalProperties":{"type":"string"},"description":"Gets or sets custom metadata as key-value pairs for integration-specific configuration."},"paymentProcessor":{"oneOf":[{"type":"null"},{"description":"Gets or sets the payment processor/acquirer configuration for this payment method.","$ref":"#/components/schemas/PaymentProcessorDto"}]},"paymentFacilitator":{"oneOf":[{"type":"null"},{"description":"Gets or sets the payment facilitator (PayFac) configuration for sub-merchant management.","$ref":"#/components/schemas/PaymentFacilitatorMerchantDto"}]},"fraudManagement":{"oneOf":[{"type":"null"},{"description":"Gets or sets the fraud management system configuration.","$ref":"#/components/schemas/FraudManagementSettingsDto"}]},"threeDS":{"oneOf":[{"type":"null"},{"description":"Gets or sets the 3D Secure (3DS) authentication configuration.","$ref":"#/components/schemas/ThreeDSSettingsDto"}]}},"description":"Contains configuration settings for a merchant's payment processing capabilities."},"PaymentProcessorDto":{"type":"object","properties":{"id":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["null","integer","string"],"description":"Gets or sets the unique numeric identifier for this processor configuration.","format":"int32"},"acquirer":{"type":"string","description":"Gets or sets the payment processor/acquirer identifier."},"settings":{"oneOf":[{"type":"null"},{"description":"Gets or sets processor-specific configuration settings and credentials.","$ref":"#/components/schemas/PaymentProcessorSettingsDto"}]},"default":{"type":["null","boolean"],"description":"Gets or sets whether this is the default processor for the payment method."}},"description":"Represents a payment processor/acquirer configuration for routing transactions."},"PaymentProcessorSettingsDto":{"type":"object","properties":{"fields":{"type":"array","items":{"$ref":"#/components/schemas/PaymentProcessorFieldDto"},"description":"Gets or sets the merchant configuration fields required by the payment processor."},"fingerprint":{"oneOf":[{"type":"null"},{"description":"Gets or sets device fingerprinting configuration for fraud detection.","$ref":"#/components/schemas/FingerprintSettingsDto"}]},"cardholderFields":{"type":["null","array"],"items":{"$ref":"#/components/schemas/CardholderFieldDto"},"description":"Gets or sets the cardholder information fields required by the payment processor."},"currencies":{"type":["null","array"],"items":{"$ref":"#/components/schemas/CurrencyDto"},"description":"Gets or sets the currencies supported by this payment processor."},"isoConnection":{"type":["null","boolean"],"description":"Gets or sets whether this processor uses ISO 8583 protocol for transaction communication."},"externalToken":{"type":["null","boolean"],"description":"Gets or sets whether the processor provides its own tokenization service."}},"description":"Contains configuration requirements and capabilities for a payment processor/acquirer."},"PaymentProcessorFieldDto":{"type":"object","properties":{"id":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"format":"int32"},"label":{"type":"string"},"name":{"type":"string"},"description":{"type":["null","string"]},"required":{"type":"boolean"}}},"FingerprintSettingsDto":{"type":"object","properties":{"name":{"type":"string"}}},"CardholderFieldDto":{"type":"object","properties":{"id":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"description":"Gets or sets the unique numeric identifier for this field.","format":"int32"},"label":{"type":"string","description":"Gets or sets the display label for this field in user interfaces."},"name":{"type":"string","description":"Gets or sets the field name/identifier used in API requests."},"description":{"type":["null","string"],"description":"Gets or sets an optional description providing guidance for completing this field."},"required":{"type":"boolean","description":"Gets or sets whether this field is mandatory for payment processing."}},"description":"Represents a required or optional field for cardholder information in payment forms."},"CurrencyDto":{"type":"object","properties":{"id":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"format":"int32"},"isoCode":{"type":"string"},"name":{"type":"string"},"plural":{"type":"string"},"symbol":{"type":"string"}}},"PaymentFacilitatorMerchantDto":{"type":"object","properties":{"id":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"description":"Gets or sets the unique identifier of the payment facilitator sub-merchant.","format":"int32"},"name":{"type":["null","string"],"description":"Gets or sets the name of the payment facilitator sub-merchant."},"merchantId":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"description":"Gets or sets the unique identifier of the parent merchant account.","format":"int32"}},"description":"Represents a sub-merchant operating under a Payment Facilitator (PayFac) model."},"FraudManagementSettingsDto":{"type":"object","properties":{"provider":{"type":"string","description":"Gets or sets the fraud management provider/service."},"enabled":{"type":"boolean","description":"Gets or sets whether fraud management screening is enabled for this payment method."}},"description":"Configuration settings for fraud detection and prevention services."},"ThreeDSSettingsDto":{"type":"object","properties":{"provider":{"type":"string","description":"Gets or sets the 3D Secure provider/service used for authentication."},"enabled":{"type":"boolean","description":"Gets or sets whether 3D Secure authentication is enabled for this payment method."},"rules":{"oneOf":[{"type":"null"},{"description":"Gets or sets the rule-based configuration for when 3DS authentication is required.","$ref":"#/components/schemas/ThreedsRulesDto"}]},"metadata":{"type":["null","object"],"additionalProperties":{"type":"string"},"description":"Gets or sets custom metadata for provider-specific 3DS configuration."}},"description":"Configuration settings for 3D Secure (3DS) authentication."},"ThreedsRulesDto":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Gets or sets whether rule-based 3DS triggering is enabled."},"tier":{"type":"string","description":"Gets or sets the 3DS tier/level that determines authentication requirements."}},"description":"Rule-based configuration for 3D Secure authentication triggering."},"PaymentMethodValidationError":{"type":"object","properties":{"code":{"type":"string","description":"Gets or sets the error code identifying the specific validation issue."},"message":{"type":"string","description":"Gets or sets the human-readable error message describing the issue."}},"description":"Represents a validation error for a payment method configuration."},"CustomerDto":{"type":"object","properties":{"id":{"type":["null","string"],"description":"Unique identifier for the customer assigned by Plexo."},"referenceId":{"type":["null","string"],"description":"External reference identifier for the customer from your system."},"metadata":{"type":["null","object"],"additionalProperties":{"type":"string"},"description":"Custom key-value pairs for storing additional customer information."},"description":{"type":["null","string"],"description":"Optional description or notes about the customer."},"email":{"type":["null","string"],"description":"Customer's email address."},"name":{"type":["null","string"],"description":"Customer's full name (computed property)."},"phone":{"type":["null","string"],"description":"Customer's phone number with country code."},"firstName":{"type":["null","string"],"description":"Customer's first name or given name."},"lastName":{"type":["null","string"],"description":"Customer's last name or family name."},"document":{"oneOf":[{"type":"null"},{"description":"Primary identification document (e.g., national ID, driver's license).","$ref":"#/components/schemas/DocumentDto"}]},"identification":{"oneOf":[{"type":"null"},{"description":"Secondary identification document or tax identification number.","$ref":"#/components/schemas/DocumentDto"}]},"birthdate":{"type":["null","string"],"description":"Customer's date of birth.","format":"date-time"},"address":{"oneOf":[{"type":"null"},{"description":"Customer's billing or primary address.","$ref":"#/components/schemas/AddressDto"}]},"shipping":{"oneOf":[{"type":"null"},{"description":"Customer's shipping address and contact information.","$ref":"#/components/schemas/ShippingDto"}]},"status":{"type":["null","string"],"description":"Current status of the customer account."}},"description":"Customer profile used in customer, payment, and session responses."},"DocumentDto":{"type":"object","properties":{"type":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["null","integer","string"],"description":"Type of the identification document.","format":"int32"},"value":{"type":["null","string"],"description":"Document number or identifier value."}},"description":"Represents an identification or legal document for a customer."},"AddressDto":{"type":"object","properties":{"city":{"type":["null","string"],"description":"City or locality name."},"country":{"type":["null","string"],"description":"Two-letter ISO country code (ISO 3166-1 alpha-2)."},"line1":{"type":"string","description":"Primary address line (street address, P.O. box, company name, etc.)."},"line2":{"type":["null","string"],"description":"Secondary address line (apartment, suite, unit, building, floor, etc.)."},"postalCode":{"type":["null","string"],"description":"ZIP or postal code."},"state":{"type":["null","string"],"description":"State, province, prefecture, or region."}},"description":"Represents a physical address for billing or shipping purposes."},"ShippingDto":{"type":"object","properties":{"address":{"description":"Physical delivery address for shipping.","$ref":"#/components/schemas/AddressDto"},"name":{"type":"string","description":"Name of the person receiving the shipment."},"phone":{"type":"string","description":"Contact phone number for delivery coordination."}},"description":"Shipping information for delivering physical goods to a customer."},"SessionSettings":{"type":"object","properties":{"paymentMethodTypes":{"type":["null","array"],"items":{"type":"string"},"description":"Allowed payment method types (e.g., \"card\", \"bank_transfer\")."},"paymentMethods":{"type":["null","array"],"items":{"type":"string"},"description":"Allowed payment methods (card brands: \"VISA\", \"MASTERCARD\", \"OCA\", etc.)."},"tokenization":{"oneOf":[{"type":"null"},{"description":"Tokenization-specific settings (required for tokenization sessions).","$ref":"#/components/schemas/TokenizationSettingsRequest"}]},"checkout":{"oneOf":[{"type":"null"},{"description":"Checkout-specific settings (optional for checkout sessions).","$ref":"#/components/schemas/CheckoutSettingsRequest"}]},"callbacks":{"oneOf":[{"type":"null"},{"description":"Callback URLs for session events (optional).","$ref":"#/components/schemas/Callbacks"}]},"redirects":{"oneOf":[{"type":"null"},{"description":"Redirect behavior configuration (optional).","$ref":"#/components/schemas/RedirectSettings"}]},"ui":{"oneOf":[{"type":"null"},{"description":"UI customization settings (optional).","$ref":"#/components/schemas/SessionUISettings"}]}},"description":"Configuration settings for a session."},"TokenizationSettingsRequest":{"type":"object","properties":{"type":{"type":"string","description":"Token storage type: \"store\" or \"temporal\"."},"allowedCardTypes":{"type":["null","array"],"items":{"type":"string"},"description":"Allowed card types for tokenization (optional)."},"features":{"type":["null","array"],"description":"Enabled tokenization features (optional)."},"fields":{"oneOf":[{"type":"null"},{"description":"Field visibility and validation settings (optional).","$ref":"#/components/schemas/TokenizationSettingsFields"}]},"verifyFunds":{"oneOf":[{"type":"null"},{"description":"Fund verification settings for zero-amount authorization (optional).","$ref":"#/components/schemas/VerifyFundsDto"}]},"cardHolder":{"oneOf":[{"type":"null"},{"description":"Pre-filled cardholder information (optional).","$ref":"#/components/schemas/CardHolderDto"}]}},"description":"Settings for tokenization sessions."},"TokenizationSettingsFields":{"type":"object","properties":{"cardholder":{"description":"Cardholder name field settings.","$ref":"#/components/schemas/TokenizationSettingsFieldValues"},"identification":{"description":"Identification document field settings.","$ref":"#/components/schemas/TokenizationSettingsFieldValues"},"billingAddress":{"description":"Billing address field settings.","$ref":"#/components/schemas/TokenizationSettingsFieldValues"}},"description":"Field visibility and behavior settings for tokenization forms."},"TokenizationSettingsFieldValues":{"type":"object","properties":{"visible":{"type":"string","description":"Gets or sets when the field is shown in the hosted tokenization UI."},"readOnly":{"type":"boolean","description":"Gets or sets whether the field is read-only."}},"description":"Represents the visibility state for a tokenization settings field."},"VerifyFundsDto":{"type":"object","properties":{"amount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["number","string"],"description":"Amount to authorize for verification (typically $1.00).","format":"double"},"currency":{"type":"string","description":"Currency code for the verification amount."}},"description":"Settings for card verification via zero-amount or small-amount authorization."},"CardHolderDto":{"type":"object","properties":{"firstName":{"type":["null","string"],"description":"The first name of the cardholder."},"lastName":{"type":["null","string"],"description":"The last name of the cardholder."},"email":{"type":["null","string"],"description":"The email address of the cardholder."},"birthdate":{"type":["null","string"],"description":"The birthdate of the cardholder.","format":"date-time"},"identification":{"oneOf":[{"type":"null"},{"description":"The identification details of the cardholder.","$ref":"#/components/schemas/DocumentDto"}]},"billingAddress":{"oneOf":[{"type":"null"},{"description":"The billing address of the cardholder.","$ref":"#/components/schemas/AddressDto"}]},"phoneNumber":{"type":["null","string"],"description":"The phone number of the cardholder."}},"description":"Represents the details of a cardholder."},"CheckoutSettingsRequest":{"type":"object","properties":{"installments":{"type":["null","object"],"additionalProperties":{"type":"array","items":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"format":"int32"}},"description":"Installment options per payment method (optional)."},"amountMode":{"description":"Amount mode for the checkout session.","$ref":"#/components/schemas/AmountModeEnum"},"flexibleAmount":{"oneOf":[{"type":"null"},{"description":"Flexible amount constraints for the checkout session (optional).","$ref":"#/components/schemas/FlexibleAmountSettings"}]},"disableThreeds":{"type":"boolean","description":"Disables 3DS for payments created from this checkout session."},"walletIntegrations":{"oneOf":[{"type":"null"},{"description":"Wallet integration availability for the checkout session (optional, server-enriched).","$ref":"#/components/schemas/SessionWalletIntegrationsDto"}]}},"description":"Checkout-specific configuration settings."},"AmountModeEnum":{"description":"Defines the amount mode for checkout sessions."},"FlexibleAmountSettings":{"type":"object","properties":{"allowedCurrencies":{"type":["null","array"],"items":{"type":"string"},"description":"Allowed currencies for flexible amount mode (required)."},"minAmount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["null","number","string"],"description":"Minimum allowed amount (optional).","format":"double"},"maxAmount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["null","number","string"],"description":"Maximum allowed amount (optional).","format":"double"},"suggestedAmount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["null","number","string"],"description":"Suggested amount to display as a hint to the customer (optional).","format":"double"}},"description":"Constraints for flexible amount checkout sessions."},"SessionWalletIntegrationsDto":{"type":"object","properties":{"googlePay":{"oneOf":[{"type":"null"},{"description":"Google Pay availability for this session.","$ref":"#/components/schemas/SessionWalletDto"}]},"applePay":{"oneOf":[{"type":"null"},{"description":"Apple Pay availability for this session.","$ref":"#/components/schemas/SessionWalletDto"}]},"clickToPay":{"oneOf":[{"type":"null"},{"description":"Click to Pay (Mastercard SRC) availability for this session.","$ref":"#/components/schemas/SessionClickToPayDto"}]}},"description":"Wallet integrations availability for a checkout session."},"SessionWalletDto":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether this wallet is enabled for this checkout session."},"mode":{"type":["null","string"],"description":"The integration mode: \"hosted\", \"api\", or \"both\"."},"dynamicShipping":{"type":"boolean","description":"Enables the Dynamic Shipping feature in Google Pay checkout for this session."}},"description":"Represents the availability and mode of a single wallet type in a checkout session."},"SessionClickToPayDto":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Whether Click to Pay is enabled for this session."},"mode":{"type":["null","string"],"description":"Integration mode: \"hosted\" | \"api\" | \"both\"."},"openApiClientId":{"type":["null","string"],"description":"Open API client identifier for SDK initialization."},"srcClientId":{"type":["null","string"],"description":"Open API client identifier using the Mastercard SDK field name expected by checkout."},"srcDpaId":{"type":["null","string"],"description":"SRC DPA identifier for SDK initialization."},"supportedCardBrands":{"type":["null","array"],"items":{"type":"string"},"description":"Supported card brands for SDK initialization."},"dpaName":{"type":["null","string"],"description":"Registered DPA name required by the Mastercard JavaScript runtime."},"displayName":{"type":["null","string"],"description":"Display name to show in the Click to Pay UI."},"originDomains":{"type":["null","array"],"items":{"type":"string"},"description":"Allowed origin domains for SDK initialization."}},"description":"Click to Pay runtime block included in checkout session responses.\nContains only the fields the frontend SDK needs to initialize Click to Pay."},"Callbacks":{"type":"object","properties":{"paymentCallbackUrl":{"type":["null","string"],"description":"Callback URL for payment events triggered by checkout sessions."},"tokenizationCallbackUrl":{"type":["null","string"],"description":"Callback URL for tokenization events triggered by tokenization sessions."}},"description":"Callback URLs for session events."},"RedirectSettings":{"type":"object","properties":{"defaultUrl":{"type":"string","description":"Default URL to redirect after successful completion."},"cancelUrl":{"type":["null","string"],"description":"URL to redirect when customer cancels (optional)."},"useParamOverride":{"type":["null","boolean"],"description":"Allow redirect URL override via query parameters (optional)."},"redirectOnError":{"type":["null","boolean"],"description":"Redirect to DefaultUrl even on errors (optional)."},"skipResultPage":{"type":["null","boolean"],"description":"Skip the result page and redirect immediately (optional)."}},"description":"Redirect behavior configuration for sessions."},"SessionUISettings":{"type":"object","properties":{"colors":{"type":["null","object"],"additionalProperties":{"type":"string"},"description":"Custom color scheme (optional)."},"theme":{"type":["null","string"],"description":"Theme mode: \"default\" or \"default_dark\" (optional)."},"autoDarkTheme":{"type":["null","boolean"],"description":"Automatically switch theme based on user's browser preferences (optional)."},"logoUrl":{"type":["null","string"],"description":"URL of your logo to display (optional)."},"hideElements":{"type":["null","array"],"items":{"type":"string"},"description":"UI elements to hide (optional)."}},"description":"UI customization settings for the hosted session page."},"PaymentInstrumentTokenDto":{"type":"object","properties":{"clientId":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"description":"The unique identifier of the client.","format":"int32"},"paymentMethodId":{"type":"string","description":"The unique identifier of the payment method."},"paymentMethodType":{"type":"string","description":"The type of the payment method."},"tokenizationType":{"type":"string","description":"The type of tokenization."},"status":{"type":"string","description":"The status of the payment instrument token."},"token":{"type":"string","description":"The token of the payment instrument."},"source":{"type":"string","description":"The source of the payment instrument token. Possible values: \"card\" or \"network-token\"."},"bin":{"type":["null","string"],"description":"The BIN (Bank Identification Number) of the card."},"last4":{"type":["null","string"],"description":"The last 4 digits of the card."},"expMonth":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"description":"The expiration month of the card.","format":"int32"},"expYear":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"description":"The expiration year of the card.","format":"int32"},"cardName":{"type":"string","description":"Masked PAN."},"cardholderName":{"type":"string","description":"The cardholder name."},"cardType":{"type":["null","string"],"description":"The type of the card. Possible values: \"credit\", \"debit\", \"prepaid\"."},"cardOrigin":{"type":["null","string"],"description":"The origin of the card."},"paymentProcessor":{"oneOf":[{"type":"null"},{"description":"The payment processor details.","$ref":"#/components/schemas/PaymentProcesesorRequestDto"}]},"issuer":{"oneOf":[{"type":"null"},{"description":"The issuer of the card.","$ref":"#/components/schemas/CardIssuer"}]},"expiresAt":{"type":["null","string"],"description":"The expiration date of the token.","format":"date-time"},"usedAt":{"type":["null","string"],"description":"The date when the token was used.","format":"date-time"},"customerId":{"type":["null","string"],"description":"The unique identifier of the customer.","format":"uuid"},"createdAt":{"type":["null","string"],"description":"The creation date of the token.","format":"date-time"},"uniqueIdAlias":{"type":["null","string"],"description":"The unique alias identifier for the payment instrument token."},"metadata":{"type":["null","object"],"additionalProperties":{"type":"string"},"description":"Additional metadata for the payment instrument token. Contains information like payment source (google-pay, apple-pay), authentication method, cryptogram indicators, etc."}},"description":"Represents the details of a payment instrument token."},"PaymentProcesesorRequestDto":{"type":"object","properties":{"id":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["null","integer","string"],"format":"int32"},"acquirer":{"type":"string"}}},"CardIssuer":{"type":"object","properties":{"id":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"description":"Gets or sets the unique identifier for the card issuer.","format":"int32"},"name":{"type":["null","string"],"description":"Gets or sets the full name of the issuing bank."},"shortName":{"type":["null","string"],"description":"Gets or sets the abbreviated name or common name of the issuing bank."},"pictureUrl":{"type":["null","string"],"description":"Gets or sets the URL to the issuer's logo image."},"externalId":{"type":["null","string"],"description":"Gets or sets the external identifier used by payment processors or card networks."},"country":{"type":["null","string"],"description":"Gets or sets the issuer country name derived from BIN locality data."},"countryCode":{"type":["null","string"],"description":"Gets or sets the ISO 3166-1 alpha-2 country code of the issuer."}},"description":"Represents a bank or financial institution that issues payment cards."},"BrowserDetailsDto":{"type":"object","properties":{"ipAddress":{"type":["null","string"],"description":"Public IP address observed for the payer's browser or device."},"deviceFingerprint":{"type":["null","string"],"description":"Merchant-generated device fingerprint or browser identifier, when available."},"userAgent":{"type":["null","string"],"description":"Full browser user-agent string from the payer's device."},"device":{"type":["null","string"],"description":"High-level device type, such as desktop, mobile, or tablet."},"operativeSystem":{"type":["null","string"],"description":"Operating system reported by the payer's device, such as iOS, Android, Windows, or macOS."}},"description":"Represents the details of a browser used in a payment transaction."},"CheckoutPaymentRequest":{"type":"object","properties":{"flow":{"type":["null","string"],"description":"Payment flow type (optional)."},"referenceId":{"type":"string","description":"Your unique reference ID for this payment."},"invoiceNumber":{"type":"string","description":"Invoice or order number."},"items":{"type":["null","array"],"items":{"$ref":"#/components/schemas/PaymentRequestItem"},"description":"Line items for this payment (optional)."},"installments":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["null","integer","string"],"description":"Number of installments for this payment (optional).","format":"int32"},"amount":{"oneOf":[{"type":"null"},{"description":"Payment amount details.","$ref":"#/components/schemas/PaymentAmountDto"}]},"statementDescriptor":{"type":["null","string"],"description":"Text to appear on customer's card statement (optional)."},"metadata":{"type":["null","object"],"additionalProperties":{"type":"string"},"description":"Custom metadata key-value pairs (optional)."}},"description":"Payment details for a checkout session."},"PaymentRequestItem":{"type":"object","properties":{"referenceId":{"type":"string","description":"The reference identifier of the item (e.g., SKU or Id)."},"name":{"type":"string","description":"The name of the item."},"description":{"type":["null","string"],"description":"The description of the item."},"quantity":{"pattern":"^-?(?:0|[1-9]\\d*)$","type":["integer","string"],"description":"The quantity of the item.","format":"int32"},"price":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["number","string"],"description":"The price per unit of the item.","format":"double"},"discount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["null","number","string"],"description":"The discount applied to the item.","format":"double"},"metadata":{"type":["null","object"],"additionalProperties":{"type":"string"},"description":"The metadata associated with the item."},"tax":{"oneOf":[{"type":"null"},{"description":"The tax amount details for the item.","$ref":"#/components/schemas/TaxAmountDto"}]}},"description":"Represents an item in a payment request."},"TaxAmountDto":{"type":"object","properties":{"type":{"type":["null","string"],"description":"The type of tax. Possible values: \"19210\", \"17934\", \"none\"."},"amount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["number","string"],"description":"The amount of tax.","format":"double"},"rate":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["null","number","string"],"description":"The rate of tax. As decimal value.","format":"double"}},"description":"Represents the tax amount details."},"PaymentAmountDto":{"required":["currency"],"type":"object","properties":{"currency":{"maxLength":3,"minLength":0,"type":"string","description":"The currency of the payment amount.\nThe value should be an ISO Alpha code, such as UYU or USD."},"total":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["number","string"],"description":"The total amount of the payment.","format":"double"},"details":{"oneOf":[{"type":"null"},{"description":"The detailed breakdown of the payment amount.","$ref":"#/components/schemas/PaymentAmountDetailsDto"}]}},"description":"Represents the amount details of a payment."},"PaymentAmountDetailsDto":{"type":"object","properties":{"tax":{"oneOf":[{"type":"null"},{"description":"The tax amount details.","$ref":"#/components/schemas/TaxAmountDto"}]},"taxedAmount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["number","string"],"description":"The taxable amount.","format":"double"},"tipAmount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["null","number","string"],"description":"The tip amount.","format":"double"},"discountAmount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["null","number","string"],"description":"The discount amount.","format":"double"},"shippingAmount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["null","number","string"],"description":"The shipping amount.","format":"double"},"loyaltyProgram":{"oneOf":[{"type":"null"},{"description":"The loyalty program details.","$ref":"#/components/schemas/LoyaltyProgramDto"}]}},"description":"Represents the detailed breakdown of the payment amount."},"LoyaltyProgramDto":{"type":"object","properties":{"amount":{"pattern":"^-?(?:0|[1-9]\\d*)(?:\\.\\d+)?$","type":["null","number","string"],"format":"double"},"provider":{"type":["null","string"]}}},"PaymentActions":{"type":"object","properties":{"rel":{"type":"string","description":"Relation or mode label for the action."},"href":{"type":"string","description":"URL to call or present to the payer."},"method":{"type":"string","description":"HTTP verb or hosted-session mode indicator."}},"description":"Action metadata returned with payments and hosted session responses."}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://plexo.gitbook.io/rest-api/api-reference/models.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.