PayU Order API

openapi: 3.1.0
info:
  version: 2.1.0
  title: PayU GPO Europe REST Authorize Order API
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  x-logo:
    url: https://poland.payu.com/wp-content/themes/global-website/assets/src/images/payu-logo.svg
  description: '# Overview


    This reference is designed to assist you in effectively utilizing the PayU REST API to enhance your online payment capabilities. Whether you''re running an e-commerce store or developing applications that require secure and seamless payment processing, our API offers a range of features to meet your needs.


    Our API offers a comprehensive set of endpoints to empower you with full control over your payment processes. With these endpoints, you can seamlessly create, capture, cancel, and retrieve orders, conduct payouts, and access essential reports.


    For more details on the integration, please refer to the official <a href="/europe/docs/">PayU documentation</a>. It provides comprehensive explanations, code samples, and best practices for seamless integration of the PayU API into your applications.


    ## Testing


    ### Production Environment


    For a basic integration, including only a redirection to PayU hosted payment page, it is perfectly enough to use the public test point of sale. However, if you would like to test a full set of endpoints, including e.g. refunds, consider registering for a sandbox account.


    **Public Test POS (point of sale)**


    | Key name                       |                            Value |

    | ------------------------------ | -------------------------------: |

    | POS ID (pos_id)                |                           145227 |

    | OAuth protocol - client_id     |                           145227 |

    | Second key (MD5)               | 13a980d4f851f3d9a1cfc792fb1f5e50 |

    | OAuth protocol - client_secret | 12f071174cb7eb79d4aac5bc2f07563f |


    ### Sandbox Environment


    Sandbox is an almost identical copy of PayU production system. It can be used for integration and testing purposes.


    **Public Test POS (Point of Sale)**


    Although it is best to <a href="https://registration-merch-prod.snd.payu.com/boarding/#/registerSandbox/" target="_blank">create your own account</a> to later be able to configure it as needed, you may also use a public sandbox test POS without registering:


    | Key name                       |                            Value |

    | ------------------------------ | -------------------------------: |

    | POS ID (pos_id)                |                           300746 |

    | OAuth protocol - client_id     |                           300746 |

    | Second key (MD5)               | b6ca15b0d1020e8094d9b5f8d163db54 |

    | OAuth protocol - client_secret | 2ee86a66e5d97e3fadc400c9f19b065d |


    The availability of the sandbox environment can be checked on the <a href="https://status.snd.payu.com/" target="_blank">Status page</a>.


    **Testing Card Payments**


    In order to test card payments on sandbox, please use credentials displayed on the <a href="/europe/docs/testing/sandbox/" target="_blank">Sandbox</a> documentation page.'
servers:
- url: https://secure.payu.com
  description: Production Server
- url: https://secure.snd.payu.com
  description: Sandbox Test Server
security:
- Bearer:
  - client_credentials
tags:
- name: Order
  x-displayName: Order
  description: 'Order is the basic payment request for the standard integration with PayU.

    > If the response to the payment creation request is returned with an **HTTP 200** status and in HTML format, make sure that the tool used to communicate with PayU has automatic redirect handling disabled. Only in this case is it possible to receive the correct JSON response with an **HTTP 302** status code.'
paths:
  /api/v2_1/orders:
    post:
      tags:
      - Order
      summary: Create an Order
      security:
      - Bearer:
        - client_credentials
        - trusted_merchant
      description: Create a new order request.
      operationId: create-an-order
      parameters:
      - name: Content-Type
        in: header
        description: Content type
        required: true
        schema:
          type: string
        style: simple
        example: application/json
      - name: Authorization
        in: header
        description: Auth token
        required: true
        schema:
          type: string
        style: simple
        example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: Parameters for OrderCreateRequest
              required:
              - customerIp
              - merchantPosId
              - description
              - currencyCode
              - totalAmount
              - products
              properties:
                continueUrl:
                  type: string
                  description: Address for redirecting the customer after payment is commenced.
                  example: www.example.com/path
                  maxLength: 1024
                  format: RFC 3986
                notifyUrl:
                  type: string
                  description: The address for sending notifications
                  example: https://your.eshop.com/notify
                  maxLength: 1024
                  format: RFC 3986
                customerIp:
                  type: string
                  description: 'Payer''s IP address. Value is accepted in following formats:<ul> <li> **IPv4** - address represented in the dotted decimal format of 4 sets of decimal numbers separated by dots. The decimal number in each and every set is in the range 0 - 255. Example: 1.12.123.255.</li> <li> **IPv6** - address represented as eight groups of four hexadecimal digits, each group representing 16 bits (two octets). The groups are separated by colons (:). Example: 2011:0db8:85a3:0101:0101:8a2e:0370:7334.</li></ul>'
                  examples:
                  - 127.0.0.1
                  - 127.0.0.2
                  - 8d33:56b2:24aa:b822:9b2f:1db7:c21d:04e1
                merchantPosId:
                  type: string
                  description: Point of sale ID.
                  examples:
                  - '140332'
                  - '145227'
                description:
                  type: string
                  description: Description of the order.
                  maxLength: 4000
                additionalDescription:
                  type: string
                  description: Additional description of the order.
                  maxLength: 1024
                visibleDescription:
                  type: string
                  maxLength: 80
                  description: Order/Payment description visible for Buyer on the PayU payment page.
                statementDescription:
                  type: string
                  maxLength: 22
                  description: Payment recipient name followed by payment description (order ID, ticket number etc) visible on card statement. The name should be easy to recognize by the cardholder. If field is not provided, static name configured by PayU will be used.
                extOrderId:
                  type: string
                  description: ID of an order used in merchant system. Order identifier assigned by the merchant. It enables merchants to find a specific order in their system. This value must be unique within a single POS.
                  maxLength: 1024
                currencyCode:
                  type: string
                  description: Currency code compliant with ISO 4217 (e.g EUR).
                  examples:
                  - EUR
                  - PLN
                  - USD
                totalAmount:
                  type: string
                  description: Total price of the order in pennies (e.g. 1000 is 10.00 EUR). Applies also to currencies without subunits (e.g. 1000 is 10 HUF).
                  example: '1000'
                validityTime:
                  type: string
                  description: Duration for the validity of an order (in seconds), during which time payment must be made. Default value 86400.
                  example: '100000'
                cardOnFile:
                  type: string
                  description: Information about party initializing order or a transaction with Buyer consent to save card token. "cardOnFile" parameter cannot be used with "recurring" parameter.
                  enum:
                  - FIRST
                  - STANDARD_CARDHOLDER
                  - STANDARD_MERCHANT
                  example: FIRST
                recurring:
                  type: string
                  description: 'Marks the order as recurring payment: <ul> <li><b>FIRST</b> - payment initialized by the card owner who agreed to save card for future use in recurring plan. You can expect full authentication (3D Secure and/or CVV). If you want to use multi-use token (TOKC_) later, you have to be confident, that first recurring payment was successful.</li> <li><b>STANDARD</b> - subsequent recurring payment (user is not present). This transaction has multi use token (TOKC_). You cannot use it if FIRST recurring payment failed.</li> </ul> <b><code>recurring</code> parameter cannot be used with <code>cardOnFile</code> parameter</b> .'
                  enum:
                  - FIRST
                  - STANDARD
                  example: FIRST
                donation:
                  $ref: '#/components/schemas/donation'
                buyer:
                  $ref: '#/components/schemas/buyer'
                shoppingCarts:
                  $ref: '#/components/schemas/shoppingCarts'
                products:
                  $ref: '#/components/schemas/products'
                payMethods:
                  $ref: '#/components/schemas/payMethods'
                mcpData:
                  $ref: '#/components/schemas/mcpData'
                threeDsAuthentication:
                  $ref: '#/components/schemas/threeDsAuthentication'
                riskData:
                  $ref: '#/components/schemas/riskData'
                credit:
                  $ref: '#/components/schemas/credit'
                submerchant:
                  $ref: '#/components/schemas/submerchant'
                settings:
                  $ref: '#/components/schemas/settings'
                deviceFingerprint:
                  type: string
                  description: Hashed identifier of the user or its device.
                  example: 3e9fae0b3e6003a4093358167bc1079e
                  maxLength: 255
      responses:
        '201':
          x-summary: Created
          description: SUCCESS
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: object
                    properties:
                      statusCode:
                        type: string
                  redirectUri:
                    type: string
                  qrCode:
                    type: string
                    description: Based64 encoded QR code image. **It is returned only for transparent QR code payment type**.
                  orderId:
                    type: string
                    example: WZHF5FFDRJ140731GUEST000P01
                  iframeAllowed:
                    type: boolean
                    example: true
                  threeDsProtocolVersion:
                    type: string
                    enum:
                    - 3DS2
                    example: 3DS2
                  extOrderId:
                    type: string
                  challengeParameters:
                    type: object
                    properties:
                      threeDsServerTransactionId:
                        type: string
                        example: 0016f22b-f988-4358-b2c6-8917bba22037
                      acsTransID:
                        type: string
                        example: d7c1ee99-9478-44a6-b1f2-391e29c6b340
                      acsReferenceNumber:
                        type: string
                        example: 3DS_LOA_ACS_201_13579
                      acsSignedContent:
                        type: string
                        example: c29tZUJhc2U2NGVuY29kZWRTdHJpbmc=
        '302':
          x-summary: Found
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: object
                    properties:
                      statusCode:
                        type: string
                        description: Response code
                        example: SUCCESS
                      severity:
                        type: string
                  redirectUri:
                    type: string
                    description: Url redirection address with payment summary.
                    example: https://merch-prod.snd.payu.com/pay/?orderId=WZHF5FFDRJ140731GUEST000P01&token=eyJhbGciOiJIUzI1NiJ9.eyJvcmRlcklkIjoiV1pIRjVGRkRSSjE0MDczMUdVRVNUMDAwUDAxIiwicG9zSWQiOiJhYmMxMjM0IiwiYXV0aG9yaXRpZXMiOlsiUk9MRV9DTElFTlQiXSwicGF5ZXJFbWFpbCI6InRlc3RAdGVzdC5jb20iLCJleHAiOjE2NzI3NjE4NjEsImlzcyI6IlBBWVUiLCJhdWQiOiJhcGktZ2F0ZXdheSIsInN1YiI6IlBheVUgc3ViamVjdCIsImp0aSI6IjYzMTA3M2Y0LThmMzgtNDNlZS1iOTc1LWVlNWIwZGI0ZWFiZSJ9.tBThoQDVgo9mpmh2AUDC5hkfecwtqO0L9LSCdXRYruk
                  iframeAllowed:
                    type: boolean
                    example: true
                  threeDsProtocolVersion:
                    type: string
                    enum:
                    - 3DS2
                  orderId:
                    type: string
                    description: Order identifier given by PayU.
                    example: WZHF5FFDRJ140731GUEST000P01
                  extOrderId:
                    type: string
                    description: Order identifier given by merchant.
                    example: my_ext_order_id
                  payMethods:
                    type: object
                    properties:
                      payMethod:
                        type: object
                        properties:
                          card:
                            type: object
                            properties:
                              number:
                                type: string
                                description: Card number.
                                example: 4444333322221111
                              expirationMonth:
                                type: integer
                                description: Card expiration month.
                                example: 9
                              expirationYear:
                                type: integer
                                description: Card expiration year.
                                example: 2026
                          type:
                            type: string
                            enum:
                            - CARD_TOKEN
                          value:
                            type: string
                            example: TOKC_XATB7DF8ACXYTVQIPLWTVPFRKQE
        '400':
          x-summary: Bad Request
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400'
        '401':
          x-summary: Unauthorized
          description: Incorrect authentication. Check signature parameters and implementation of the signature algorithm.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401'
        '403':
          x-summary: Forbidden
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/403'
        '500':
          x-summary: Internal server error
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/500'
  /api/v2_1/orders/{orderId}:
    get:
      tags:
      - Order
      summary: Retrieve an Order
      description: Retrieve the status and details of an order.
      operationId: retrieve-an-order
      parameters:
      - name: orderId
        in: path
        example: WZHF5FFDRJ140731GUEST000P01
        description: Order ID generated by the PayU system
        required: true
        content:
          application/json:
            schema:
              type: string
      - name: Content-Type
        in: header
        description: Content type
        required: true
        schema:
          type: string
        style: simple
        example: application/json
      - name: Authorization
        in: header
        description: Auth token
        required: true
        schema:
          type: string
        style: simple
        example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd
      responses:
        '200':
          x-summary: OK
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  orders:
                    type: array
                    description: Array of order objects.
                    items:
                      type: object
                      properties:
                        shippingMethod:
                          type: object
                          properties:
                            country:
                              type: string
                              description: Two-letter country code compliant with ISO-3166
                              example: PL
                            price:
                              type: string
                              description: Shipping cost
                              example: 2000
                            name:
                              type: string
                              description: Shipping method name
                              example: parcell
                        orderId:
                          type: string
                          description: Order ID generated by the PayU system.
                          example: VVLR1HXK2S160929GUEST000P01
                        extOrderId:
                          type: string
                          description: External order ID (assigned by the shop).
                          example: '343242'
                        orderCreateDate:
                          type: string
                          description: Order creation timestamp.
                          example: '2023-01-03T14:58:17.443+01:00'
                        notifyUrl:
                          type: string
                          description: Address for sending notifications.
                          example: http://localhost/OrderNotify/
                        customerIp:
                          type: string
                          description: 'Customer''s IP address. Note: 0.0.0.0 is not accepted.'
                          example: 127.0.0.1
                        merchantPosId:
                          type: string
                          description: Point of sale ID.
                          example: '145227'
                        description:
                          type: string
                          description: Description for order.
                          example: New Order
                        additionalDescription:
                          type: string
                          description: Additional description for order.
                          example: New Order
                        validityTime:
                          type: string
                          description: Duration for the validity of an order (in seconds), during which time payment must be made.
                          default: '86400'
                        currencyCode:
                          type: string
                          description: Currency code compliant with ISO 4217.
                          example: PLN
                        totalAmount:
                          type: string
                          description: Total price of the order.
                          example: '3200'
                        buyer:
                          $ref: '#/components/schemas/buyer'
                        payMethod:
                          type: object
                          properties:
                            amount:
                              type: string
                              example: 20000
                            type:
                              type: string
                              enum:
                              - PBL
                              - CARD_TOKEN
                              - PAYMENT_WALL
                              - BLIK_AUTHORIZATION_CODE
                              - BLIK_TOKEN
                        products:
                          $ref: '#/components/schemas/products'
                        shoppingCarts:
                          $ref: '#/components/schemas/shoppingCarts'
                        status:
                          type: string
                          description: Order status.
                          enum:
                          - NEW
                          - PENDING
                          - WAITING_FOR_CONFIRMATION
                          - COMPLETED
                          - CANCELED
                          example: COMPLETED
                  properties:
                    $ref: '#/components/schemas/properties'
        '400':
          x-summary: Bad Request
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400'
        '401':
          x-summary: Unauthorized
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401'
        '404':
          x-summary: Not found
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404'
    delete:
      tags:
      - Order
      summary: Cancel an Order
      description: Cancel (reject) orders processed by the PayU system.
      operationId: cancel-an-order
      parameters:
      - name: orderId
        in: path
        example: WZHF5FFDRJ140731GUEST000P01
        description: Order ID generated by the PayU system
        required: true
        content:
          application/json:
            schema:
              type: string
      - name: Content-Type
        in: header
        description: Content type
        required: true
        schema:
          type: string
        style: simple
        example: application/json
      - name: Authorization
        in: header
        description: Auth token
        required: true
        schema:
          type: string
        style: simple
        example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd
      responses:
        '200':
          x-summary: OK
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  orderId:
                    type: string
                    description: Order identifier in PayU's system.
                    example: WZHF5FFDRJ140731GUEST000P01
                  extOrderId:
                    type: string
                    description: Order identifier in merchant's system.
                    example: 3e5cac39-7e38-4139-8fd6-30adc06a61bd
                  status:
                    type: object
                    properties:
                      statusCode:
                        type: string
                        description: Status after update.
                        example: SUCCESS
        '400':
          x-summary: Bad Request
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400'
        '401':
          x-summary: Unauthorized
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401'
        '403':
          x-summary: Forbidden
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/403'
        '404':
          x-summary: Not Found
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404'
        '500':
          x-summary: Internal server error
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/500'
  /api/v2_1/orders/{orderId}/captures:
    post:
      tags:
      - Order
      summary: Capture Authorized Order
      description: Capture whole order and update its status to COMPLETED (ended).
      operationId: capture-authorized-order
      parameters:
      - name: orderId
        in: path
        example: WZHF5FFDRJ140731GUEST000P01
        description: Order ID generated by the PayU system
        required: true
        content:
          application/json:
            schema:
              type: string
      - name: Content-Type
        in: header
        description: Content type
        required: true
        schema:
          type: string
        style: simple
        example: application/json
      - name: Authorization
        in: header
        description: Auth token
        required: true
        schema:
          type: string
        style: simple
        example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/Full'
              - $ref: '#/components/schemas/Partial'
      responses:
        '200':
          x-summary: OK
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: object
                    properties:
                      statusCode:
                        type: string
                        description: Status after update.
                        example: SUCCESS
                      statusDesc:
                        type: string
                        description: Status message.
                        example: Status was updated
        '400':
          x-summary: Bad Request
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400'
        '401':
          x-summary: Unauthorized
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401'
        '500':
          x-summary: Internal server error
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/500'
  /api/v2_1/orders/{orderId}/status:
    put:
      tags:
      - Order
      summary: (deprecated) Capture Authorized Order
      description: Capture an order and update its status to COMPLETED (ended).
      operationId: capture-authorized-order-deprecated
      parameters:
      - name: orderId
        in: path
        example: WZHF5FFDRJ140731GUEST000P01
        description: Order ID generated by the PayU system
        required: true
        content:
          application/json:
            schema:
              type: string
      - name: Content-Type
        in: header
        description: Content type
        required: true
        schema:
          type: string
        style: simple
        example: application/json
      - name: Authorization
        in: header
        description: Auth token
        required: true
        schema:
          type: string
        style: simple
        example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - orderId
              - orderStatus
              properties:
                orderId:
                  type: string
                  description: Identifier of the order you want to update.
                  example: VVLR1HXK2S160929GUEST000P01
                orderStatus:
                  type: string
                  description: Status of the order after update.
                  example: COMPLETED
      responses:
        '200':
          x-summary: OK
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: object
                    properties:
                      statusCode:
                        type: string
                        description: Status after update.
                        example: SUCCESS
                      statusDesc:
                        type: string
                        description: Status message.
                        example: Status was updated
        '400':
          x-summary: Bad Request
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400'
        '401':
          x-summary: Unauthorized
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401'
        '500':
          x-summary: Internal server error
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/500'
  /api/v2_1/orders/{orderId}/transactions:
    get:
      tags:
      - Order
      summary: Retrieve a Transaction
      description: Retrieve the details of transactions created for an order with specified `orderId`.
      operationId: retrieve-a-transaction
      security:
      - Bearer:
        - oAuth token
      parameters:
      - name: orderId
        in: path
        example: WZHF5FFDRJ140731GUEST000P01
        description: Order ID generated by the PayU system
        required: true
        content:
          application/json:
            schema:
              type: string
      - name: Content-Type
        in: header
        description: Content type
        required: true
        schema:
          type: string
        style: simple
        example: application/json
      - name: Authorization
        in: header
        description: Auth token
        required: true
        schema:
          type: string
        style: simple
        example: Bearer 3e5cac39-7e38-4139-8fd6-30adc06a61bd
      responses:
        '200':
          x-summary: OK
          description: ''
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/card'
                - $ref: '#/components/schemas/pbl'
                - $ref: '#/components/schemas/blik'
                - $ref: '#/components/schemas/wire'
        '400':
          x-summary: Bad Request
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400'
        '401':
          x-summary: Unauthorized
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/401'
        '404':
          x-summary: Unauthorized
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/404'
components:
  schemas:
    pbl:
      type: object
      properties:
        transactions:
          type: array
          description: Array of order objects.
          items:
            type: object
            properties:
              payMethod:
                type: object
                properties:
                  value:
                    type: string
             

# --- truncated at 32 KB (85 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/payu/refs/heads/main/openapi/payu-order-api-openapi.yml