---
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
  - `merchant_id` string, uuid — Merchant ID. Defaults to the logged-in merchant if not provided. Required for admin tokens.
  - `customer` object, required — Customer information for payment flows
    - `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-1 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
  - `billing_address` object — A physical address
    - `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)
  - `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'
  - `redirect_urls` object, required
    - `success_url` string, uri, required
    - `failure_url` string, uri, required
  - `webhook_endpoints` string[] — Optional. Up to 10 registered webhook endpoints to fan this payment's webhooks out to, each signed with its own secret. An endpoint can be test-only, live-only, or both. Omit to use the no-reference precedence: the legacy default URL, then the merchant's default endpoint, then the single active endpoint.

## 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

---

[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)