Sign in

v1

latestOpenAPI 3.0.3MIT2026-07-2428350487.0 KB
PayPal

Create a PayPal Order

post/paypal/orders

Request body

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.

currencyCodestring required

Currency code of the payment (ISO 4217)

intent'authorize' | 'capture'

By default payments against an order will be captured in a single step, but you can choose to split the authorization and the capture of the order.

  • authorize - if you intend to first authorize using POST /paypal/orders/{orderId}/payments with an intent of authorize then capture the authorized payment using POST /paypal/orders/{orderId}/payments with an intent of capture
  • capture - If you intend to capture immediately using POST /paypal/orders/{orderId}/payments with an intent of capture
customerOrderCodestring

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

displayNamestring

Business name which overrides the name in the PayPal account.

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

localestring

The locale used during PayPal payment (BCP 47).

invoiceIdstring

Merchant provided invoice number for the order.

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

vaultboolean

Requests for the user's PayPal wallet to be vaulted by PayPal. If the customer agrees when redirected to PayPal, and if the payment is successful, a vaultId will be made available. This is false by default.

returnUrlstring

The URL to return the customer to upon successful approval of a payment on the PayPal site. Mandatory if vaulting is requested.

cancelUrlstring

The URL to return the customer to upon cancellation of the request on the PayPal site. Mandatory if vaulting is requested.

enableShippingAddressboolean

Dictates display of shipping address selection during PayPal payment. If an address is supplied in shippingAddressOverride it will be displayed regardless of the value of this field.

shippingAddressEditableboolean

Dictates display of shipping address selection during PayPal payment regardless of if a shipping address override is present.

cashierIdstring

For use by BR-DGE Cashier to link the transaction to a particular Cashier instance.

customMetadataCustomMetadata

Optional custom metadata string fields for the transaction.

Up to 25 fields can be included with the following constraints:

The field name may not be empty or have leading or trailing whitespace, and can consist of upper and lowercase letters, numbers, space, underscore "_", hyphen "-" and single quote "'".

Maximum string length of either field name and field value is 200 chars.

customerIdstring

The ID of the customer in your system.

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

customerIpAddressstring ipv4

IP address of the customer

vaultIdstring

Vault ID generated by PayPal referring to the customer's stored PayPal wallet.

Example request

{
  "amount": 1234,
  "currencyCode": "GBP",
  "customerOrderCode": "ABC123",
  "displayName": "Display Name",
  "locale": "en-GB",
  "invoiceId": "987654321",
  "vault": true,
  "enableShippingAddress": true,
  "shippingAddressOverride": {
    "address1": "Flat 1",
    "address2": "Victoria House",
    "town": "Edinburgh",
    "county": "Lothian",
    "postcode": "BH23 6AA",
    "country": "GB",
    "phoneNumber": "+44 123 1110000",
    "buildingNumberOrName": "10a",
    "recipientName": "John Smith"
  },
  "lineItems": [
    {
      "name": "T-Shirt",
      "description": "A green t-shirt",
      "quantity": 1,
      "unitAmount": 1000,
      "unitTax": 100
    }
  ],
  "customer": {
    "accountId": "A12345N343",
    "firstName": "John",
    "lastName": "Smith",
    "email": "john.smith@example.com",
    "phoneNumber": "+44 123 1110000",
    "country": "GB",
    "creationTimestamp": "2022-01-30T10:10:10Z"
  },
  "ota": {
    "type": "bus",
    "serviceStartDate": "2022-01-30T10:10:10Z",
    "serviceEndDate": "2022-01-30T10:10:10Z",
    "startCountry": "GB",
    "startCity": "Edinburgh",
    "startPostcode": "BH23 6AA"
  },
  "cashierId": "90e7aff7-7e57-459a-a46e-9258c8abc99b",
  "customMetadata": {
    "accountAge": "2",
    "transactionType": "Other"
  },
  "customerId": "Customer001",
  "customerIpAddress": "123.100.100.200",
  "vaultId": "0tb28273r6584005e"
}

Response

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

codestring

Response Code signifying the outcome of the request.

messagestring

A description of the outcome of the request.

idstring

The ID of this request. If you can include these when querying the outcome of individual requests, we can track down the root cause faster.

orderIdstring

The ID of the order.

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

statusstring

The status of the order.

redirectUrlstring

The URL to redirect your customer to to progress the order.

intent'authorize' | 'capture'

By default payments against an order will be captured in a single step, but you can choose to split the authorization and the capture of the order.

  • authorize - if you intend to first authorize using POST /paypal/orders/{orderId}/payments with an intent of authorize then capture the authorized payment using POST /paypal/orders/{orderId}/payments with an intent of capture
  • capture - If you intend to capture immediately using POST /paypal/orders/{orderId}/payments with an intent of capture
creationTimestampstring

The date and time that the order was created

cashierIdstring

For use by BR-DGE Cashier to link the transaction to a particular Cashier instance.

paymentIdstring

The ID of the payment associated with this Order.

Example response

{
  "code": "1000",
  "id": "463ac35c9f6413ad48485a3953bb6124",
  "orderId": "987654321",
  "status": "CAPTURED",
  "redirectUrl": "987654321",
  "creationTimestamp": "2022-01-30T10:10:10Z",
  "riskAssessments": {
    "merchant": {
      "decision": "APPROVED",
      "retryable": true,
      "rawResponse": {
        "httpStatusCode": 200
      }
    }
  },
  "cashierId": "90e7aff7-7e57-459a-a46e-9258c8abc99b",
  "psp": {
    "name": "Checkout.com",
    "transactionId": "6418da68-0b3d-4409-ab14-1ceb752b0b1f",
    "switchAccountId": "switch-account-123",
    "provisionedUserId": "Vx0H4pdAtPCz",
    "additionalInfo": {
      "customerFirstName": "John",
      "customerLastName": "Smith",
      "customerDateOfBirth": "2000-01-01",
      "customerIpAddress": "123.100.100.200",
      "customerId": "de5d7b4a-9410-40e1-85fd-8ceee23c9fd0",
      "paysafecardCustomerId": "151743187547"
    },
    "rawPspResponses": [
      {
        "httpStatusCode": 200,
        "pspName": "Checkout.com",
        "headers": {
          "content-type": [
            "application/json"
          ]
        }
      }
    ]
  },
  "paymentId": "57f7f444-29ce-4230-8c7f-1c1fd85c8bc9"
}