Endpoints

1. Status Check

Check if the connection to the One-CP API is established.

Endpoint: GET /status

Authentication: Basic Auth

Responses:

• 200 OK: Connection established.

  {
      "status": "ready",
      "provider": "667999d063824b596cf82155"
  }

  Property	Type	Description
  status	string	Connection status, returns "ready" when operational
  provider	string	The provider ID associated with the authenticated widget

• 401 Unauthorized: Invalid credentials.

• 403 Forbidden: No permission to access the resource.

2. Initialize Transaction

Create a new transaction for checkout processing.

Endpoint: POST /initialize

Authentication: Basic Auth

Request Body:

• application/json

  • Schema: #/components/schemas/CorporateCheckout

Responses:

• 201 Created: Transaction created successfully.

{
    "transactionId": "667999d063824b596cf82155"
}

Property	Type	Description
transactionId	string	Unique identifier for the created transaction

• 400 Bad Request: Invalid input data. See #/components/schemas/ValidationError for details.

• 401 Unauthorized: Invalid credentials.

• 403 Forbidden: No permission to access the resource.

Example Request

{
    "refIDs": {
        "provider-id": "667999d063824b596cf82155sdfwew334435"
    },
    "title": "Off site event",
    "currency": "EUR",
    "items": [
        {
            "stockId": "12345", // items id form the provider
            "name": "Flight",
            "category": "FLIGHT",
            "description": "Description of first item in CorporateCheckout",
            "period": {
                "start": "2024-04-16T12:07:05.159Z",
                "end": "2024-04-16T12:07:05.159Z"
            },
            "price": 450,
            "totalTax": 10,
            "total": 1350,
            "taxes": [
                {
                    "type": "VAT",
                    "value": 100,
                    "unit": "PERCENT",
                    "basis": "PER_QUANTITY",
                    "applyTo": "NET_PRICE"
                }
            ],
            "departure": "FRA",
            "destination": "MUC",
            "airline": "LH",
            "serviceClass": "FIRST_CLASS",
            "cancellationPolicy": {
                "description": "cancellation Policy",
                "reference": "PAYMENT_DATE",
                "penalties": [
                    {
                        "type": "OFFSET_PENALTY",
                        "offset": {
                            "amount": 2,
                            "unit": "DAYS"
                        },
                        "value": {
                            "amount": 20,
                            "unit": "FIXED_AMOUNT"
                        },
                        "condition": "AFTER_PAYMENT"
                    },
                    {
                        "type": "OFFSET_PENALTY",
                        "offset": {
                            "amount": 3,
                            "unit": "DAYS"
                        },
                        "value": {
                            "amount": 80,
                            "unit": "FIXED_AMOUNT"
                        },
                        "condition": "AFTER_PAYMENT"
                    }
                ]
            }
        }
    ],
    "recipients": ["[email protected]"],
    "attachments": [
        {
            "url": "http://file_url.pdf",
            "type": "INVOICE"
        }
    ]
}

Response

The response will contain the created transaction ID, as the following:

{
    "transactionId": "1234567890"
}

Error Handling

If there are any errors in the request, the API will return an appropriate error message with a status code indicating the type of error.

Example:

{
    "message": ["currency should not be empty", "items.0.price should not be empty"],
    "error": "Bad Request",
    "statusCode": 400
}

3. Cancel and Refund

Cancel items in a contract and process a refund.

Endpoint: PATCH /cancel

Authentication: Basic Auth

Request Body:

• multipart/form-data

  • Schema:

    allOf:
      - $ref: '#/components/schemas/CancellationReq'
      - type: object
        properties:
          file:
            type: string
            format: binary
            description: Invoice file for the cancellation (max size: 10MB).

Responses:

• 200 OK: Request processed. The response body indicates the outcome of the cancellation.

  {
      "status": "SUCCESS",
      "errorMessage": null
  }

  Property	Type	Description
  status	string	Result of cancellation operation: "SUCCESS" or "FAILED"
  errorMessage	string	Error message if status is "FAILED", otherwise null

• 400 Bad Request: Invalid input data or contract status doesn't allow cancellation. See #/components/schemas/ValidationError for details.

• 401 Unauthorized: Invalid credentials.

• 403 Forbidden: No permission to access the resource.

• 404 Not Found: Contract not found.

• 500 Internal Server Error: Internal server error or refundable amount calculation error.