---
title: "Create a BR-DGE Hosted Payment Page Order"
method: POST
path: "/orders"
tags: ["Orders"]
---

# Create a BR-DGE Hosted Payment Page Order

`POST /orders`

## Request body

- Order — Class representing an order tracked by the application.
  - `allowedPaymentInstruments` OrderPaymentInstrumentType[] — By default, the BR-DGE Hosted Payment Page will attempt to offer all possible payment methods based on a range of criteria including: - The payment methods that are enabled on your retail channels. - The availability of PSPs connected to your retail channel, and the payment methods they support. - The payment methods that are supported by your customers' web browser. As it is sometimes useful to limit the available payment methods on a per-order basis, you have the option to specify a set of allowed payment methods when creating an order via `POST /orders`. This will result in only the payment methods specified in the set being offered to your customer as part of the order. Possible values: - `card` - `applePay` - `googlePay` - `payPal` - `astroPay` - `visaInstalments` please note that you should also enable `card` if you wish to enable Visa Installments. - `trustly`
  - `amount` integer, required — Amount in a currency to be used for the transaction. In the lowest denomination of the currency of the payment. This means that `1234` in GBP represents `£12.34`.
  - `billingAddress` Address
    - `firstName` string — First name of the occupant. Please use only letters, spaces and these symbols: `-'.`
    - `lastName` string — Last name of the occupant. Please use only letters, spaces and these symbols: `-'.`
    - `phoneNumber` string — Telephone number of the occupant Please use only numbers, spaces and an optional leading +.
    - `buildingNumberOrName` string — The building number or name. Providing a building number or name separate from `address1` is recommended as some payment service provider (PSP) APIs have a separate field. If you are unsure whether you need to collect this data, please raise a ticket with support on the BR-DGE Support Portal at <https://docs.br-dge.io/docs/support#contact-support>. Please use only letters, spaces and these symbols: `-'.`
    - `address1` string — First line of the address. Please use only letters, numbers, spaces and these symbols: `'[]()@?!\-/.,_&*:;+=`
    - `address2` string — Second line of the address. Please use only letters, numbers, spaces and these symbols: `'[]()@?!\-/.,_&*:;+=`
    - `address3` string — Third line of the address. Please use only letters, numbers, spaces and these symbols: `'[]()@?!\-/.,_&*:;+=`
    - `town` string — Town of the address. Please use only letters, numbers, spaces and these symbols: `'[]()@?!\-/.,_&*:;+=`
    - `county` string — County of the address. Please use only letters, numbers, spaces and these symbols: `'[]()@?!\-/.,_&*:;+=`
    - `postcode` string — Postcode of the address. Please use at least one and no more than 9 alphanumeric characters (excl. spaces).
    - `country` string — ISO 3166 Alpha-2 Country code
  - `cardOnFileTermsAndConditionsUrl` string — Link to terms and conditions relating to saving card details. If `cardOnFileTermsAndConditionsUrl` is specified and `customerAgreedToSaveCard`` is set to true then a message will be displayed to your customer notifying them that their card details will be saved according to the linked terms and conditions. If `cardOnFileTermsAndConditionsUrl` is specified and `customerAgreedToSaveCard` is not specified or set to false then your customer will be given the opportunity to agree to the linked terms and conditions and have their card details saved.
  - `corporateCardPercentageSurcharge` number, double — If provided then when BR-DGE detects a shopper using a corporate card we will automatically apply a surcharge to the base amount for the order. Your customer will be notified of any surcharges and given the option to use an alternative payment method.
  - `currencyCode` string, required — Currency code of the payment (ISO 4217)
  - `customerAgreedToSaveCard` boolean — If [Credentials On File Mandate requirements](https://docs.br-dge.io/docs/vault#credentials-on-file-mandate-compliance) relating to cardholder consent has been met prior to creating an order you can set this flag to ensure that the Hosted Payment Page always creates a BR-DGE Card on File if your customer enters card details. Please note that if you set this to true then you also need to provide a link to the agreement via the `cardOnFileTermsAndConditionsUrl` field.
  - `cardOnFileSaveEnabled` boolean — Determines if the save card checkbox is to be displayed or not.
  - `customerEmail` string, required — Email address of the customer
  - `customerFirstName` string, required — First name of the customer (customerFirstName length plus customerLastName length must be less than 255 characters long)
  - `customerId` string — Associate order with a customer identifier. Any pre-existing BR-DGE Card on Files for the customer will automatically be presented as payment methods and any new BR-DGE Cards on File will be associated with the customer. Please use only letters, numbers, spaces and these symbols: `'[]()@?!\-/.,_&*:;+=`
  - `customerLastName` string — Last name of the customer (customerFirstName length plus customerLastName length must be less than 255 characters long)
  - `customerOrderCode` string, required — You may provide your own order code to be used in payments This is separate from the BR-DGE order. Please use only letters, numbers, spaces and these symbols: `'[]()@?!\-/.,_&*:;+=`
  - `customerPhoneNumber` string — Telephone number of the customer
  - `deliveryAddress` Address
    - `firstName` string — First name of the occupant. Please use only letters, spaces and these symbols: `-'.`
    - `lastName` string — Last name of the occupant. Please use only letters, spaces and these symbols: `-'.`
    - `phoneNumber` string — Telephone number of the occupant Please use only numbers, spaces and an optional leading +.
    - `buildingNumberOrName` string — The building number or name. Providing a building number or name separate from `address1` is recommended as some payment service provider (PSP) APIs have a separate field. If you are unsure whether you need to collect this data, please raise a ticket with support on the BR-DGE Support Portal at <https://docs.br-dge.io/docs/support#contact-support>. Please use only letters, spaces and these symbols: `-'.`
    - `address1` string — First line of the address. Please use only letters, numbers, spaces and these symbols: `'[]()@?!\-/.,_&*:;+=`
    - `address2` string — Second line of the address. Please use only letters, numbers, spaces and these symbols: `'[]()@?!\-/.,_&*:;+=`
    - `address3` string — Third line of the address. Please use only letters, numbers, spaces and these symbols: `'[]()@?!\-/.,_&*:;+=`
    - `town` string — Town of the address. Please use only letters, numbers, spaces and these symbols: `'[]()@?!\-/.,_&*:;+=`
    - `county` string — County of the address. Please use only letters, numbers, spaces and these symbols: `'[]()@?!\-/.,_&*:;+=`
    - `postcode` string — Postcode of the address. Please use at least one and no more than 9 alphanumeric characters (excl. spaces).
    - `country` string — ISO 3166 Alpha-2 Country code
  - `intent` string — By default payments are captured immediately, but you can you can choose to split the authorization and the capture of the payment. * `authorize` - if you intend to capture separately using `POST /payments/{paymentId}/capture` * `capture` - If you intend to capture immediately
  - `merchantInitiated` 'unscheduled' | 'recurring' — Only set this field if you are using the Hosted Payment Page to perform an initial Merchant Initiated Transaction (MIT). For more information see [here]. Possible values: - `unscheduled` An unscheduled charge for a service such as e-scooter hire - `recurring` A recurring payment for a magazine subscription [here]: https://docs.br-dge.io/docs/vault#making-merchant-initiated-transactions-mits-using-card-on-file
  - `orderDescription` string, required — Description of what the order is for Please use only letters, numbers, spaces and these symbols: `'[]()@?!\-/.,_&*:;+=`
  - `returnUrl` string, required — Return URL for confirmed order
  - `threeDSecureOptions` ThreeDSecureOptions — Some Payment Service Providers allow you to pass parameters to indicate your preferences relating to 3-D Secure. Note: We cannot guarantee that downstream Payment Service Providers will honour your preferences, but we can ensure that your preferences are passed on whenever possible.
    - `challengeRequested` boolean — Indicates whether the payment request should result in a 3-D Secure challenge and not experience a frictionless flow, if handled by a payment service provider that supports this feature.
    - `exemptionRequested` boolean — Indicates whether the payment request should be considered for a 3D Secure exemption, if handled by a payment service provider that supports this feature. DEPRECATED: the 'scaExemption' field should be used instead.
    - `automaticallyStepUp` boolean — Attempt a payment without 3DSecure, and if 3DSecure is requested from the PSP, automatically re-attempt the payment with 3DSecure.
  - `threeDSecureRequired` boolean — You can indicate that 3-D Secure processing is preferred, usually initializing a 3-D Secure authentication flow. Note that setting this as true does not guarantee that the payment will end up with successful 3-D Secure authentication. Also, setting this to false does not guarantee that 3-D Secure authentication will not be applied to the payment, as some PSPs may choose to apply their own rules around this regardless need to opt-in to 3-D Secure authentication on a per-payment basis.
  - `tokens` string — A comma-delimited set of BR-DGE Card on File multi-use tokens to be offered as payment methods for the order. Please use only letters, numbers, spaces and these symbols: `'[]()@?!\-/.,_&*:;+=`
  - `payPal` PayPalHppOrderDetails — Additional configuration if PayPal is enabled within your order and Retail Channel.
    - `invoiceId` string — Merchant provided invoice number for the order. Please use only letters, numbers, spaces and these symbols: `'[]()@?!\-/.,_&*:;+=`
    - `customerAccountId` string — Customer's account ID with the merchant. Please use only letters, numbers, spaces and these symbols: `'[]()@?!\-/.,_&*:;+=`
    - `customerAccountCreationTimestamp` string — The date and time that the customers account was created.
    - `enableShippingAddress` boolean — Dictates display of shipping address selection during PayPal payment. If an address is supplied in deliveryAddress it will be displayed regardless of the value of this field.
    - `shippingAddressEditable` boolean — Dictates display of shipping address selection during PayPal payment regardless of if a shipping address override is present.
    - `displayName` string — Business name which overrides the name in the PayPal account. Please use only letters, numbers, spaces and these symbols: `'[]()@?!\-/.,_&*:;+=`
    - `locale` string — The end-users localization preference in the format [language[_territory]]. Language is the ISO 639-1 code and territory the ISO 3166 Alpha-2 code.
    - `lineItems` LineItem[]
      - `name` string — Name of the item. Please use only letters, numbers, spaces and these symbols: `'[]()@?!\-/.,_&*:;+=`
      - `description` string — Description of the item. Please use only letters, numbers, spaces and these symbols: `'[]()@?!\-/.,_&*:;+=`
      - `quantity` integer — Number of the item ordered.
      - `unitAmount` integer — Amount per unit.
      - `unitTax` integer — Item tax per unit.
    - `ota` PayPalOnlineTravelAgency — Details of the booked transportation. Only required if you're an online travel agency.
      - `type` 'hotel' | 'train' | 'ferry' | 'bus' | 'multimodal' | 'airline' — The type of transportation the customer has booked.
      - `serviceStartDate` string — The start date of the transport.
      - `serviceEndDate` string — The end date of the transport.
      - `changeGuest` boolean — Whether the customer associated with the booking can change.
      - `startCountry` string — The starting country of the transportation.
      - `startCity` string — The starting city of the transportation. Please use only letters, numbers, spaces and these symbols: `'[]()@?!\-/.,_&*:;+=`
      - `startPostcode` string — The starting postcode of the transportation. Please use only letters, numbers, spaces and these symbols: `'[]()@?!\-/.,_&*:;+=`

## Response `201`

Order created. You can now redirect your customer to the provided URL.

- OrderResponse
  - `code` string — A unique identifier covering the outcome of the request
  - `id` string — The ID of this request
  - `message` string — A description of the outcome of the request
  - `orderId` string — The ID of this order
  - `redirectUrl` string — The URL to redirect your customer to in progress the order

## Other responses

- `400` — Bad request - the request was in an invalid format or contained invalid information. If have any questions about why you are receiving these responses, please raise a ticket with support on the BR-DGE Support Portal at <https://docs.br-dge.io/docs/support#contact-support> with the `id` from the response so we track down the individual requests on our end.
- `401` — Unauthorized request.
- `500` — An internal server error occurred upstream while processing the request. If you have any questions about why you are receiving these responses, please raise a ticket with support on the BR-DGE Support Portal at <https://comcarde.atlassian.net/servicedesk/customer/portals> with the `id` from the response so we track down the individual requests on our end.

---

[API](https://skmtc.net/br-dge/apis/br-dge-transaction-rest-api.md) · [All operations](https://skmtc.net/br-dge/apis/br-dge-transaction-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/br-dge/br-dge-transaction-rest-api/revisions/a9c0feac5523/schema)