Create Order

POST 
/orders

Enables you to create a new merchant order.

Request

Header Parameters

idempotency-key string
Idempotency Key for the request
Example: 31f9952c-0058-458b-8244-4ae110ef1556

application/json

Body

processingEntityId uuidrequired

Processing entityId provided by Nuvei.

merchantTransactionId string

ID of the transaction in the merchant system.

Possible values: <= 45 characters

productId string

A free text parameter used to identify the product/service sold. If this parameter is not sent or is sent with an empty value, then it contains the concatenation of all item names up until the parameter maximum length. Risk rules and traffic management rules are usually built based on this parameter value.

Possible values: <= 50 characters

currencyConversion

object

type stringrequired

The type of the currency conversion.

Possible values: [MCP]

originalAmount numberrequired

The original amount of the transaction in the currency that the merchant requested.

originalCurrency stringrequired

The 3-letter ISO currency code of the currency that the merchant requested in the transaction.

Possible values: >= 3 characters and <= 3 characters

amount numberrequired

The transaction amount.

currency stringrequired

The 3-letter ISO currency code.

Possible values: >= 3 characters and <= 3 characters

transactionType PaymentTransactionType (string)

The type of transaction.

Possible values: [Auth, PreAuth, Sale]

isMoto boolean

Indicates whether the transaction was done over email/phone or is a regular transaction. Values: true = Moto transaction | false = no Moto Transaction

isPartialApproval boolean

Describes a situation where the deposit was completed and processed with an amount lower than the requested amount due to a consumer's lack of funds within the desired payment method. Partial approval is only supported by Nuvei acquiring. Values: true - Allow partial approval | false - Not allow partial approval

zeroAmountReason string

For Authentication Zero scenarios, this optional field defines the authentication type.

Possible values: [recurring, installments, addCard, maintainCard, accountVerification]

amountDetails

object

totalDiscount number

Amount of discount applied.

Default value: 0

totalHandling number

Amount of handling.

Default value: 0

totalShipping number

Amount of freight or shipping.

Default value: 0

totalTax number

Total tax amount.

Default value: 0

items

object[]

Array [

name stringrequired

price numberrequired

quantity integerrequired

]

dynamicDescriptor

object

merchantName string

The merchant name, as is displayed for the transaction on the consumer's card statement.

Possible values: <= 25 characters

merchantContactInformation string

The merchant contact information, as is displayed for the transaction on the consumer's card statement. It can also be an email address.

Possible values: <= 255 characters

subMerchant

object

id string

Represents the internal merchant’s ID, which is forwarded to Visa and Mastercard

Possible values: <= 15 characters

city string

The payment facilitator’s sub-merchant’s city name.

Possible values: <= 20 characters

countryCode string

The payment facilitator’s sub-merchant’s 2-letter ISO country code.

Possible values: >= 2 characters and <= 2 characters

urlDetails

object

With this class, a merchant can dynamically provide possible URLs to which the end user is redirected after a payment is made, as well as a dynamic URL for DMNs.

webhookUrl string

The URL to which notifications for outcome of the financial transactions is sent.

successUrl string

The URL to which the end user is redirected in case of a successful transaction with an APM.

failureUrl string

The URL to which the end user is redirected in case of an unsuccessful transaction with an APM.

pendingUrl string

The URL to which the end user is redirected in case of a pending transaction with an APM.

rebill

object

expiry date

Recurring Expiry in the format: YYYYMMDD. REQUIRED if step = init. We recommend setting expiry to a value of no more than 5 years from the date of the initial transaction processing date

frequency integer

Recurring Frequency in days. REQUIRED if step = init.

step string

Indicates the type of transaction performed as part of a rebilling plan.

Possible values: [init, recurring, MIT]

deviceDetails

object

deviceName string

deviceOS string

deviceType string

Supported device types include: DESKTOP, SMARTPHONE, TABLET, TV, UNKNOWN (if device type cannot be recognized).

ipAddress string

The customer's IP address.

browser

object

acceptHeader string

Exact content of the HTTP accept headers as sent to the 3DS Requestor from the cardholder's browser. If the total length of the accept header sent by the browser exceeds 2048 characters, the 3D-Secure Server truncates the excess portion.

colorDepth integer

Value representing the bit depth of the color palette for displaying images, in bits per pixel. Obtained from cardholder browser using the screen.colorDepth property. Values: 1, 4, 8, 15, 16, 24, 32, 48

javaEnabled boolean

Represents the ability of the cardholder browser to execute Java. REQUIRED when javaScriptEnabled is TRUE. Value is returned from the navigator.javaEnabled property. Values: TRUE, FALSE

javaScriptEnabled boolean

Determines whether the browser is JavaScript enabled (from navigator.javaScriptEnabled property). Values: TRUE, FALSE

language string

Value representing the browser language as defined in IETF BCP47. Returned from navigator.language property.

screenHeight integer

Total height of the cardholder's screen in pixels. Value is returned from the screen.height property.

screenWidth integer

Total width of the cardholder's screen in pixels. Value is returned from the screen.width property.

timeZone string

Time difference between UTC time and the cardholder browser local time, in minutes. The value is returned from the getTimezoneOffset() method.

userAgent string

Exact content of the HTTP user-agent header. If the total length of the user-agent header sent by the browser exceeds 2048 characters, the 3D-Secure Server truncates the excess portion.

custom

object

property name* password

buyerDetails

object

buyerId string

Possible values: <= 255 characters

firstName string

Possible values: <= 30 characters

lastName string

Possible values: <= 40 characters

companyName string

Possible values: <= 100 characters

locale string

The user's locale and default language.

Possible values: <= 5 characters

dateOfBirth date

Format is YYYY-MM-DD.

email string

Possible values: <= 100 characters

phone string

Possible values: <= 18 characters

phone2 string

Possible values: <= 18 characters

workPhone string

Possible values: <= 18 characters

nationalIdentificationNumber password

The user's national ID number.

Possible values: <= 25 characters

billingAddress

object

address string

Possible values: <= 60 characters

addressLine2 string

Possible values: <= 60 characters

addressLine3 string

Possible values: <= 60 characters

state string

ISO county/province/state/territory/union territory code

Possible values: <= 6 characters

zip string

Possible values: <= 10 characters

city string

Possible values: <= 30 characters

countryCode stringrequired

The 2-letter ISO country code.

Possible values: >= 2 characters and <= 2 characters

phone string

Possible values: <= 18 characters

addressMatch boolean

Set to “true” when address matches shipping address.

Default value: false

shippingAddress

object

sameAsBilling boolean

Default value: false

address string

Possible values: <= 60 characters

addressLine2 string

Possible values: <= 60 characters

addressLine3 string

Possible values: <= 60 characters

state string

ISO county/province/state/territory/union territory code

Possible values: <= 6 characters

zip string

Possible values: <= 10 characters

city string

Possible values: <= 30 characters

countryCode string

The 2-letter ISO country code.

Possible values: >= 2 characters and <= 2 characters

firstName string

Possible values: <= 30 characters

lastName string

Possible values: <= 40 characters

phone string

Possible values: <= 18 characters

phone2 string

Possible values: <= 18 characters

permittedOperations PermittedOperation (string)[]required

Array of operations that are allowed for this order. Must be any combination of payment, settle, refund and void.

Possible values: [payments, operations], >= 1

uiConfig

object

property name* password
storePaymentOption PaymentTokenStorageOption (string)

Possible values: [none, tokenOnly, buyerToken]

preventOverride preventOverride (string)[]

An array of fields that cannot be overridden on the order.

Possible values: >= 1

openAmount

object

Object for providing minimum and maximum amounts for open amount functionality.

min numberrequired

max numberrequired

Responses

201

OK

application/json

Schema

Schema

sessionId string
A temporary access token that can be used to perform an action on an order.
Example: sid_4980d755d3f64304a0cbf9b0778faff8

result

object

required

status stringrequired

The transaction status.

Possible values: [error, success, pending]

errors

object

code string

If an error occurred on the request side, an error code is returned in this parameter.

Possible values: <= 11 characters

Example: 7000.1000

reason string

If an error occurred on the request side, then an error reason is returned in this parameter.

Possible values: <= 400 characters

Example: Internal Processing Error

Example (from schema)

{
  "sessionId": "sid_4980d755d3f64304a0cbf9b0778faff8",
  "result": {
    "status": "error",
    "errors": {
      "code": "7000.1000",
      "reason": "Internal Processing Error"
    }
  }
}

Example

{
  "sessionId": "sid_4980d755d3f64304a0cbf9b0778faff8",
  "result": {
    "status": "success"
  }
}

400

Bad Request

application/json

Schema

Schema

sessionId string
A temporary access token that can be used to perform an action on an order.
Example: sid_4980d755d3f64304a0cbf9b0778faff8

result

object

required

status stringrequired

The transaction status.

Possible values: [error, success, pending]

errors

object

code string

If an error occurred on the request side, an error code is returned in this parameter.

Possible values: <= 11 characters

Example: 7000.1000

reason string

If an error occurred on the request side, then an error reason is returned in this parameter.

Possible values: <= 400 characters

Example: Internal Processing Error

Example (from schema)

{
  "sessionId": "sid_4980d755d3f64304a0cbf9b0778faff8",
  "result": {
    "status": "error",
    "errors": {
      "code": "7000.1000",
      "reason": "Internal Processing Error"
    }
  }
}

Example

{
  "result": {
    "status": "error",
    "errors": {
      "code": "5000.1000",
      "reason": "[processingEntityId] must not be null"
    }
  }
}

401

Unauthorized

application/json

Schema

Schema

sessionId string
A temporary access token that can be used to perform an action on an order.
Example: sid_4980d755d3f64304a0cbf9b0778faff8

result

object

required

status stringrequired

The transaction status.

Possible values: [error, success, pending]

errors

object

code string

If an error occurred on the request side, an error code is returned in this parameter.

Possible values: <= 11 characters

Example: 7000.1000

reason string

If an error occurred on the request side, then an error reason is returned in this parameter.

Possible values: <= 400 characters

Example: Internal Processing Error

Example (from schema)

{
  "sessionId": "sid_4980d755d3f64304a0cbf9b0778faff8",
  "result": {
    "status": "error",
    "errors": {
      "code": "7000.1000",
      "reason": "Internal Processing Error"
    }
  }
}

Example

{
  "result": {
    "status": "error",
    "errors": {
      "code": "7300.3000",
      "reason": "Authorization error"
    }
  }
}

403

Forbidden

application/json

Schema

Schema

sessionId string
A temporary access token that can be used to perform an action on an order.
Example: sid_4980d755d3f64304a0cbf9b0778faff8

result

object

required

status stringrequired

The transaction status.

Possible values: [error, success, pending]

errors

object

code string

If an error occurred on the request side, an error code is returned in this parameter.

Possible values: <= 11 characters

Example: 7000.1000

reason string

If an error occurred on the request side, then an error reason is returned in this parameter.

Possible values: <= 400 characters

Example: Internal Processing Error

Example (from schema)

{
  "sessionId": "sid_4980d755d3f64304a0cbf9b0778faff8",
  "result": {
    "status": "error",
    "errors": {
      "code": "7000.1000",
      "reason": "Internal Processing Error"
    }
  }
}

Example

{
  "result": {
    "status": "error",
    "errors": {
      "code": "7300.3000",
      "reason": "Authorization error"
    }
  }
}

500

Internal Server Error

application/json

Schema

Schema

sessionId string
A temporary access token that can be used to perform an action on an order.
Example: sid_4980d755d3f64304a0cbf9b0778faff8

result

object

required

status stringrequired

The transaction status.

Possible values: [error, success, pending]

errors

object

code string

If an error occurred on the request side, an error code is returned in this parameter.

Possible values: <= 11 characters

Example: 7000.1000

reason string

If an error occurred on the request side, then an error reason is returned in this parameter.

Possible values: <= 400 characters

Example: Internal Processing Error

Example (from schema)

{
  "sessionId": "sid_4980d755d3f64304a0cbf9b0778faff8",
  "result": {
    "status": "error",
    "errors": {
      "code": "7000.1000",
      "reason": "Internal Processing Error"
    }
  }
}

Example

{
  "result": {
    "status": "error",
    "errors": {
      "code": "7000.1000",
      "reason": "Internal system error"
    }
  }
}

Loading...