Create Payment

Creates a new payment and returns the information required to redirect the customer to the hosted checkout page.

After the customer completes payment, Overdrive Connect notifies your application through the Merchant Callback and then redirects the customer's browser back to your website.

Endpoint

POST /api/payments

Request Headers

Header	Value
Authorization	`Basic API_KEY:API_SECRET`
Content-Type	`application/json`
Accept	`application/json`

Request Body

The request body contains the payment details, customer information, and optional redirect URLs used to initiate the payment.

Payment Details

These fields describe the payment being created.

Field	Type	Required	Description
merchantPaymentReference	string	Yes	Unique payment reference generated by your application.
currency	string	Yes	Three-letter ISO currency code.

Tip

The merchantPaymentReference uniquely identifies a payment within your merchant account and must be unique for each logical payment.

Customer Information

These fields identify the customer making the payment.

Field	Type	Required	Description
firstName	string	Yes	Customer's first name.
lastName	string	Yes	Customer's last name.
email	string	Yes	Customer's email address.
mobile	string	Yes	Customer's mobile number.

Payment Items

A payment must contain one or more items.

Field	Type	Required	Description
code	string	No	Merchant SKU or product code.
name	string	Yes	Item name.
description	string	No	Item description.
unitPrice	string	Yes	Unit price with two decimal places.
quantity	integer	Yes	Number of units to purchase.

Note: unitPrice is represented as a decimal string to preserve precision.

Redirect URLs

These optional URLs determine where the customer's browser is redirected after completing payment.

Field	Required	Description
successUrl	No	Redirect URL after a successful payment.
failureUrl	No	Redirect URL after a failed payment.
cancelUrl	No	Redirect URL if the customer cancels payment.

Example Request

{
    "merchantPaymentReference": "BOOKING-10001",
    "currency": "PHP",
    "firstName": "Bruce",
    "lastName": "Wayne",
    "email": "bruce@wayne.com",
    "mobile": "09171234567",
    "items": [
        {
            "code": "sku-smvr001",
            "name": "Space Marine VR",
            "description": "Zero Latency Booking",
            "unitPrice": "1000.00",
            "quantity": 1
        }
    ],
    "successUrl": "https://merchant.example/success",
    "failureUrl": "https://merchant.example/failure",
    "cancelUrl": "https://merchant.example/cancel"
}

Note: The items array must contain at least one item.

The payment amount is automatically calculated from the sum of all items.

Example Response

{
    "referenceNumber": "0197d3fd-f9e8-7f90-8e5c-bcba2a57fef8",
    "providerReference": "pay_xxxxxxxxx",
    "redirectUrl": "https://checkout.example.com/pay/0197d3fd-f9e8-7f90-8e5c-bcba2a57fef8"
}

What Happens Next?

Merchant Website
│
Create Payment
│
Overdrive Connect
│
Returns redirectUrl
│
Browser Redirect
▼
Hosted Checkout
│
Customer Completes Payment
│
Merchant Callback
│
Browser Redirect
▼
Merchant Website

After successfully creating a payment, redirect the customer to the returned redirectUrl. Once the payment is completed, Overdrive Connect sends a signed Merchant Callback containing the final payment status before redirecting the customer back to your website.

Idempotency

The merchantPaymentReference uniquely identifies a payment within your merchant account.

Existing Payment	Result
Pending	Returns the existing payment.
Paid	Returns `409 PAYMENT_ALREADY_EXISTS`.
Failed	Creates a new payment.

Tip

Reuse the same merchantPaymentReference when retrying a request after a network interruption. This prevents duplicate payments and ensures idempotent behavior.

Possible Errors

HTTP Status	Error Code
401	`INVALID_CREDENTIALS`
409	`PAYMENT_ALREADY_EXISTS`
422	`VALIDATION_FAILED`
429	`RATE_LIMIT_EXCEEDED`
502	`PAYMENT_GATEWAY_ERROR`

Next Step

Continue to the Get Payment guide to learn how to retrieve the current status of an existing payment.