---
title: "Create a new payment request"
method: POST
path: "/api/v1/payment-requests"
tags: ["Payments"]
---

# Create a new payment request

`POST /api/v1/payment-requests`

Create a new payment request

## Request body

- PaymentRequestInput — Payment request input parameters
  - `customer` object, required — The customer details
    - `name` string, required — The name of the customer
    - `email` union, required — The email of the customer (either email or phone_number must be provided)
      - string, email — The email of the customer (either email or phone_number must be provided)
      - string
    - `phone_number` string — The phone number of the customer (either email or phone_number must be provided)
  - `billingAddress` object, required — The billing address details
    - `address_line1` string, required — The first line of the address
    - `address_line2` string — The second line of the address
    - `apartment` string — The apartment, unit, or suite number
    - `city` string, required — The city
    - `state_province` string — The state or province
    - `country` string, required — The country code
    - `postal_code` string, required — The postal code
    - `company_name` string — The company name (if applicable)
  - `amount` number, required — The amount of the payment request
  - `currency` string, required — The currency of the payment request
  - `payment_reference` string — Payment reference to appear on the payer’s bank statement (max 18 alphanumeric characters)
  - `order_id` string — The unique identifier for the merchant's order
  - `locale` string, required — The locale of the payment request
  - `platform` string, required — The platform used for the payment request
  - `device_type` string — The type of device used for the payment request
  - `external_payment_request_id` string — External payment reference
  - `test_transaction` boolean — Flag for test transactions
  - `group` string — For grouping related transactions
  - `gid` string — Global identifier
  - `selected_bank_id` string — Selected bank reference
  - `session_id` string — Session tracking
  - `success_url_redirect` string — URL to redirect on successful payment
  - `fail_url_redirect` string — URL to redirect on failed payment

## Response `201`

Created

- PaymentRequestResponse
  - `success` boolean, required — Indicates if the request was successful
  - `data` object, required — Payment request response data
    - `redirect_url` string, required — URL to redirect the user to

## Other responses

- `400` — Bad Request
- `401` — Unauthorized

## Changes

- **2025-11-03** `6637b341d86d` — 1 info
  - endpoint added
- **2025-11-02** `919eb7a392aa` — 1 breaking
  - api path removed without deprecation

[Change history](https://skmtc.dev/banqzinc/apis/quidkey-api/changes/api/v1/payment-requests/post.md)

---

[API](https://skmtc.dev/banqzinc/apis/quidkey-api.md) · [All operations](https://skmtc.dev/banqzinc/apis/quidkey-api/llms.txt) · [OpenAPI document](https://skmtc.dev/banqzinc/apis/quidkey-api/revisions/6637b341d86d?raw)