v1

latestOpenAPI 3.0.3MIT2026-07-2428350487.0 KB

Orders

Create a BR-DGE Hosted Payment Page Order

post/orders

Request body

allowedPaymentInstrumentsOrderPaymentInstrumentType[]

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

amountinteger 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.

cardOnFileTermsAndConditionsUrlstring

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 cardOnFileTermsAndConditionsUrlis specified andcustomerAgreedToSaveCard` 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.

corporateCardPercentageSurchargenumber 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.

currencyCodestring required

Currency code of the payment (ISO 4217)

customerAgreedToSaveCardboolean

If Credentials On File Mandate requirements 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.

cardOnFileSaveEnabledboolean

Determines if the save card checkbox is to be displayed or not.

customerEmailstring required

Email address of the customer

customerFirstNamestring required

First name of the customer (customerFirstName length plus customerLastName length must be less than 255 characters long)

customerIdstring

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: '[]()@?!\-/.,_&*:;+=

customerLastNamestring

Last name of the customer (customerFirstName length plus customerLastName length must be less than 255 characters long)

customerOrderCodestring 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: '[]()@?!\-/.,_&*:;+=

customerPhoneNumberstring

Telephone number of the customer

intentstring

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

orderDescriptionstring required

Description of what the order is for

Please use only letters, numbers, spaces and these symbols: '[]()@?!\-/.,_&*:;+=

returnUrlstring required

Return URL for confirmed order

threeDSecureRequiredboolean

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.

tokensstring

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: '[]()@?!\-/.,_&*:;+=

Example request

{
  "allowedPaymentInstruments": [
    "applePay",
    "card"
  ],
  "amount": 1234,
  "billingAddress": {
    "firstName": "John",
    "lastName": "Smith",
    "phoneNumber": "+44 123 1110000",
    "buildingNumberOrName": "10a",
    "address1": "Flat 1",
    "address2": "Victoria House",
    "address3": "15 Apple Street",
    "town": "Edinburgh",
    "county": "Lothian",
    "postcode": "BH23 6AA",
    "country": "GB"
  },
  "cardOnFileTermsAndConditionsUrl": "http://example.com/terms",
  "corporateCardPercentageSurcharge": 12.5,
  "currencyCode": "GBP",
  "customerEmail": "a@b.com",
  "customerFirstName": "John",
  "customerId": "john@doe.com",
  "customerLastName": "Smith",
  "customerOrderCode": "ABC123",
  "customerPhoneNumber": "+44 123 1110000",
  "deliveryAddress": {
    "firstName": "John",
    "lastName": "Smith",
    "phoneNumber": "+44 123 1110000",
    "buildingNumberOrName": "10a",
    "address1": "Flat 1",
    "address2": "Victoria House",
    "address3": "15 Apple Street",
    "town": "Edinburgh",
    "county": "Lothian",
    "postcode": "BH23 6AA",
    "country": "GB"
  },
  "orderDescription": "Taxi fare",
  "returnUrl": "http://www.return.url",
  "threeDSecureRequired": true,
  "tokens": "token1,token2",
  "payPal": {
    "invoiceId": "987654321",
    "customerAccountId": "A12345N343",
    "customerAccountCreationTimestamp": "2022-01-30T10:10:10Z",
    "enableShippingAddress": true,
    "displayName": "Display Name",
    "locale": "en_GB",
    "lineItems": [
      {
        "name": "T-Shirt",
        "description": "A green t-shirt",
        "quantity": 1,
        "unitAmount": 1000,
        "unitTax": 100
      }
    ],
    "ota": {
      "type": "bus",
      "serviceStartDate": "2022-01-30T10:10:10Z",
      "serviceEndDate": "2022-01-30T10:10:10Z",
      "startCountry": "GB",
      "startCity": "Edinburgh",
      "startPostcode": "BH23 6AA"
    }
  }
}

Response

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

codestring

A unique identifier covering the outcome of the request

idstring

The ID of this request

messagestring

A description of the outcome of the request

orderIdstring

The ID of this order

redirectUrlstring

The URL to redirect your customer to in progress the order

Example response

{
  "code": "1000",
  "id": "4fad8e2e06a15656"
}