# Create single payment

Creates a Single Payment

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

## Request fields (application/json):

  - `type` (string)
    Specifies the type of financial operation being performed. 

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

  - `capture` (object)
    The Capture object contains all the necessary information for executing a fund capture action. It defines how and where the funds should be routed upon capturing a transaction. This object is essential for finalizing transactions and ensuring the correct allocation of funds. Object required when the operation type is Sale.

  - `capture.descriptive` (string, required)
    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"

  - `capture.transaction_key` (string)
    A customizable text field for users to input their own identifier for the resource. This can be any string that helps the user uniquely identify or reference the resource in their own system.
    Example: "231d0464-6382-4e39-9a1f-af82ea166868"

  - `capture.account` (object)
    An object within the capture request that specifies the details of the account to which the funds should be routed, different from the initially requested account. This ensures that the captured funds are directed to the correct destination as per the specific routing requirements.

  - `capture.account.id` (string, required)
    The unique identifier of the account where the captured funds will be routed. This ID corresponds to an existing account in the system and is used to specify the destination for the capture transaction.

  - `capture.capture_date` (string)
    The date when the action should be executed. This field specifies the exact day for capturing the transaction, formatted as "YYYY-MM-DD" (e.g., "2024-06-30"). It is optional and defaults to the current date if not specified.
    Example: "2024-06-30"

  - `capture.splits` (array)
    An array of split objects defining how funds should be divided among multiple accounts. Each split specifies an account, an amount, and optional margin details. This is useful for marketplace or multi-vendor scenarios where transaction proceeds need to be distributed across different parties.

  - `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"

  - `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"

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

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

  - `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

  - `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"

  - `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.

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

  - `currency` (string)
    ISO 4217 currency code. If not specified, the default currency is set to EUR.
    Example: "EUR"

  - `method` (string, required)
    Enumerates the possible values for the payment method used in the transaction. This field helps to identify the selected payment method. Possible values include:

METHOD   | DESCRIPTION     |
---------|-----------------|
 CC      | Credit Card     |
 VI      | Digital IBAN    |
 DD      | Direct Debit    |
 MB      | Multibanco      |
 MBW     | MBWay           |
 GP      | Google Pay*     |
 AP      | Apple Pay*      |
 SW      | Samsung Wallet* |

*payment only available through checkout yet
    Enum: "CC", "VI", "DD", "MB", "MBW", "GP", "AP", "SW"

  - `key` (string)
    A customizable text field for users to input their own identifier for the resource. This can be any string that helps the user uniquely identify or reference the resource in their own system.
    Example: "Payment of Invoice Nº 1982652"

  - `customer` (object)
    The Customer object contains the necessary details about the customer involved in the transaction. This includes identification information, contact details, and preferences. All fields are optional unless specified otherwise.

  - `customer.id` (string)
    Unique identifier for the customer. When provided, it links the transaction to an existing customer record.
    Example: "649e88cf-0b78-4c36-8f99-33f5ebb812a1"

  - `customer.name` (string)
    Full name of the customer. This is typically displayed on receipts and statements.
    Example: "John Doe"

  - `customer.email` (string)
    Customer's email address. Used for sending receipts, notifications, and payment confirmations.
    Example: "john.doe@example.com"

  - `customer.phone` (string)
    The contact phone number of the customer, excluding the country code indicator (e.g., "+351"). This field is used for communication purposes. If the payment method is MBWAY, the phone_number is required and is used to send the MBWAY push notification.
    Example: "911234567"

  - `customer.phone_indicative` (string)
    The country code indicator for the customer's phone number (e.g., "351" for Portugal). This field is used in conjunction with the phone number to ensure proper international dialing and communication.
    Example: "+351"

  - `customer.fiscal_number` (string)
    Customer's tax identification number or fiscal number. Format may vary by country.
    Example: "PT123456789"

  - `customer.key` (string)
    A customizable text field for users to input their own identifier for the customer. This can be any string that helps the user uniquely identify the customer in their own system.
    Example: "customer Key Example"

  - `customer.language` (string)
    Preferred language for customer communications. Uses ISO 639-1 language codes.
    Enum: "PT", "EN", "ES"

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

  - `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").

  - `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.

  - `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"

  - `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.

  - `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"

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

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

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

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

  - `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"

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

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

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

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

  - `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

  - `expiration_time` (string)
    The last possible time to make the payment. Applicable in Multibanco payments. This field is deprecated, use multibanco.expiration_time instead.
    Example: "2017-12-12 16:05"

## Response 201 fields (application/json):

  - `status` (string)
    Indicates the overall status of the API response. 'ok' means the request was successful, 'error' indicates there was a problem.
    Enum: "ok", "error"

  - `message` (array)
    An array of messages providing details about the response status. These messages give additional context about the operation result.

  - `id` (string)
    Example: "c6056234-a3f9-42de-b944-3ed793fcb6bb"

  - `method` (object)
    Method information returned in POST responses after creating a payment

  - `method.type` (string)
    The payment method type
    Enum: "mb", "cc", "dd", "mbw", "vi", "ap", "gp", "sw"

  - `method.status` (string)
    The current status of the payment method
    Enum: "waiting", "pending", "active", "deleted", "success"

  - `method.entity` (string)
    Multibanco entity (for Multibanco payments)
    Example: "59126"

  - `method.reference` (string)
    Multibanco reference (for Multibanco payments)
    Example: "810000618"

  - `method.expiration_date` (string)
    Expiration date of the payment method formatted as MM/DD
    Example: "11/28"

  - `method.url` (string)
    Payment URL (for certain payment methods)

  - `method.sdd_mandate` (object)
    SDD Mandate information as returned in detail responses

  - `method.sdd_mandate.id` (string)
    Mandate ID
    Example: "50389142122"

  - `method.sdd_mandate.iban` (string)
    International Bank Account Number (IBAN) in standard format

  - `method.sdd_mandate.key` (string)
    Mandate key
    Example: "Sdd mandate Key Example"

  - `method.sdd_mandate.name` (string)
    Account holder name
    Example: "John Doe"

  - `method.sdd_mandate.email` (string)
    Account holder email
    Example: "john.doe@easypay.pt"

  - `method.sdd_mandate.phone` (string)
    Account holder phone
    Example: "911345678"

  - `method.sdd_mandate.account_holder` (string)
    Account holder name as registered with bank
    Example: "John Doe"

  - `method.sdd_mandate.country_code` (string)
    Country code
    Example: "PT"

  - `method.sdd_mandate.max_num_debits` (string)
    Maximum number of debits allowed
    Example: "12"

  - `method.sdd_mandate.billing_entity` (string)
    Billing entity identifier
    Example: "PT16103627"

  - `method.sdd_mandate.reference_adc` (string)
    Example: "987654321123"

  - `customer` (object)

  - `capture` (object)

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

  - `multibanco.expiration_time` (string,null)
    When the Multibanco reference expires
    Example: "2025-09-28T12:41:08Z"

  - `multibanco.start_time` (string)
    When the Multibanco reference becomes valid
    Example: "2025-08-26T12:41:09Z"

  - `multibanco.product` (string)
    The Multibanco product type used
    Enum: "SPG", "CHECKDIGIT", "FILE"

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

  - `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

## 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 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 409 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 412 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.