POST
/
api
/
service
/
order
/
create
JavaScript
import Ivy from '@getivy/node-sdk';

const client = new Ivy({
  apiKey: 'My API Key',
});

const order = await client.orders.create({ amount: 0, currency: 'EUR', referenceId: 'referenceId' });

console.log(order.id);
{
  "id": "<string>",
  "merchantId": "<string>",
  "payerFinancialAddress": {
    "type": "iban",
    "iban": {
      "accountHolderName": "<string>",
      "iban": "<string>",
      "bic": "<string>"
    },
    "sortCode": {
      "accountHolderName": "<string>",
      "sortCode": "<string>",
      "accountNumber": "<string>"
    },
    "bankCode": {
      "accountHolderName": "<string>",
      "code": "<string>",
      "accountNumber": "<string>"
    },
    "bban": {
      "accountHolderName": "<string>",
      "bban": "<string>",
      "bic": "<string>"
    }
  },
  "appId": "<string>",
  "merchantAppId": "<string>",
  "shopName": "<string>",
  "referenceId": "<string>",
  "displayId": "<string>",
  "offsetProject": "<string>",
  "metadata": {},
  "category": "<string>",
  "co2Grams": 1,
  "applicationFeeAmount": 1,
  "price": {
    "total": 1.01,
    "currency": "EUR",
    "subTotal": 123,
    "shipping": 123,
    "totalNet": 123,
    "vat": 123
  },
  "lineItems": [
    {
      "name": "<string>",
      "referenceId": "<string>",
      "singleNet": 123,
      "singleVat": 123,
      "amount": 123,
      "quantity": 1,
      "image": "<string>",
      "category": "5045",
      "EAN": "<string>",
      "co2Grams": 1
    }
  ],
  "shopLogo": "<string>",
  "guest": false,
  "climateActionMode": {
    "type": "transaction",
    "amount": 123
  },
  "impactOffsetProjects": [
    "<any>"
  ],
  "billingAddress": {
    "firstName": "<string>",
    "lastName": "<string>",
    "line1": "<string>",
    "line2": "<string>",
    "region": "<string>",
    "city": "<string>",
    "zipCode": "<string>",
    "country": "AF"
  },
  "shippingAddress": {
    "firstName": "<string>",
    "lastName": "<string>",
    "line1": "<string>",
    "line2": "<string>",
    "region": "<string>",
    "city": "<string>",
    "zipCode": "<string>",
    "country": "AF"
  },
  "paymentStatus": "not_settled",
  "status": "failed",
  "refunds": [
    {
      "id": "<string>",
      "description": "<string>",
      "referenceId": "<string>",
      "transactionId": "<string>",
      "amount": 1,
      "status": "pending",
      "createdAt": "<any>",
      "updatedAt": "<any>"
    }
  ],
  "refundAmount": 1,
  "createdAt": "<any>",
  "updatedAt": "<any>",
  "shopperEmail": "<string>",
  "shopper": {
    "email": "<string>",
    "phoneNumber": "<string>"
  },
  "trees": 123,
  "merchantFinancialAddress": {
    "type": "iban",
    "iban": {
      "accountHolderName": "<string>",
      "iban": "<string>",
      "bic": "<string>"
    },
    "sortCode": {
      "accountHolderName": "<string>",
      "sortCode": "<string>",
      "accountNumber": "<string>"
    },
    "bankCode": {
      "accountHolderName": "<string>",
      "code": "<string>",
      "accountNumber": "<string>"
    },
    "bban": {
      "accountHolderName": "<string>",
      "bban": "<string>",
      "bic": "<string>"
    },
    "paymentReference": "<string>"
  },
  "bankStatementReference": "<string>",
  "destination": {
    "bankAccount": {
      "type": "iban",
      "iban": {
        "accountHolderName": "<string>",
        "iban": "<string>",
        "bic": "<string>"
      },
      "sortCode": {
        "accountHolderName": "<string>",
        "sortCode": "<string>",
        "accountNumber": "<string>"
      },
      "bankCode": {
        "accountHolderName": "<string>",
        "code": "<string>",
        "accountNumber": "<string>"
      },
      "bban": {
        "accountHolderName": "<string>",
        "bban": "<string>",
        "bic": "<string>"
      },
      "paymentReference": "<string>"
    },
    "bankStatementReference": "<string>"
  },
  "paymentMethodType": "sepa_debit",
  "setupPaymentMandate": true,
  "statusHistoryList": [
    {
      "previousStatus": "failed",
      "currentStatus": "failed",
      "reason": "ORDER_CREATED",
      "createdAt": "<any>",
      "updatedAt": "<any>"
    }
  ],
  "mandate": {
    "setup": false,
    "referenceId": "<string>",
    "accountHolderName": "<string>",
    "userNotificationEmail": "<string>",
    "additionalDisplayInformation": {
      "price": {
        "amount": 123,
        "currency": "EUR"
      },
      "cadence": "BI_WEEKLY"
    },
    "reference": "<string>",
    "creditor": {
      "name": "<string>",
      "id": "<string>"
    }
  },
  "subaccountId": "<string>",
  "subaccountLegalName": "<string>",
  "instantPaymentScheme": true,
  "statusClassification": {
    "primary": "payment_authorisation_failed",
    "secondary": "timeout"
  },
  "paymentMode": "direct",
  "customerId": "<string>",
  "bankId": "<string>",
  "transactionId": "<string>"
}

Authorizations

​
X-Ivy-Api-Key
string
header
required

API key for authentication

Body

application/json
​
amount
number
required

The total amount of the order

​
currency
enum<string>
required

The currency code of the order

Available options:
EUR,
GBP,
PLN,
SEK,
DKK
​
referenceId
string
required

The merchant's unique reference ID for the order

​
expiresAt
string

Optional expiration timestamp in seconds

​
customer
object

The customer of the merchant.

​
subaccountId
string

The subaccount id of the merchant.

Response

200 - application/json

Order created successfully

​
id
string
required

The unique id for the order.

​
merchantId
string
required
​
appId
string
required

The unique id for the merchantApp which initiated the order.

​
merchantAppId
string
required

Same as appId

​
shopName
string
required

The legal name of the merchant which initiated the order.

​
referenceId
string
required

A unique id for the order which can be set when creating the checkoutSession.

​
applicationFeeAmount
number
required

The amount of application fee collected with the order.

Required range: x > 0
​
price
object
required

The price object. All values in decimals, e.g. 0.13 for 13 cents.

​
status
enum<string>
required

The status of the order. As soon as this value is 'paid', you can ship the order.

Available options:
failed,
canceled,
processing,
waiting_for_payment,
paid,
in_refund,
refunded,
refund_failed,
partially_refunded,
in_dispute,
disputed,
refused,
finalizing
​
createdAt
any
required
​
updatedAt
any
required
​
instantPaymentScheme
boolean
required
​
payerFinancialAddress
object

The financial address of the payer associated with the order. Only available after successful PIS flow.

​
displayId
string

The customer-facing id of the order.

​
offsetProject
string

The project related to the order.

​
metadata
object

Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

​
category
string

The merchant category code for the account. MCCs are used to classify businesses based on the goods or services they provide.

​
co2Grams
number
Required range: x > 0
​
lineItems
object[]

The list of line items sold with the order.

​
guest
boolean
default:false
​
climateActionMode
object
​
impactOffsetProjects
any[]
​
billingAddress
object
​
shippingAddress
object
​
paymentStatus
enum<string>

Deprecated. The status of the payment.

Available options:
not_settled,
failed,
canceled,
processing,
requires_action,
succeeded,
in_refund,
refunded,
refund_failed,
partially_refunded,
disputed
​
refunds
object[]

All partial and total refunds of this order.

​
refundAmount
number

The total amount in the currency of all successful refunds for this order

Required range: x > 0
​
shopperEmail
string

Deprecated. The email of the customer who completed the order.

​
shopper
object

Information about the customer who finished the order.

​
trees
number
​
merchantFinancialAddress
object

The financial address of the merchant associated with the order. Only available when requested via order/details and therefore requires authentication.

​
bankStatementReference
string

The reference that will be shown on the bank statement of the customer. Only available after a successful DirectDebit initiation.

​
destination
object

The destination bank account and statement reference for the order.

​
paymentMethodType
enum<string>
Available options:
sepa_debit,
customer_balance,
manual_bank_transfer
​
setupPaymentMandate
boolean

If set to true, a payment mandate will be created for the user. This is currently in alpha and defaults to false.

​
statusHistoryList
object[]
​
mandate
object
​
subaccountId
string

The subaccount id of the merchant.

​
subaccountLegalName
string
​
statusClassification
object
​
paymentMode
enum<string>

The payment mode of the order. Can be either settlement or direct.

Available options:
direct,
settlement
​
customerId
string

The unique identifier of the customer who placed the order.

​
bankId
string

The unique identifier of the customer's bank.

​
transactionId
string

The unique id of the transaction.