PayPal

Create a PayPal Order

Changed on Nov 3, 2026

post/paypal/orders

Request

Base URL
https://sandbox.comcarde.com/v1
URL
https://sandbox.comcarde.com/v1/paypal/orders
Auth
HTTP bearer

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

IP address of the customer (IPv4 or IPv6)

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"
}

Changes

Nov 3, 2026c13725f5409c Revision changes
- breaking
  the response's body type changed from object to no type for status
- breaking
  the response's body type changed from object to no type for status
- breaking
  the /////// response's property format changed from ipv4 to no format for status
- warning
  changed the pattern of the request property from ^$|^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$ to ^$|^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)(\.(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)){3}|(([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:)|::(ffff(:0{1,4})?:)?((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)|([0-9a-fA-F]{1,4}:){1,4}:((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)))$
- warning
  removed the optional property from the response with the status
- warning
  removed the optional property from the response with the status
- warning
  removed the optional property from the response with the status
- warning
  removed the optional property from the response with the status
- warning
  removed the optional property from the response with the status
- warning
  removed the optional property from the response with the status
- warning
  removed the optional property from the response with the status
- warning
  removed the optional property from the response with the status
- warning
  removed the optional property from the response with the status
- warning
  removed the optional property from the response with the status
- info
  the request property format was generalized from ipv4 to no format
- info
  added subschema #2 to the response body allOf list for the response status
- info
  added subschema #2 to the response body allOf list for the response status
- info
  added the optional property ////////// to the response with the status
- info
  the response property /////// became required for the status
- info
  the response property /////// became required for the status
- info
  the response property /////// became required for the status
- info
  the response property /////// became required for the status
- info
  the response property /////// became required for the status
- info
  the /////// response's property pattern was changed from ^$|^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$ to ^$|^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)(\.(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)){3}|(([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:)|::(ffff(:0{1,4})?:)?((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)|([0-9a-fA-F]{1,4}:){1,4}:((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)))$ for the status

Operation history

Create a PayPal Order

Request

Request body

Example request

Response 201Created

Example response

Changes

Response