> ## Documentation Index > Fetch the complete documentation index at: https://docs.paybyrd.com/llms.txt > Use this file to discover all available pages before exploring further. # Create Order > This endpoint allows you to create a new order. Orders are used in Paybyrd Checkout or the Pay By Link feature. ## OpenAPI ````yaml /openapi.yml post /api/v2/orders openapi: 3.0.3 info: title: Gateway API version: v2 contact: name: Support email: support@paybyrd.com license: name: Copyright © Paybyrd termsOfService: https://paybyrd.com/en/privacy servers: - url: https://gateway.paybyrd.com description: Production security: - authByApiKey: [] paths: /api/v2/orders: post: tags: - Orders summary: Create Order description: >- This endpoint allows you to create a new order. Orders are used in Paybyrd Checkout or the Pay By Link feature. operationId: api-orders-create requestBody: content: application/json: schema: $ref: '#/components/schemas/OrderCreation' examples: Minimal order request: $ref: '#/components/examples/OrderCreationBasicExample' Order request with paybylink: $ref: '#/components/examples/OrderCreationWithPaybylinkExample' Order request with tokenization: $ref: '#/components/examples/OrderCreationWithTokenizationExample' Order request full: $ref: '#/components/examples/OrderCreationFullExample' responses: '201': description: '201' content: application/json: examples: Result: $ref: '#/components/examples/OrderCreationResponseExample' schema: $ref: '#/components/schemas/OrderCreation' deprecated: false components: schemas: OrderCreation: type: object required: - isoAmount - currency - orderRef properties: orderId: type: string description: This field contains the unique identifier that represents the order. format: guid example: e901d7fa-a41a-4c93-bc53-7a08cd72aff4 readOnly: true isoAmount: type: integer description: >- Total amount for this transaction in ISO format, with the following pattern "2500" (to express 25.00) format: int64 currency: type: string description: Valid ISO-4217 alpha code e.g EUR example: EUR orderRef: type: string description: Merchant reference for this order example: ABC123456 orderDate: type: string description: Order creation date in UTC example: '2021-05-31T22:04:31Z' readOnly: true expiresAt: type: string description: >- Order expiration date in UTC, which is the sum of 'sessionExpiresIn' with 'expiresIn' parameters. example: '2021-05-31T22:04:31Z' readOnly: true status: $ref: '#/components/schemas/OrderStatus' readOnly: true checkoutUrl: type: string description: >- The checkoutUrl is the direct link to Paybyrd Checkout. You can use it in your ecommerce to display the payment page to the shopper. example: https://chk.paybyrd.com/chk_fG3F6muPB readOnly: true shopper: $ref: '#/components/schemas/OrderShopper' ShoppingCart: $ref: '#/components/schemas/ShoppingCart' orderOptions: $ref: '#/components/schemas/OrderOptions' paymentOptions: $ref: '#/components/schemas/PaymentOptions' metadata: type: object description: >- Metadata allows you to pass any data to Paybyrd which will be returned in the order query and also sent in the status changed notifications. additionalProperties: true example: key1: 1 key2: value code: $ref: '#/components/schemas/PaybyrdCode' readOnly: true description: $ref: '#/components/schemas/PaybyrdDescription' readOnly: true OrderStatus: type: string description: >- Represents the status of the order. Created - Order has no payments associated to it or all payment attempts have failed. Pending - Order has a payment associated to it which is in progress but not concluded. Paid - Order has a payment associated to it with final status 'Success'. Canceled - This status can occur by system routines, shopper action by clicking on 'cancel payment' button in the hosted page or by calling the order cancel endpoint. Expired - This status occurs by system routines that checks for payment abandonment or in case an expiration date is sent in the create order request. Refunded - In case a successful payment is refunded, its order will have the 'Refunded' status. example: created enum: - created - paid - pending - refunded - canceled - expired OrderShopper: type: object properties: shopperId: type: string description: >- This field contains the unique identifier generated by Paybyrd and it is returned in the API response format: guid example: e901d7fa-a41a-4c93-bc53-7a08cd72aff4 readOnly: true email: type: string description: The shopper's email address format: email example: shopper_email@mail.com firstName: type: string description: The shopper's first name example: Peter lastName: type: string description: The shopper's last name example: Park birthName: type: string description: The shopper's birth name birthDate: type: string description: The The shopper's birth date example: '1985-05-31' birthPostalCode: type: string description: The shopper's postal code associated with the birth address customReference: type: string description: A custom reference to the shopper civility: type: string description: The civility or title of the shopper example: Mr, Mrs, Ms phoneCountryCode: type: integer description: The shopper's phone country code format: int32 example: 351 phoneNumber: type: string description: The shopper's phone number without country code example: '123123123' maximum: 20 shippingAddress: type: string description: The shopper's shipping address shippingPostalCode: type: string description: The shopper's shipping postal code shippingCity: type: string description: The shopper's shipping city shippingCountry: type: string description: The shopper's shipping country valid ISO-3166 alpha-3 code example: PRT shippingState: type: string description: The state or province of the shopper's shipping address example: SP maximum: 2 shippingType: type: string description: The shopper's shipping type example: National, International, UrgentNational, UrgentInternational homeAddress: type: string description: The shopper's home address homePostalCode: type: string description: The postal code of the shopper's home address homeCity: type: string description: The city of the shopper's home address homeCountry: type: string description: The country of the shopper's home address example: PRT ipAddress: type: string description: The shopper's IP address format: 192.168.0.1 documentNumber: type: string description: The shopper's document number example: ID card number, passport number... firstPurchaseDate: type: string description: The date and time of the first purchase made by the shopper example: '2021-05-10T12:30:00Z' lastPurchaseDate: type: string description: The date and time of the last purchase made by the shopper example: '2021-12-19T19:30:00Z' ShoppingCart: type: array items: oneOf: - $ref: '#/components/schemas/ProductShoppingCartItem' - $ref: '#/components/schemas/TravelShoppingCartItem' - $ref: '#/components/schemas/TravelWithStayShoppingCartItem' OrderOptions: type: object description: Defines settings for this order properties: redirectUrl: type: string description: >- This is the URL which the shopper will be redirected to after payment is concluded in Paybyrd Checkout. We will always concatenate relevant information of the payment as query string parameters in the URL provided. The transactionId and orderId will always be available, so you can use this data to query the status of the order after redirection. example: https://your-site-url/payment-finished format: url culture: type: string description: >- The order culture defines which language will be used to present the order information to the customer. example: en-US expiresIn: type: string description: >- The order will expire according to the value given passed in this field in case its status is 'Created'. In case you also send 'sessionExpiresIn' in the request, the final expiration time will be the sum of both. format: timespan example: '00:15:00' notifyBy: type: object description: >- This is Paybyrd's paybylink feature. When 'notifyBy' is provided, a payment link will be sent to the channels defined inside this object. properties: email: type: object properties: address: type: string description: The email which the payment link will be sent to. format: email example: shopper_email@mail.com sms: type: object properties: phoneCountryCode: type: integer description: The phone country code which the link will be sent to. format: int32 example: 351 PhoneNumber: type: string description: The phone number which the link will be sent to. example: '123123123' maximum: 20 whatsapp: type: object properties: phoneCountryCode: type: integer description: The phone country code which the link will be sent to. format: int32 example: 351 PhoneNumber: type: string description: The phone number which the link will be sent to. example: '123123123' maximum: 20 checkoutVersion: type: integer description: >- Defines the Checkout version to be used for this order. Version 1 uses the legacy hosted form, version 2 uses the new Checkout. enum: - 1 - 2 example: 2 PaymentOptions: type: object description: Defines settings for payment. properties: maxAttempts: type: integer description: >- Indicates the max number of attempts that the shopper has to conclude the payment in Paybyrd Checkout. format: int32 example: 3 sessionExpiresIn: type: string description: >- Defines the time that the shopper has to initiate the payment once the Checkout is open. Session restarts whenever the hosted page is closed and opened again. format: timespan example: '00:15:00' allowedPaymentMethods: type: array description: >- Indicates which payment methods will be available for the shopper to choose in Paybyrd Checkout form. items: $ref: '#/components/schemas/PaymentMethod' example: - CARD - MBWAY cardOptions: type: object properties: isPreAuth: type: boolean description: >- Indicates whether the payment will be processed as a pre-authorization or not if paid with card tokenOptions: type: object description: Defines the payment tokenization settings. required: - customReference properties: customReference: type: string description: >- Custom reference serves as a virtual wallet or identifier that allows you to group and manage multiple tokenized cards When an order is created using the custom reference, all the tokenized cards associated with that reference will be displayed in Paybyrd Checkout, allowing the customer to choose which tokenized card they want to use for the transaction. If there are no tokenized cards associated with the provided custom reference, the Paybyrd system will tokenize the payment card chosen by the shopper. maximum: 50 example: ABC123456789 tokenizationIsRequired: type: boolean description: >- Indicates whether the tokenization of the card payment is mandatory or not for the transaction. example: false tokenizationMethod: type: string description: >- The value indicates what type of tokenization method should be used. At the moment, only card type payments can generate tokens. The value "cardOnFile" is generally used for one-click payment scenarios. The value "subscription' is used for recurring payments. enum: - cardOnFile - subscription PaybyrdCode: type: string description: >- Represents the Paybyrd code of the web request. To see more details check in [Return Codes](ref:appendix-return-codes) page. example: BYRD200 enum: - BYRD010 - BYRD200 - BYRD201 - BYRD203 - BYRD205 - BYRD206 - BYRD207 - BYRD208 - BYRD230 - BYRD231 - BYRD240 - BYRD290 - BYRD291 - BYRD292 - BYRD294 - BYRD299 - BYRD401 - BYRD403 - BYRD900 - BYRD901 - BYRD999 PaybyrdDescription: type: string example: Operation successfully completed description: >- Represents a textually the description of the Paybyrd code of the web request. To see more details check in [Return Codes](ref:appendix-return-codes) page enum: - Request accepted - Operation successfully completed - Payment being processed. Waiting for shopper - >- An error occurred while processing the payment. Please query the transaction to confirm its status - Operation rejected - Operation blocked by velocity - Pending redirect - Payment canceled by the shopper - Payment already refunded - >- The refund amount exceeds the remaining balance of the original payment - Token is expired - >- An error occurred while pre processing the transaction. Please review your request and try again - >- An error occurred during while preparing transaction for acquiring. Please review your request and try again - >- No payment methods available for this operation. Please contact Paybyrd's support - >- Transaction could not be updated. Please review your request and try again - >- Operation could not be completed. Please review your request and try again - Resource access is forbidden - Resource access unauthorized - Invalid input - Resource not found - Operation failed ProductShoppingCartItem: type: object properties: amount: type: integer description: The amount of the item categories: type: array items: type: string description: The categories of the item description: type: string description: The description of the item shipping: $ref: '#/components/schemas/Shipping' type: string description: The shipping method for the item type: type: string description: The type of the item example: Product (Fixed value for product shopping cart item) enum: - Product TravelShoppingCartItem: type: object properties: amount: type: integer description: The amount of the item categories: type: array items: type: string description: The categories of the item example: - AIRLINE TICKET description: type: string description: The description of the item shipping: $ref: '#/components/schemas/Shipping' type: string description: The shipping method for the item example: VIR type: type: string description: The type of the item example: Travel (Fixed value for travel shopping cart item) enum: - Travel departure: type: string description: >- The IATA code of the airport/train or bus station if travel with transportation, else IATA code of the stay city example: GIG departureDate: type: string format: date-time description: The date and time of departure example: '2024-12-19T19:30:00Z' destination: type: string description: >- The IATA code of the airport/train or bus station if travel with transportation, empty otherwise example: LIS destinationCountryCode: type: string description: The destination country code, format ISO 3166-1 alpha-3 example: PRT hasInsurance: type: boolean description: Indicates if the customer chooses an insurance mainDepartureCompany: type: string description: >- The Airline name of the first flight (IATA code) in case of travel with flight, empty otherwise returnDate: type: string format: date-time nullable: true description: >- Can be null if the customer chooses a one-way trip. The date and time of return otherwise example: '2024-12-19T19:30:00Z' travelersCount: type: integer description: The number of passengers travelType: type: string description: The type of travel enum: - Unknown - OneWay - TwoWay - Multiple TravelWithStayShoppingCartItem: type: object properties: amount: type: integer description: The amount of the item categories: type: array items: type: string description: The categories of the item description: type: string description: The description of the item shipping: $ref: '#/components/schemas/Shipping' type: string description: The shipping method for the item type: type: string description: The type of the item example: TravelWithStay (Fixed value for TravelWithStay shopping cart item) enum: - TravelWithStay roomRange: type: string description: Accommodation range if travel with stay example: 2 stars PaymentMethod: type: string description: Represents the payment method of the transaction. example: CARD enum: - CARD - MBWAY - SIBS_MULTIBANCO - IDEAL - PAYPAL - MULTICAIXA_REF - SEPA - FLOA1XD - FLOA3X - FLOA4X Shipping: type: object properties: shippingMethod: type: string enum: - ADX - AE1 - AGE - CHX - CHR - CDS - COL - CRE - CSX - DRO - EA1 - EMP - EMX - EXP - FDR - GLS - IMP - KIA - KIB - LCE - LCS - LDS - LDE - LDR - LSP - LCK - MAG - MOR - M30 - OT1 - OT2 - OT3 - PRM - RDE - RCO - RCD - RDO - REG - REL - RIM - RCE - SO1 - SO2 - STD - STU - TNT - TNB - TNX - TRP - TRK - UPS - VIR description: The shipping method examples: OrderCreationBasicExample: description: Sample of how the create an order with Paybyrd with minimal requirements value: isoAmount: 5000 currency: EUR orderRef: ABC123456 orderOptions: redirectUrl: https://your-site-url/payment-finished culture: en-US checkoutVersion: 2 OrderCreationWithPaybylinkExample: description: Sample of how the create a paybylink with Paybyrd value: isoAmount: 5000 currency: EUR orderRef: ABC123456 shopper: firstName: JHOSH lastName: JONES orderOptions: redirectUrl: https://your-site-url/payment-finished culture: en-US checkoutVersion: 2 notifyBy: email: address: customeremail@mail.com sms: phoneCountryCode: 351 phoneNumber: '123123123' whatsapp: phoneCountryCode: 351 phoneNumber: '123123123' OrderCreationWithTokenizationExample: description: Sample of how the create an order with Paybyrd with card tokenization value: isoAmount: 5000 currency: EUR orderRef: ABC123456 orderOptions: redirectUrl: https://your-site-url/payment-finished culture: en-US checkoutVersion: 2 paymentOptions: tokenOptions: customReference: ABC123456 tokenizationIsRequired: true tokenizationMethod: cardOnFile OrderCreationFullExample: description: >- Sample of how the create an order with Paybyrd sending all available parameters value: isoAmount: 5000 currency: EUR orderRef: ABC123456 shopper: firstName: JHOSH lastName: JONES email: jhoshjs@dominio.com phoneCountryCode: 351 phoneNumber: '123123123' ip: 111.111.111.111 shippingAddress: Street name shippingPostalCode: 1234-123 shippingCity: Lisbon shippingCountry: PRT shippingState: LB documentNumber: ABC123456 homeAddress: Home street name homePostalCode: 1250-189 homeCity: Lisbon homeCountry: PRT customReference: JHOSH_JONES birthName: JHOSH birthDate: '2001-05-01' birthPostalCode: 1250-189 civility: Mr firstPurchaseDate: '2023-10-01T10:00:00Z' lastPurchaseDate: '2024-12-19T19:30:00Z' shoppingCart: - description: Product amount: 2500 categories: - Category 1 - Category 2 shipping: shippingMethod: STD type: Product - description: Travel amount: 125000 categories: - AIRLINE TICKET shipping: shippingMethod: VIR type: Travel hasInsurance: false travelType: TwoWay departureDate: '2024-12-19T19:30:00Z' returnDate: '2024-12-31T15:30:00Z' departure: GIG destination: LIS destinationCountryCode: PRT travelersCount: 1 mainDepartureCompany: LP - description: Stay amount: 250000 categories: - HOTEL shipping: shippingMethod: VIR type: TravelWithStay roomRange: 2 stars orderOptions: redirectUrl: https://your-site-url/payment-finished culture: en-US checkoutVersion: 2 expiresIn: '00:15:00' notifyBy: email: address: customeremail@mail.com sms: phoneCountryCode: 351 phoneNumber: '123123123' whatsapp: phoneCountryCode: 351 phoneNumber: '123123123' paymentOptions: maxAttempts: 1 sessionExpiresIn: '00:10:00' allowedPaymentMethods: - CARD - SIBS_MULTIBANCO - SEPA - IDEAL - MBWAY cardOptions: isPreAuth: false tokenOptions: customReference: ABC123456 tokenizationIsRequired: false tokenizationMethod: cardOnFile metadata: key1: 1 key2: value OrderCreationResponseExample: description: This is an example of how the order creation response is returned value: orderId: 63a8a157-81c9-46ea-84b4-2bef6daad3fa orderDate: '2021-08-24T17:45:27Z' expiresAt: '2021-08-25T17:45:27Z' checkoutUrl: https://chk.paybyrd.com/chk_a321as123a checkoutKey: >- eyJPcmRlcklkIjoiMzFhMDYzMmItODcxMy00NjIwLThiZjItMDdiN2UyZTk5MTRjIiwiT3JkZXJSZWYiOiI0MTAxMjA3MTU0IiwiUGVyc29uSWQiOjEwLCJMaXZlIjpmYWxzZSwiRW50aXR5SWQiOiIzMWEwNjMyYi04NzEzLTQ2MjAtOGJmMi0wN2I3ZTJlOTkxNGMiLCJBbW91bnQiOiI1MC4wMCIsIkN1cnJlbmN5IjoiRVVSIn0= status: created isoAmount: 50 currency: EUR orderRef: ABC123456 shopper: shopperId: 676b5023-9624-4d19-bdd2-c61b1be803b7 firstName: JHOSH lastName: JONES email: jhoshjs@dominio.com phoneCountryCode: 351 phoneNumber: '123123123' ip: 111.111.111.111 orderOptions: redirectUrl: https://your-site-url/payment-finished culture: en-US checkoutVersion: 2 expiresIn: '00:15:00' paymentOptions: maxAttempts: 1 sessionExpiresIn: '00:10:00' allowedPaymentMethods: - CARD - SIBS_MULTIBANCO - SEPA - IDEAL - MBWAY cardOptions: isPreAuth: false tokenOptions: customReference: ABC123456 tokenizationIsRequired: false tokenizationMethod: cardOnFile code: BYRD200 description: Operation successfully completed securitySchemes: authByApiKey: type: apiKey in: header name: x-api-key ````