---
title: "Create a payment request and return a payment_token for iframe flow"
method: POST
path: "/api/v1/embedded/payment-requests"
tags: ["Embedded"]
---

# Create a payment request and return a payment_token for iframe flow

`POST /api/v1/embedded/payment-requests`

Create a payment request and return a payment_token for iframe flow

## Request body

- EmbeddedPaymentRequestInput
  - `customer` object, required
    - `name` string, required — Full name of the customer
    - `email` string, email, required — Email address of the customer
    - `phone` string, required — E.164-formatted phone number
    - `country` string, required — ISO-3166 alpha-2 country code
  - `order` object, required
    - `order_id` string, required — Merchant's order identifier
    - `amount` integer, required — Minor-unit amount (e.g. cents)
    - `currency` string, required — ISO-4217 currency code
    - `payment_reference` string, required — Up to 18 chars, appears on customer bank statement
    - `locale` string, required — BCP-47 locale tag
    - `test_transaction` boolean — Flag to force sandbox mode
    - `rewards` object — Optional reward information for the customer
      - `extra_rewards` number, required — Reward points for this transaction
      - `total_rewards` number — Total reward points including base and extra rewards (optional)
      - `description` string — Optional description of the reward offer
  - `device_type` 'web' | 'ios' | 'android' — Platform/device type for the payment request
  - `redirect_urls` object, required
    - `success_url` string, uri, required
    - `failure_url` string, uri, required

## Response `201`

Created

- EmbeddedPaymentRequestResponse
  - `success` boolean, required — Indicates if the request was successful
  - `data` object, required
    - `payment_token` string, required — Opaque token to be embedded into iframe src
    - `expires_in` integer, required — Seconds until token expiry

## 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/embedded/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)