# Create an order

This endpoint creates new orders, supporting both one-time purchases and recurring subscriptions.

Endpoint: POST /order
Version: 1.0
Security: Bearer

## Request fields (application/x-www-form-urlencoded):

  - `amount` (number, required)
    A string containing an exact monetary amount in the given currency. If you would want to charge €100.00 then you should provide 100.00.

  - `currency` (string, required)
    A three-character [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code.
    Example: "EUR"

  - `orderType` (string, required)
    Type of the order. Possible values are:
* purchase: One-off payment.
* recurring: A recurring order that will be billed automatically based on a defined interval. When using this type, the intervalType and intervalValue parameters are required.
* managed: Merchant-managed order; rebilling is initiated by the merchant on request.
* credit: Used for credit transactions or Original Credit Transactions (OCTs) / Card Funding Transactions (CFTs).
    Enum: "purchase", "recurring", "managed", "credit"

  - `customerId` (integer, required)
    The unique identifier for the customer.

  - `siteId` (integer)
    Unique identifier of your site profile. Mandatory if more than one site is configured.

  - `description` (string)
    Description of the goods or services included in the order.

  - `externalOrderId` (string)
    An external order identifier. This can be used to link the order with an external system.

  - `intervalType` (string)
    The type of recurring interval.
    Enum: "day", "month"

  - `intervalValue` (integer)
    The value of the recurring interval. For example, if intervalType is month and intervalValue is 3, the order will recur every 3 months.

  - `retryPayment` (string)
    A comma-separated list of ISO 8601 Durations representing retry intervals for failed payments. For example, PT1H,PT2H would retry once after 1 hour, and again after 2 hours. See [ISO 8601 Durations](https://en.wikipedia.org/wiki/ISO_8601#Durations) for more information.

  - `trialAmount` (number)
    The amount to be charged for the initial (trial) payment. This value is also used to validate and store the payment method.

  - `firstBillDate` (string)
    Use firstBillDate to specify the initial billing date when it differs from the regular recurring interval (defined by intervalValue). This is often used for trials. If firstBillDate is used, trialAmount must be greater than 0.
Use [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date, time and timezone offset.

  - `backUrl` (string)
    URL to which the cardholder will be redirected after completing a 3D Secure or digital wallet payment.
    Example: "https://myserver.com/callback/success-payment"

  - `transactionMethod` (string)
    Specifies the payment method for the transaction.  Possible values include:
* Card Payments (card): For card payments, provide one of the following:
  * Existing Card: The cardId of the stored card.
  * New Card: The following details for the new card: cardHolderName, cardHolderCountry, cardHolderState (required if the country is US or CA), cardNumber, cardExpiryDate, and cardCvv.

* Wallet Payments (wallet): For digital wallet transactions, use wallet and set the walletTransactionMode parameter to either transfer or credit.
    Enum: "card", "wallet"

  - `cardTransactionMode` (string)
    Specifies how the card transaction is processed.
* auth: Authorizes the card but does not capture the funds immediately.  This is useful for verifying card details and holding funds before completing the purchase.  A subsequent capture operation is required to settle the payment.
* authAndCapture: Authorizes and immediately captures the funds. This is the standard mode for most transactions where payment is collected at the time of purchase.
* credit: Processes a credit transaction (e.g., a refund or reversal).  This mode is used to credit funds back to the cardholder.
    Enum: "auth", "authAndCapture", "credit"

  - `cardId` (integer)
    The ID of a stored card belonging to the current customer.
    Example: 123

  - `cardNumber` (string)
    The card number (numbers only, no spaces).

  - `cardExpiryDate` (string)
    The card expiry date (MM/YY). For example: 12/28 or 05/26.

  - `cardCvv` (string)
    The card verification value (CVV). Three digits for Visa, Mastercard, Maestro; four digits for American Express.

  - `cardHolderName` (string)
    The cardholder's name.

  - `cardHolderCountry` (string)
    The cardholder's country. Use [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) codes (e.g., US).

  - `cardHolderState` (string)
    The cardholder's state (for US and CA only). Use two-letter [ISO 3166-2](https://en.wikipedia.org/wiki/ISO_3166-2) codes. For US, see [ISO 3166-2:US](https://en.wikipedia.org/wiki/ISO_3166-2:US) (e.g., NY). For CA, see [ISO 3166-2:CA](https://en.wikipedia.org/wiki/ISO_3166-2:CA) (e.g., ON).

  - `saveCard` (boolean)
    Indicates whether to save the card information for future use.

  - `invoiceEmail` (string)
    The email address to which the invoice will be sent.

  - `ip` (string)
    Customer's IP address (ipv4 or ipv6)

  - `threeDSecureData` (string)
    Base64 encoded JSON object containing 3D Secure version 2 data, such as browser information and billing/shipping addresses.  For details, see the 3-D Secure – Protocol and Core Functions Specification on the [EMVCo website](https://www.emvco.com/document-search/?action=search_documents&publish_date=&emvco_document_version=&emvco_document_book=&px_search=&emvco_document_technology%5B0%5D=3-d-secure&sort=publish_date&sort_order=DESC).

  - `externalCustomData` (string)
    Custom data that will be passed back in the IPN callback. This field is not validated and can be used to send additional information. For complex data, use a JSON-encoded string.

  - `level3Data` (string)
    Detailed information (JSON format) about items, tickets, etc. Refer to the API documentation for details

  - `transactionOption` (object)
    JSON-encoded parameters used to pass optional flags.

  - `transactionOption.digitalWallet` (object)
    Encrypted Apple Pay or Google Pay wallet token that xMoney decrypts before authorization. If you already decrypted the wallet payload, send the top-level POST /order digitalWalletType and digitalWallet* fields instead.

  - `transactionOption.digitalWallet.walletType` (any, required)
    Wallet brand for the encrypted token.
    Enum: "googlePay", "applePay"

  - `transactionOption.digitalWallet.data` (string, required)
    Encrypted wallet token payload, usually Base64 encoded.

  - `transactionOption.isSoftDecline` (any)
    Enum: "yes", "no"

  - `transactionOption.subMerchantId` (string)

  - `transactionOption.splitPayment` (object)

  - `transactionOption.splitPayment.splitSchema` (array, required)

  - `transactionOption.splitPayment.splitSchema.toSite` (integer, required)

  - `transactionOption.splitPayment.splitSchema.amount` (number, required)

  - `transactionOption.splitPayment.splitSchema.description` (string)

  - `transactionOption.splitPayment.splitSchema.tag` (array)

  - `digitalWalletType` (string)
    Use this field when your integration sends an already-decrypted Apple Pay or Google Pay payment network payload directly in the order request. When this field is present, xMoney does not decrypt transactionOption.digitalWallet; send the decrypted card details with cardNumber and cardExpiryDate, and send the wallet payload details with the digitalWallet* fields.
    Enum: same as `transactionOption.digitalWallet.walletType` (2 values)

  - `digitalWalletCryptogram` (string)
    Cryptogram from the decrypted wallet payload. For Google Pay, this is the payment method cryptogram. For Apple Pay, this is the online payment cryptogram from the payment data.
    Example: "AgAAAAAAAIR8CQrXcIhbQAAAAAA="

  - `digitalWalletEci` (string)
    Electronic Commerce Indicator from the decrypted wallet payload.
    Example: "05"

  - `digitalWalletRawData` (string)
    JSON string containing the decrypted external payment network payload. This field is required when digitalWalletType is provided.
    Example: "{\"paymentMethodDetails\":{\"pan\":\"4111111111111111\"}}"

  - `digitalWalletProtocolVersion` (string)
    Wallet protocol version from the external payment payload. For Google Pay, this is typically ECv2.
    Example: "ECv2"

  - `networkTokenType` (string)
    Network token scheme or token service provider. When this field is present, xMoney treats the payment as a network token payment. Send the DPAN in networkToken and the token expiry in cardExpiryDate. Do not combine network token payments with cardId.
    Enum: "MDES", "VTS", "APPLE", "GOOGLE", "SAMSUNG"

  - `networkToken` (string)
    Network token value, also known as the DPAN. Spaces and dashes are ignored. Required when networkTokenType is provided.
    Example: "4111111111111111"

  - `networkTokenCryptogram` (string)
    Token cryptogram associated with the network token. TAVV and DSRP cryptograms are sent in this field when supplied by the token service provider or wallet.
    Example: "AgAAAAAAAIR8CQrXcIhbQAAAAAA="

  - `networkTokenEci` (string)
    Electronic Commerce Indicator associated with the network token.
    Example: "05"

  - `networkTransactionId` (string)
    Optional scheme network transaction identifier from the original transaction. xMoney handles this internally for standard xMoney tokenized payments. Send this field only when tokenization happens outside xMoney and your integration needs to provide the original scheme reference for stored-credential or merchant-initiated transaction chaining. If this field is provided, networkTransactionDate is also required.
    Example: "123456789012345"

  - `networkTransactionDate` (string)
    Optional date of the original network transaction, represented as a Unix timestamp in milliseconds. Send this field only together with networkTransactionId for external-tokenization merchant-initiated flows. If this field is provided, networkTransactionId is also required.
    Example: "1717070400000"

  - `eci` (string)
    Electronic Commerce Indicator returned by the 3-D Secure authentication process. It indicates the authentication result and liability shift status for the card transaction.
    Example: "01"

  - `cavv` (string)
    Cardholder Authentication Verification Value generated during 3-D Secure authentication. This value is provided by the issuer or ACS and should be submitted with the payment authorization request when available.
    Example: "/HftVQ7ns+gLAnGoYJW_LYwBuqBs+CfPqSXiFuuNMQm2m-DVD7PDiOlE/e2zP91EsA3bB9UD9hukOwPp9mF-Pklk72+06-ZlI/"

  - `xid` (string)
    Transaction identifier associated with the 3-D Secure authentication session. For 3-D Secure 1, this is typically the XID value. For 3-D Secure 2, this may be used as a transaction/session correlation identifier depending on the provider.
    Example: "/27870b3a-5b13-3e62-7ef1-d78c473452f4/i"

  - `threeDSProtocolVersion` (string)
    Version of the 3-D Secure protocol used for the authentication flow. For example, 2.2.0.
    Example: "2.1.0"

  - `threeDsType` (string)
    Type of 3-D Secure authentication flow or result classification, as provided by the payment gateway or 3-D Secure provider. The accepted values depend on the provider integration.
    Example: "0"

## Response 201 fields (application/json):

  - `code` (integer, required)

  - `message` (string, required)

  - `data` (object)

  - `data.orderId` (integer, required)

  - `data.transactionId` (integer, required)

  - `data.cardId` (integer)
    The id of the card if one was saved

  - `data.is3d` (integer)
    Enum: 0, 1

  - `data.isRedirect` (boolean)

  - `data.redirect` (object)
    This object will be available only if is3d = 1

  - `data.redirect.url` (string, required)
    Url of the ACS

  - `data.redirect.params` (object, required)
    Key value pair of parameters that need to be send (using 'formMethod' method) to the ACS url

  - `data.redirect.formMethod` (string)
    Enum: "POST", "GET"

## Response 402 fields (application/json):

  - `code` (integer, required)

  - `message` (string, required)

  - `data` (object)

  - `data.orderId` (integer, required)

  - `data.transactionId` (integer)

  - `error` (array)

  - `error.code` (integer)
    System error code.

  - `error.message` (string)
    System error message.

  - `error.type` (string)
    System error type.
    Enum: "Exception", "Validation"

  - `error.field` (string)
    Field name that caused the error.