Create an Order

POST

api

service

order

create

curl --request POST \
  --url https://api.sand.getivy.de/api/service/order/create \
  --header 'Content-Type: application/json' \
  --header 'X-Ivy-Api-Key: <api-key>' \
  --data '{
  "amount": 123,
  "currency": "EUR",
  "referenceId": "<string>",
  "expiresAt": "<string>",
  "customer": {
    "email": "jsmith@example.com"
  },
  "subaccountId": "<string>"
}'

{
  "id": "<string>",
  "payerFinancialAddress": {
    "type": "<string>",
    "iban": {
      "iban": "<string>",
      "bic": "<string>",
      "accountHolderName": "<string>"
    },
    "sortCode": {
      "sortCode": "<string>",
      "accountNumber": "<string>",
      "accountHolderName": "<string>"
    },
    "bankCode": {
      "code": "<string>",
      "accountNumber": "<string>",
      "accountHolderName": "<string>"
    },
    "bban": {
      "bban": "<string>",
      "accountHolderName": "<string>",
      "bic": "<string>"
    }
  },
  "merchantId": "<string>",
  "appId": "<string>",
  "merchantAppId": "<string>",
  "shopperEmail": "<string>",
  "shopper": {
    "email": "<string>",
    "phoneNumber": "<string>"
  },
  "shopName": "<string>",
  "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"
  },
  "referenceId": "<string>",
  "metadata": {},
  "category": "<string>",
  "applicationFeeAmount": 123,
  "price": {
    "total": 123,
    "currency": "EUR",
    "subTotal": 123,
    "shipping": 123,
    "totalNet": 123,
    "vat": 123
  },
  "co2Grams": 123,
  "trees": 123,
  "lineItems": [
    {
      "name": "<string>",
      "referenceId": "<string>",
      "singleNet": 123,
      "singleVat": 123,
      "amount": 123,
      "quantity": 123,
      "image": "<string>",
      "category": "<string>",
      "EAN": "<string>"
    }
  ],
  "shopLogo": "<string>",
  "incentiveMode": "white_label",
  "guest": true,
  "climateActionMode": {
    "type": "transaction",
    "amount": 123
  },
  "impactOffsetProjects": [
    "<string>"
  ],
  "shippingMethod": {
    "id": "<string>",
    "price": 123,
    "name": "<string>",
    "countries": [
      "AF"
    ],
    "reference": "<string>",
    "timeFrame": "<string>",
    "deliveryEstimate": {
      "minimum": {
        "unit": "hour",
        "value": 123
      },
      "maximum": {
        "unit": "hour",
        "value": 123
      }
    }
  },
  "paymentStatus": "failed",
  "status": "failed",
  "refunds": [
    {
      "id": "<string>",
      "description": "<string>",
      "referenceId": "<string>",
      "amount": 123,
      "status": "pending",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z"
    }
  ],
  "refundAmount": 123,
  "offsetProject": "<string>",
  "displayId": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "merchantFinancialAddress": {
    "type": "<string>",
    "iban": {
      "iban": "<string>",
      "bic": "<string>",
      "accountHolderName": "<string>"
    },
    "sortCode": {
      "sortCode": "<string>",
      "accountNumber": "<string>",
      "accountHolderName": "<string>"
    },
    "bankCode": {
      "code": "<string>",
      "accountNumber": "<string>",
      "accountHolderName": "<string>"
    },
    "bban": {
      "bban": "<string>",
      "accountHolderName": "<string>",
      "bic": "<string>"
    },
    "paymentReference": "<string>"
  },
  "bankStatementReference": "<string>",
  "destination": {
    "bankAccount": {
      "type": "<string>",
      "iban": {
        "iban": "<string>",
        "bic": "<string>",
        "accountHolderName": "<string>"
      },
      "sortCode": {
        "sortCode": "<string>",
        "accountNumber": "<string>",
        "accountHolderName": "<string>"
      },
      "bankCode": {
        "code": "<string>",
        "accountNumber": "<string>",
        "accountHolderName": "<string>"
      },
      "bban": {
        "bban": "<string>",
        "accountHolderName": "<string>",
        "bic": "<string>"
      }
    },
    "bankStatementReference": "<string>"
  },
  "statusHistoryList": [
    {
      "previousStatus": "failed",
      "currentStatus": "failed",
      "reason": "<string>",
      "updatedAt": "2023-11-07T05:31:56Z"
    }
  ],
  "paymentMethodType": "sepa_debit",
  "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>",
  "instantPaymentScheme": true,
  "statusClassification": {
    "primary": "<string>",
    "secondary": "<string>"
  },
  "subaccountLegalName": "<string>",
  "paymentMode": "settlement",
  "customerId": "<string>",
  "bankId": "<string>"
}

Authorizations

X-Ivy-Api-Key

string

header

required

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

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

Returns the order

string

required

The Ivy unique identifier for the order.

merchantId

string

required

The unique identifier for the merchant which initiated the order / payment attempt.

appId

string

required

deprecated

The unique identifier for the merchantApp which initiated the order / payment attempt.

merchantAppId

string

required

deprecated

Deprecated in favor of appId.

shopName

string

required

The name of the merchant which initiated the order.

referenceId

string

required

An internal reference id which will be stored with the checkout & corresponding order. Needs to be unique per shop per order and can be up to 200 characters.

Maximum length: 200

applicationFeeAmount

number

required

The Ivy fee for the payment.

price

object

required

The amount to be paid by the user. The amounts is in decimals, i.e. 10.23 represents EUR 10.23. Any amount of decimal places can be provided on initialization, but the actual transfer amount is rounded to 2 decimal places, as this is the format accepted by most banks.

status

enum<string>

required

The order status. This status symbolises the state of the user's payment attempt. See the guide for more information.

Available options:

failed,

canceled,

processing,

waiting_for_payment,

paid,

in_refund,

refunded,

refund_failed,

partially_refunded,

in_dispute,

disputed,

refused

createdAt

string

required

updatedAt

string

required

instantPaymentScheme

boolean

required

payerFinancialAddress

object

The source bank account where the money is send from.

shopperEmail

string

deprecated

Deprecated in favor of shopper.email. The email of the user if collected in the Checkout.

shopper

object

The shopper object. Contains information collected from the user during the Checkout.

billingAddress

object

The billing address of the user. Required when handshake=true.

shippingAddress

object

The shipping address of the user. This is only collected in express Checkouts.

metadata

object

Any data which will be stored and returned for this checkout session and corresponding order. See here for more info.

category

string

The merchant category code or MCC.

co2Grams

number

deprecated

trees

number

deprecated

lineItems

object[]

The line items of the Checkout.

shopLogo

string

The logo of the shop provided as a URL.

incentiveMode

enum<string>

default:white_label

The incentive mode of the checkout session. For any use-case apart from e-commerce, please use white_label as the value. If set to white_label, the checkout session will be white labeled. If set to sustainable, the checkout session will contain sustainable incentives for users.

Available options:

white_label,

sustainable

guest

boolean

False by default. If set to true, customers skip email input and jump directly to their bank login. For express Checkout Sessions this is always false.

climateActionMode

object

impactOffsetProjects

string[]

Only valid for sustainable incentive mode. The social / sustainable projects available to the user during Checkout.

shippingMethod

object

The selected shipping method by the user. Can either be selected during an express Checkout Session or passed during Checkout Session creation.

shippingMethod.price

number

required

The price of the shipping method in decimals, i.e. 10.23 represents EUR 10.23.

shippingMethod.name

string

required

The customer-facing name of the shipping method.

shippingMethod.id

string

The unique identifier of the shipping method within Ivy.

shippingMethod.countries

enum<string>[]

The list of countries where the shipping method is available.

Available options:

AF,

AL,

DZ,

AS,

AD,

AO,

AI,

AQ,

AG,

AR,

AM,

AW,

AU,

AT,

AZ,

BS,

BH,

BD,

BB,

BY,

BE,

BZ,

BJ,

BM,

BT,

BO,

BA,

BW,

BV,

BR,

IO,

BN,

BG,

BF,

BI,

KH,

CM,

CA,

CV,

KY,

CF,

TD,

CL,

CN,

CX,

CC,

CO,

KM,

CG,

CD,

CK,

CR,

CI,

HR,

CU,

CY,

CZ,

DK,

DJ,

DM,

DO,

EC,

EG,

SV,

GQ,

ER,

EE,

ET,

FK,

FO,

FJ,

FI,

FR,

GF,

PF,

TF,

GA,

GM,

GE,

DE,

GH,

GI,

GR,

GL,

GD,

GP,

GU,

GT,

GN,

GW,

GY,

HT,

HM,

VA,

HN,

HK,

HU,

IS,

IN,

ID,

IR,

IQ,

IE,

IL,

IT,

JM,

JP,

JO,

KZ,

KE,

KI,

KP,

KR,

KW,

KG,

LA,

LV,

LB,

LS,

LR,

LY,

LI,

LT,

LU,

MO,

MG,

MW,

MY,

MV,

ML,

MT,

MH,

MQ,

MR,

MU,

YT,

MX,

FM,

MD,

MC,

MN,

MS,

MA,

MZ,

MM,

NA,

NR,

NP,

NL,

NC,

NZ,

NI,

NE,

NG,

NU,

NF,

MP,

MK,

NO,

OM,

PK,

PW,

PS,

PA,

PG,

PY,

PE,

PH,

PN,

PL,

PT,

PR,

QA,

RE,

RO,

RU,

RW,

SH,

KN,

LC,

PM,

VC,

WS,

SM,

ST,

SA,

SN,

SC,

SL,

SG,

SK,

SI,

SB,

SO,

ZA,

GS,

ES,

LK,

SD,

SR,

SJ,

SZ,

SE,

CH,

SY,

TW,

TJ,

TZ,

TH,

TL,

TG,

TK,

TO,

TT,

TN,

TR,

TM,

TC,

TV,

UG,

UA,

AE,

GB,

US,

UM,

UY,

UZ,

VU,

VE,

VN,

VG,

VI,

WF,

EH,

YE,

ZM,

ZW,

AX,

BQ,

CW,

GG,

IM,

JE,

ME,

BL,

MF,

RS,

SX,

SS,

XK

shippingMethod.reference

string

The unique identifier within your system of the shipping method.

shippingMethod.timeFrame

string

deprecated

Deprecated in favor of deliveryEstimate

shippingMethod.deliveryEstimate

object

The delivery estimate of the shipping method.

paymentStatus

enum<string>

Deprecated in favor of status. Do not use this field to trigger actions in your system.

Available options:

failed,

canceled,

processing,

requires_action,

succeeded,

in_refund,

refunded,

refund_failed,

partially_refunded,

not_settled,

disputed,

frozen_due_to_aml

refunds

object[]

The list of refunds connected to this order.

A Refund object. This corresponds to one Refund request.

refundAmount

number

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

offsetProject

string

Only valid for sustainable incentive mode. The social / sustainability project chosen by the user during Checkout.

displayId

string

The customer facing id. This id is displayed to the user during the checkout and in the merchant dashboard.

Maximum length: 200

merchantFinancialAddress

object

deprecated

bankStatementReference

string

deprecated

The bank statement reference of the payment for the order. This is the reference that will be visible on the bank statement.

destination

object

statusHistoryList

object[]

List of status history items for the order, used for logging every update on status.

paymentMethodType

enum<string>

Available options:

sepa_debit,

customer_balance,

manual_bank_transfer

mandate

object

subaccountId

string

The subaccount id of the order.

statusClassification

object

subaccountLegalName

string

The legal name of the subaccount

paymentMode

enum<string>

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

Available options:

settlement,

direct

customerId

string

The unique identifier of the customer who placed the order.

bankId

string

The unique identifier of Ivy of the chosen bank to make the payment. Not there, if no payment was made.

curl --request POST \
  --url https://api.sand.getivy.de/api/service/order/create \
  --header 'Content-Type: application/json' \
  --header 'X-Ivy-Api-Key: <api-key>' \
  --data '{
  "amount": 123,
  "currency": "EUR",
  "referenceId": "<string>",
  "expiresAt": "<string>",
  "customer": {
    "email": "jsmith@example.com"
  },
  "subaccountId": "<string>"
}'

{
  "id": "<string>",
  "payerFinancialAddress": {
    "type": "<string>",
    "iban": {
      "iban": "<string>",
      "bic": "<string>",
      "accountHolderName": "<string>"
    },
    "sortCode": {
      "sortCode": "<string>",
      "accountNumber": "<string>",
      "accountHolderName": "<string>"
    },
    "bankCode": {
      "code": "<string>",
      "accountNumber": "<string>",
      "accountHolderName": "<string>"
    },
    "bban": {
      "bban": "<string>",
      "accountHolderName": "<string>",
      "bic": "<string>"
    }
  },
  "merchantId": "<string>",
  "appId": "<string>",
  "merchantAppId": "<string>",
  "shopperEmail": "<string>",
  "shopper": {
    "email": "<string>",
    "phoneNumber": "<string>"
  },
  "shopName": "<string>",
  "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"
  },
  "referenceId": "<string>",
  "metadata": {},
  "category": "<string>",
  "applicationFeeAmount": 123,
  "price": {
    "total": 123,
    "currency": "EUR",
    "subTotal": 123,
    "shipping": 123,
    "totalNet": 123,
    "vat": 123
  },
  "co2Grams": 123,
  "trees": 123,
  "lineItems": [
    {
      "name": "<string>",
      "referenceId": "<string>",
      "singleNet": 123,
      "singleVat": 123,
      "amount": 123,
      "quantity": 123,
      "image": "<string>",
      "category": "<string>",
      "EAN": "<string>"
    }
  ],
  "shopLogo": "<string>",
  "incentiveMode": "white_label",
  "guest": true,
  "climateActionMode": {
    "type": "transaction",
    "amount": 123
  },
  "impactOffsetProjects": [
    "<string>"
  ],
  "shippingMethod": {
    "id": "<string>",
    "price": 123,
    "name": "<string>",
    "countries": [
      "AF"
    ],
    "reference": "<string>",
    "timeFrame": "<string>",
    "deliveryEstimate": {
      "minimum": {
        "unit": "hour",
        "value": 123
      },
      "maximum": {
        "unit": "hour",
        "value": 123
      }
    }
  },
  "paymentStatus": "failed",
  "status": "failed",
  "refunds": [
    {
      "id": "<string>",
      "description": "<string>",
      "referenceId": "<string>",
      "amount": 123,
      "status": "pending",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z"
    }
  ],
  "refundAmount": 123,
  "offsetProject": "<string>",
  "displayId": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "merchantFinancialAddress": {
    "type": "<string>",
    "iban": {
      "iban": "<string>",
      "bic": "<string>",
      "accountHolderName": "<string>"
    },
    "sortCode": {
      "sortCode": "<string>",
      "accountNumber": "<string>",
      "accountHolderName": "<string>"
    },
    "bankCode": {
      "code": "<string>",
      "accountNumber": "<string>",
      "accountHolderName": "<string>"
    },
    "bban": {
      "bban": "<string>",
      "accountHolderName": "<string>",
      "bic": "<string>"
    },
    "paymentReference": "<string>"
  },
  "bankStatementReference": "<string>",
  "destination": {
    "bankAccount": {
      "type": "<string>",
      "iban": {
        "iban": "<string>",
        "bic": "<string>",
        "accountHolderName": "<string>"
      },
      "sortCode": {
        "sortCode": "<string>",
        "accountNumber": "<string>",
        "accountHolderName": "<string>"
      },
      "bankCode": {
        "code": "<string>",
        "accountNumber": "<string>",
        "accountHolderName": "<string>"
      },
      "bban": {
        "bban": "<string>",
        "accountHolderName": "<string>",
        "bic": "<string>"
      }
    },
    "bankStatementReference": "<string>"
  },
  "statusHistoryList": [
    {
      "previousStatus": "failed",
      "currentStatus": "failed",
      "reason": "<string>",
      "updatedAt": "2023-11-07T05:31:56Z"
    }
  ],
  "paymentMethodType": "sepa_debit",
  "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>",
  "instantPaymentScheme": true,
  "statusClassification": {
    "primary": "<string>",
    "secondary": "<string>"
  },
  "subaccountLegalName": "<string>",
  "paymentMode": "settlement",
  "customerId": "<string>",
  "bankId": "<string>"
}

Getting Started

Bank

Checkout

Customer

Order

Charge

Mandate

Capabilities

Subaccount

Refund

Payout Report

Banking

Customer Payout

FX

Authorizations

Body

Response