---
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
  - `merchant_id` string, uuid — Merchant ID. Defaults to the logged-in merchant if not provided. Required for admin tokens.
  - `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)
      - ''
    - `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 — ISO 3166-1 alpha-2 country code
    - `postal_code` string, required — The postal code
    - `company_name` string — The company name (if applicable)
  - `amount` number, required — Decimal amount in MAJOR units (e.g. 19.99 = £19.99). Sent as a number and converted to minor units server-side. This differs from the redirect and embedded endpoints, which take an integer amount in minor units.
  - `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
  - `simulation` object — Sandbox simulation config. Honoured only when the upstream provider is a fake/sandbox backend; live providers ignore it.
    - `straddle` object
      - `customer_outcome` union — Simulated identity verification outcome
        - 'standard'
        - 'verified'
        - 'rejected'
        - 'review'
      - `paykey_outcome` union — Simulated bank account link outcome
        - 'standard'
        - 'active'
        - 'rejected'
      - `charge_outcome` union — Simulated charge outcome
        - 'standard'
        - 'paid'
        - 'on_hold_daily_limit'
        - 'cancelled_for_fraud_risk'
        - 'cancelled_for_balance_check'
        - 'failed_insufficient_funds'
        - 'reversed_insufficient_funds'
        - 'failed_customer_dispute'
        - 'reversed_customer_dispute'
        - 'failed_closed_bank_account'
        - 'reversed_closed_bank_account'
      - `balance_check` union — Balance verification behaviour
        - 'required'
        - 'enabled'
        - 'disabled'
    - `flinks` object
      - `outcome` union — Simulated bank-linking lifecycle and data shape
        - 'happy'
        - 'async'
        - 'no_us_account'
        - 'partial_data'
        - 'webhook_only'
        - 'rate_limit'
        - 'unreachable'
      - `account` object
        - `total` number, required — Total accounts to return
        - `existing` string[] — Ids of existing accounts to include; (total - existing.length) new ones are minted
      - `mfa` union — Whether an MFA challenge is presented and how it is answered
        - 'skip'
        - 'correct'
        - 'wrong'

## Response `200`

Success

- PaymentRequestResponse
  - `success` boolean, required — Indicates if the request was successful
  - `data` object, required — Payment request response data
    - `payment_link` string, required — URL of the hosted payment page to redirect the customer to

## Other responses

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

---

[API](https://skmtc.net/banqzinc/apis/quidkey-api.md) · [All operations](https://skmtc.net/banqzinc/apis/quidkey-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/banqzinc/quidkey-api/versions/f86d2bdbcb08/schema)