Create a payment transaction - HQ Rental Software

Starts a payment for an item, such as a reservation or an invoice, through a payment method. Send the customer to the external_url of the returned transaction: it is HQ's hosted payment page.

What it creates. A transaction with status open. If an open transaction already exists for the same item and payment method, and it was started the same way (not from a payment request or a save-card flow), that transaction is updated and returned instead of creating another one. The currency is always the payment method's currency. When the account adds gateway fees to payments, the method's fee is added to amount.

After the payment. The customer is sent to external_redirect with the query parameters transaction_token (the transaction uuid), item_type, item_id, status and message. Do not trust these parameters: read the transaction with "Get a payment transaction by UUID" to confirm its status. When the payment succeeds, HQ applies it to the item.

Request

Authorization

Header Params

Body Params application/jsonRequired

Example

{
    "item_type": "car_rental.reservations",
    "item_id": 1052,
    "payment_method_id": 3,
    "external_redirect": "https://www.example.com/booking/1052/paid",
    "amount": 150,
    "label": "Reservation #1052",
    "description": "Rental deposit"
}

Responses

🟢200OK

application/json

The transaction under the payment_gateways_transaction key. In this response amount is a number. A successful body has no success field. HTTP 200 is also used for failures: such a body has success: false and is an ErrorBusinessRule (status_code 410) or an ErrorUnauthorized (status_code 401 or 403). An ErrorBusinessRule is returned when item_type and item_id do not point to an existing item.

Bodyapplication/json

Example

{
    "payment_gateways_transaction": {
        "id": 5512,
        "uuid": "8c1f7c1e-2b9a-4a51-9d1e-6f2a0b0f3c11",
        "item_type": "car_rental.reservations",
        "item_id": 1052,
        "contact_type": "contacts",
        "contact_id": 30,
        "gateway_id": 2,
        "method_id": 3,
        "label": "Reservation #1052",
        "description": "Rental deposit",
        "amount": 150,
        "currency": "usd",
        "status": "open",
        "reference": "",
        "authorization": false,
        "external_redirect": "https://www.example.com/booking/1052/paid",
        "external_url": "https://yourcompany.example.com/public/payment-gateways/payment-transactions/8c1f7c1e-2b9a-4a51-9d1e-6f2a0b0f3c11/external"
    }
}

🟠422Parameter Error