# Create Checkout

Creates a Checkout Session.

Endpoint: POST /checkout
Version: 2.0
Security: accountId, apiKey

## Request fields (application/json):

  - `type` (string, required)
    Only the first value in the Array is considered (e.g. ['single', 'frequent'] would be equivalent to ['single']).
    Enum: "single", "frequent", "subscription"

  - `payment` (object, required)
    Describing the payment configuration.

  - `payment.methods` (array)
    Payment Method | Single Payment | Frequent Payment | Subscription Payment |
---------|----------|---------|----------|
 CC (Credit Card)    | x | x | x |
 DD (Direct Debit)   | x | x | x |
 MBW (MB WAY)        | x | x | - |
 MB (Multibanco)     | x | x | - |
 VI (Virtual IBAN)   | x | x | - |
 SW (Samsung Wallet) | x | - | - |
 AP (Apple Pay)      | x | - | - |
 GP (Google Pay)     | x | - | - |
    Enum: "MB", "MBW", "DD", "CC", "VI", "AP", "GP", "SW"

  - `payment.type` (any)
    Specifies the type of financial operation being performed. This property is used only for Single Payments. 

TYPE | DESCRIPTION |
---------|----------|
 sale          | a complete transaction where funds are immediately captured. |
 authorisation | a temporary hold on funds pending a future capture.          |
    Enum: "sale", "authorisation"

  - `payment.capture` (object)
    Required only if the payment type is sale.

  - `payment.capture.transaction_key` (string)
    The internal key used to identify this transaction in the merchant's database.

  - `payment.capture.capture_date` (string)
    The date on which the capture is performed.
    Example: "2026-05-15"

  - `payment.capture.account` (object)
    This object is used for multi-account clients.

  - `payment.capture.account.id` (string)
    The uuid of the account.

  - `payment.capture.splits` (object)
    This object is only used in split payments.

  - `payment.capture.splits.split_key` (string)
    A customizable text field for users to input their own identifier for the split.
    Example: "Payment of Invoice Nº 1982652"

  - `payment.capture.splits.split_descriptive` (string)
    A text field that describes the transaction as it will appear on the end user's account statement. This is typically used to provide clear, recognizable information about the payment, such as "Payment of Invoice Nº 1982652" or "Ticket for Queen".
    Example: "Payment of Invoice Nº 1982652"

  - `payment.capture.splits.account` (object)
    The account to receive the split funds

  - `payment.capture.splits.account.id` (string, required)
    Example: "c6056234-a3f9-42de-b944-3ed793fcb6bb"

  - `payment.capture.splits.value` (number, required)
    The monetary amount for the transaction. This field specifies the value of the payment in the designated currency. It must be a positive decimal number representing the exact amount to be processed.
    Example: 17.5

  - `payment.capture.splits.clearing_period` (string)
    The clearing period must follow the format 1Y, 10W or 30D. Y for Years, W for weeks, D for days. Minimum is 7 days, maximum is 1 year.
    Example: "30D"

  - `payment.capture.splits.margin_account` (object)
    The account to which the margin value should be routed. This field specifies the destination account for the margin portion of the funds, ensuring that the correct recipient receives the designated margin value.

  - `payment.capture.splits.margin_value` (number)
    The margin amount to be deducted from this split
    Example: 0.25

  - `payment.capture.descriptive` (string)
    Required if the payment method is 'MBW'.

  - `payment.sdd_mandate` (object)
    The SDD Mandate object contains the necessary fields to create a SEPA Direct Debit mandate. This object ensures that all required information is provided to authorize and process SEPA Direct Debit transactions. Object required when method is Direct Debit.

  - `payment.sdd_mandate.iban` (string, required)
    The International Bank Account Number (IBAN) of the debtor's account. This field is used to uniquely identify the debtor's bank account across international borders, ensuring accurate and efficient processing of SEPA Direct Debit transactions. The IBAN is a standardized format that includes the country code, check digits, bank code, and account number.
    Example: "PT50002700000001234567833"

  - `payment.sdd_mandate.key` (string)
    A customizable text field for users to input their own identifier for the SDD mandate.
    Example: "Sdd mandate Key Example"

  - `payment.sdd_mandate.name` (string, required)
    Full name of the account holder as it appears on the bank account.
    Example: "John Doe"

  - `payment.sdd_mandate.email` (string, required)
    Email address of the account holder for mandate-related communications.
    Example: "john.doe@example.com"

  - `payment.sdd_mandate.phone` (string, required)
    Phone number of the account holder without country code.
    Example: "911234567"

  - `payment.sdd_mandate.account_holder` (string, required)
    The name of the person or entity that holds the bank account. This field is used to identify the owner of the bank account involved in the transaction, ensuring that the correct account is credited or debited.
    Example: "John Doe"

  - `payment.sdd_mandate.country_code` (string)
    ISO 3166-1 alpha-2 country code of the customer's country.
    Example: "PT"

  - `payment.sdd_mandate.max_num_debits` (string)
    Maximum number of debits allowed under this mandate.
    Example: "12"

  - `payment.sdd_mandate.billing_entity` (string)
    The entity responsible for billing in the context of the SEPA Direct Debit (SDD) mandate.
    Example: "PT16103627"

  - `payment.expiration_time` (string)
    The last possible time to make the payment. Applicable in Multibanco payments.

Note: If the expiration time is less than the default checkout session expiration (which is 30 minutes),
the user won't be able to interact with the Checkout after that time.
    Example: "2027-12-12 16:05"

  - `payment.currency` (string)
    The currency code in ISO 4217 format (e.g., "EUR" for Euro). This field specifies the type of currency used in financial operation.

  - `payment.key` (string)
    The merchant's key for identifying the payment.

  - `payment.max_value` (number)
    Additional property for frequent payments.

  - `payment.min_value` (number)
    Additional property for frequent payments.

  - `payment.unlimited_payments` (boolean)
    Additional property for frequent payments.

  - `payment.frequency` (any)
    Additional property for subscription payments.
    Enum: "1D", "1W", "2W", "1M", "2M", "3M", "4M", "6M", "1Y", "2Y", "3Y"

  - `payment.max_captures` (integer)
    Additional property for subscription payments.

Defines a maximum number of captures, is required when no expiration_time is set.

  - `payment.start_time` (string)
    Additional property for subscription payments.
Defines the start of the billing cycles.

  - `payment.failover` (boolean)
    Additional property for subscription payments.

After all retries failed, the payment cycle can have another try with another single method.

  - `payment.capture_now` (boolean)
    Additional property for subscription payments.

Whether to schedule an immediate capture and schedule the second one for start_time.

  - `payment.retries` (number)
    Additional property for subscription payments.

Number of retries in each payment cycle.
The chosen frequency will define the max number of possible retries.

  - `payment.multibanco` (object)
    An object that holds the details specific to a Multibanco transaction. This property is used only for Single Payments.

  - `payment.multibanco.expiration_time` (string, required)
    The end timestamp indicating the deadline by which the Multibanco Reference must be paid. It defines the final time within which the payment must be completed. The format follows RFC3339 (e.g., "2024-06-30T21:38:31Z").

  - `payment.multibanco.start_time` (string)
    The starting timestamp indicating when the Multibanco Reference becomes valid for payment. It defines the initial time from which the payment can be made. The format follows RFC3339 (e.g., "2024-06-30T21:38:31Z"). This field is optional and defaults to the current timestamp if not specified, or if the sent value is in the past.

  - `payment.multibanco.multibanco` (object)
    An object that holds the details specific to a Multibanco transaction.

  - `payment.multibanco.multibanco.product` (string)
    This field is used to select the desired product. Below, the supported features for each product are listed. The default value is CHECKDIGIT. Additional costs may apply depending on the selected product.

Product Features:

| Product Type | Immediate Issuance | Expiration Date | Start Date |
|--------------|-------------------|-----------------|------------|
| CHECKDIGIT   | ✓                 | ✓               | ✗          |
| SPG          | ✗                 | ✓               | ✓          |
| FILE         | ✗                 | ✓               | ✓          |

Descriptions:
- CHECKDIGIT: Standard Multibanco references with immediate issuance
- SPG: Special purpose group references with scheduling capabilities
- FILE: File-based references for batch processing
    Enum: "FILE", "SPG", "CHECKDIGIT"

  - `payment.notification` (object)
    Notification settings for payment methods.

  - `payment.notification.customer_method_instructions_email` (boolean)
    Specifies whether an email containing the payment instructions (e.g., Multibanco reference or Virtual IBAN details) should be sent to the customer's email address when the selected payment method is Multibanco or Virtual IBAN.
    Example: true

  - `order` (object)
    Order represent the order/cart being paid. Order is required if type is one single or subscription.

  - `order.items` (array)

  - `order.items.description` (string, required)
    Brief description of the item.
    Example: "Description Example"

  - `order.items.quantity` (number)
    Quantity of this item being paid.
    Example: 2

  - `order.items.key` (string)
    The merchant's key to identify the item
    Example: "Key Example"

  - `order.items.value` (number, required)
    The price being paid for the specific item(s), rounded to 2 decimals.
    Example: 10.55

  - `order.key` (string)
    The merchant's key to identify the order.
    Example: "Example Key"

  - `order.value` (number, required)
    The price being paid for the entire order, rounded to 2 decimals
    Example: 50.78

  - `customer` (object)
    The customer details.

  - `customer.id` (string)
    A unique identifier for the resource. While typically formatted as a UUID (Universally Unique Identifier), it can also be in other formats as defined by the user. This field ensures the resource can be distinctly recognized and referenced.

  - `customer.name` (string)
    The full name of the customer. This field is used to identify the customer and personalize interactions. It typically includes the customer's first name and last name.
    Example: "Jonh Doe"

  - `customer.email` (string)
    The email address of the customer. This field is used for communication purposes, including sending transaction confirmations, receipts, and other notifications related to the customer's activities.
    Example: "example@easypay.pt"

  - `customer.phone` (string)
    The contact phone number of the customer has the E.164 pattern. This number will be used to make the payment if the method is MBWAY.
    Example: "911234567"

  - `customer.phone_indicative` (string)
    The phone country code.
    Example: "+351"

  - `customer.language` (string)
    The language preference of the customer, specified in the ISO 639-1 Alpha-2 format (e.g., "EN" for English, "PT" for Portuguese). This field is used to indicate the customer's preferred language for communication and documentation.
    Example: "EN"

  - `customer.fiscal_number` (string)
    The customer's fiscal number (prefixed by the country code).
    Example: "PT268826145"

  - `customer.key` (string)
    The merchant's key to identify the customer.
    Example: "Key Example"

## Response 201 fields (application/json):

  - `id` (string)
    UUID of the checkout.
    Example: "5db36b83-0664-4bc4-a760-7040ac3726f0"

  - `session` (string)
    Session token to be used by the rest of the Checkout process.
    Example: "PX2duB7zMRISp6WrKdkOHLcvhIj-7-yUXMYHDQf5k7L5b5mA3D_m5TCdsYT-mCOaALGw4k95I_gjYQS-tcsxAAjTqU4G0UM5sd2o5wdGTGOOuoZVv0CwmiBwhUY9j4Dq4MDryEEPXtqMHEYi7PJz7dakeBemaWFg9GCEvdE6BM_uDBjZLBIS--_uFjRWpKm5enhwTkGvF3iTXuNrsRAxrW8YTsPUGJZumz2s-xSwa6XVaqRqO9uTvuHWy9TrEs1eCTeiWpqwZaj8_aNry5Tc44Epvvw4-4yebDaMQ1gJIHyJDzkLQ9mv4lNPjOFFtJPHihzgIybJdxzE1f6oBnjudMJa0LHsyzkHt29_j4FNRwSyU0Sti2vtW9SEAJ9D8pqrhvMg7zDQkvYLxjNJrME8EVqlGA_il0hc75wigX3hRdoVokF7u0-0ac0HYltG2zYEgE2lxqzPaG_lSbidSBAIoFWhY5rij3TyQHg6lPhHF6jYhn0ytvsBRauIdlZnJau18KzcOH4fcwN8d59SuhffuSyD_Mtd7trlzz6lWM9AeoY="

  - `config` (any,null)

## Response 400 fields (application/json):

  - `status` (string, required)

  - `message` (array, required)
    An array of human-readable messages included in the response. These messages provide detailed information about the success of the operation or explain the reasons for any failure. This field is always present in the response to ensure clarity and transparency regarding the outcome of the API request.

## Response 401 fields (application/json):

  - `status` (string, required)

  - `message` (array, required)
    An array of human-readable messages included in the response. These messages provide detailed information about the success of the operation or explain the reasons for any failure. This field is always present in the response to ensure clarity and transparency regarding the outcome of the API request.

## Response 403 fields (application/json):

  - `status` (string, required)

  - `message` (array, required)
    An array of human-readable messages included in the response. These messages provide detailed information about the success of the operation or explain the reasons for any failure. This field is always present in the response to ensure clarity and transparency regarding the outcome of the API request.

## Response 404 fields (application/json):

  - `status` (string, required)

  - `message` (array, required)
    An array of human-readable messages included in the response. These messages provide detailed information about the success of the operation or explain the reasons for any failure. This field is always present in the response to ensure clarity and transparency regarding the outcome of the API request.

## Response 429 fields (application/json):

  - `status` (string, required)

  - `message` (array, required)
    An array of human-readable messages included in the response. These messages provide detailed information about the success of the operation or explain the reasons for any failure. This field is always present in the response to ensure clarity and transparency regarding the outcome of the API request.

## Response 500 fields (application/json):

  - `status` (string, required)

  - `message` (array, required)
    An array of human-readable messages included in the response. These messages provide detailed information about the success of the operation or explain the reasons for any failure. This field is always present in the response to ensure clarity and transparency regarding the outcome of the API request.