--- title: "Create a PayPal Order" method: POST path: "/paypal/orders" tags: ["PayPal"] --- # Create a PayPal Order `POST /paypal/orders` ## Request body - PayPalOrderRequest — Create PayPal Order request - `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`. - `currencyCode` string, 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` - `customerOrderCode` string — 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: `'[]()@?!\-/.,_&*:;+=` - `displayName` string — Business name which overrides the name in the PayPal account. Please use only letters, numbers, spaces and these symbols: `'[]()@?!\-/.,_&*:;+=` - `locale` string — The locale used during PayPal payment (BCP 47). - `invoiceId` string — Merchant provided invoice number for the order. Please use only letters, numbers, spaces and these symbols: `'[]()@?!\-/.,_&*:;+=` - `vault` boolean — 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. - `returnUrl` string — The URL to return the customer to upon successful approval of a payment on the PayPal site. Mandatory if vaulting is requested. - `cancelUrl` string — The URL to return the customer to upon cancellation of the request on the PayPal site. Mandatory if vaulting is requested. - `enableShippingAddress` boolean — 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. - `shippingAddressEditable` boolean — Dictates display of shipping address selection during PayPal payment regardless of if a shipping address override is present. - `shippingAddressOverride` ShippingAddressOverride — Details of the destination to ship the items too. - `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: `'[]()@?!\-/.,_&*:;+=` - `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 - `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 . Please use only letters, spaces and these symbols: `-'.` - `recipientName` string — Full name of the recipient. Please use only letters, numbers, spaces and these symbols: `'[]()@?!\-/.,_&*:;+=` - `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. - `customer` PayPalCustomer — Customer's account details with the merchant. - `accountId` string — Customer's account ID with the merchant. Please use only letters, numbers, spaces and these symbols: `'[]()@?!\-/.,_&*:;+=` - `firstName` string — Customer's first name. Please use only letters, numbers, spaces and these symbols: `'[]()@?!\-/.,_&*:;+=` - `lastName` string — Customer's last name. Please use only letters, numbers, spaces and these symbols: `'[]()@?!\-/.,_&*:;+=` - `email` string — Email address of the customer. - `phoneNumber` string — Telephone number of the occupant Please use only numbers, spaces and an optional leading +. - `country` string — ISO 3166 Alpha-2 Country code - `creationTimestamp` string — The date and time that the customers' account was created. - `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: `'[]()@?!\-/.,_&*:;+=` - `cashierId` string — For use by BR-DGE Cashier to link the transaction to a particular Cashier instance. - `customMetadata` CustomMetadata — 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. - `riskInstruments` RiskInstruments — Map of optional risk instrument objects which can be used to pass risk information to PSPs or risk engines - `checkoutRiskJs` CheckoutRiskJs — Risk instrument for Checkout's Risk.js product. Checkout's risk engine will also use the customer's IP address if available which can be provided via Payment.customerIpAddress - `deviceSessionId` string, required — device_session_id token generated in Checkout's Risk.js package - `kount` Kount — Risk instrument for Kount risk engine - `sessionId` string, required — [Session ID] used in Kount's [Device Data Collector] [Session ID]: https://developer.kount.com/hc/en-us/sections/5319287642260-Integration-Guide?article=4411121644820 [Device Data Collector]: https://developer.kount.com/hc/en-us/sections/5319287642260-Integration-Guide?article=4411121101844 - `merchant` Merchant — Risk instrument for Merchant risk engine - `customerId` string — The ID of the customer in your system. Please use only letters, numbers, spaces and these symbols: `'[]()@?!\-/.,_&*:;+=` - `customerIpAddress` string, ipv4 — IP address of the customer - `vaultId` string — Vault ID generated by PayPal referring to the customer's stored PayPal wallet. ## Response `201` Order created. You can now redirect your customer to the provided URL. - PayPalOrderResponse — Create PayPal Order response. - `code` string — [Response Code](https://docs.br-dge.io/docs/response-codes) signifying the outcome of the request. - `message` string — A description of the outcome of the request. - `id` string — 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. - `orderId` string — The ID of the order. Should only contain letters, numbers, spaces and these symbols: `'[]()@?!\-/.,_&*:;+=` - `status` string — The status of the order. - `redirectUrl` string — 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` - `creationTimestamp` string — The date and time that the order was created - `riskAssessments` PayPalOrderRiskAssessments — An optional map of risk assessment results received from risk engines. - `merchant` MerchantRiskAssessment — Risk assessment from Merchant's own risk engine. Can be used to return results when the merchant has a proprietary risk or validation engine they wish to call during the payment or payout flows. - `decision` 'APPROVED' | 'DECLINED' | 'UNAVAILABLE' | 'HELD', required — Merchant's decision Can be one of: - `APPROVED`: Merchant's risk engine has approved the transaction. - `DECLINED`: Merchant's risk engine has declined the transaction. - `UNAVAILABLE`: Merchant's risk engine was unavailable to give a decision. - `HELD`: Merchant’s risk engine has placed the transaction on hold - `code` string — The response code returned by the engine. - `message` string — Message returned by the engine. - `retryable` boolean — Indicates whether transaction can be amended and retried. - `transactionId` string — Transaction identifier returned by the Merchant risk engine. - `rawResponse` RawResponse — Contains a single http response. - `httpStatusCode` integer — The http response code for the given call to the external system - `body` string — The response body of the http request to the external system. This is the raw response with sensitive data redacted. We make no guarantees about the format of this field. It is psp dependant. The majority of these responses are in `application/json` but note for certain types of error response they may be `text/html` or `application/xml` - `cashierId` string — For use by BR-DGE Cashier to link the transaction to a particular Cashier instance. - `psp` PspInfo - `name` string, required — Name of Payment Service Provider (PSPs). Please see [PSP Integrations] for a list of possible PSPs. [PSP Integrations]: https://docs.br-dge.io/docs/psp-integrations - `transactionId` string, required — Identifier provided by the PSP this payment was routed to. - `switchAccountId` string — Internal switch account identifier for the PSP account that was used to perform the transaction. This is an internally-assigned identifier, not a value provided by the PSP. Please note: PSP account switching feature is still under development and this field is not present in GET responses and notifications yet. - `pspToken` string — The token created by the PSP for the payment instrument. - `pspCardFingerprint` string — The PSP fingerprint for the payment instrument. - `provisionedUserId` string — PSP-specific user ID that was provisioned by the PSP when processing the payment. - `additionalInfo` union — Any additional information returned from interaction with PSP - object - `type` string — Discriminator field. Please see the discriminator mapping for the `AdditionalInfo` schema. - `customerFirstName` string — Customer's first name - `customerLastName` string — Customer's last name - `customerDateOfBirth` string, date — Customer's date of birth - `customerIpAddress` string, ipv4 — IP address of the customer - `customerId` string — The ID of the customer in your system. - `paysafecardCustomerId` string — Paysafecard identifier for the customer - object - `type` string — Discriminator field. Please see the discriminator mapping for the `AdditionalInfo` schema. - `customerPaymentOptionId` string — Identifier for the customer Payment Option - object - `type` string — Discriminator field. Please see the discriminator mapping for the `AdditionalInfo` schema. - `customerPaymentOptionId` string — Identifier for the customer Payment Option - object - `type` string — Discriminator field. Please see the discriminator mapping for the `AdditionalInfo` schema. - `customer` TrueLayerCustomer — Contains TrueLayer customer information. - `address` 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 . 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 - `dateOfBirth` string, date — Date of birth of the referenced person. While this field is not required by the BR-DGE API; it is highly recommended as some PSPs recommend the inclusion of this field. If you have any questions about whether you should provide customer date of birth, please raise a ticket with the [BR-DGE Support Centre](https://support.br-dge.io/support/home). - `customerId` string — The ID of the customer in TrueLayer's system - `name` string — Customer's full name - `providerId` string — ID of the bank or other financial institution used in this payment in TrueLayer's system - `paymentSourceId` string — ID of the customer's payment source used to perform the payment in TrueLayer's system - `originalTransactionId` string - `accountNumber` string — 8 digit bank account number. - `sortCode` string — 6 digit sort code (no spaces or dashes). - `iban` string — Valid ISO 13616 International Bank Account Number (no spaces). Consists of a 2 letter country code, followed by 2 check digits, and then by up to 30 alphanumeric characters (also known as the BBAN). - object - `type` string — Discriminator field. Please see the discriminator mapping for the `AdditionalInfo` schema. - `fingerprint` string — The fingerprint associated to the authorized order's payment method - `name` string — The name of the revolut customer. - `emailAddress` string — The email address of the revolut customer - `paymentRevTag` string — Unique handle for a Revolut customer. - `revolutCustomerId` string, uuid — The unique identifier for the revolut customer. - `billingAddress` RevolutPayBillingAddress - `street_line_1` string — First line of street address information for Revolut customer. - `street_line_2` string — Second line of street address information for Revolut customer.. - `region` string — The region associated with the address. - `city` string — The region associated with the address. - `country_code` string — 2 letter country code of the country associated with the address. - `postcode` string — The postcode associated with the address. - object - `type` string — Discriminator field. Please see the discriminator mapping for the `AdditionalInfo` schema. - `vaultId` string — Vault ID generated by PayPal referring to the customer's stored PayPal wallet. - `paymentSource` PaymentSource — Details of the PayPal account used to complete the payment for the PayPal Order. - `name` string — Full name of customer. - `email` string — Email address of the customer. - `accountId` string — PayPal account ID. - `vaultId` string — Vault ID generated by PayPal referring to the customer's stored PayPal wallet. - object - `type` string — Discriminator field. Please see the discriminator mapping for the `AdditionalInfo` schema. - `pin` string — voucher pin - `serialNumber` string — voucher serial number - `rawPspResponses` RawPspResponse[], nullable - `httpStatusCode` integer — The http response code for the given call to the external system - `body` string — The response body of the http request to the external system. This is the raw response with sensitive data redacted. We make no guarantees about the format of this field. It is psp dependant. The majority of these responses are in `application/json` but note for certain types of error response they may be `text/html` or `application/xml` - `pspName` string, required — Name of Payment Service Provider (PSPs). Please see [PSP Integrations] for a list of possible PSPs. [PSP Integrations]: https://docs.br-dge.io/docs/psp-integrations - `headers` object — A key/value map of the http headers from the external system. - `paymentAccountReference` string — The Payment Account Reference (PAR) linked the the payment-instrument, if available. See our [dedicated PAR guide](https://docs.br-dge.io/docs/payment-account-reference) for more info. - `paymentId` string — The ID of the payment associated with this 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 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 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)