> ## Documentation Index > Fetch the complete documentation index at: https://docs.quidkey.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a payment request and return a payment_token for iframe flow > Create a payment request and return a payment_token for iframe flow ## OpenAPI ````yaml /api-reference/openapi.json post /api/v1/embedded/payment-requests openapi: 3.1.0 info: title: Quidkey API version: 1.0.0 description: API documentation for Quidkey Core Services servers: - url: https://core.quidkey.com description: Production security: [] paths: /api/v1/embedded/payment-requests: post: tags: - Embedded summary: Create a payment request and return a payment_token for iframe flow description: Create a payment request and return a payment_token for iframe flow requestBody: required: true description: Request body content: application/json: schema: $ref: '#/components/schemas/embeddedPaymentRequest_Input' example: merchant_id: 550e8400-e29b-41d4-a716-446655440000 customer: name: John Doe email: john@example.com phone: '+351960123456' country: GB order: order_id: ORD-123456 amount: 9300 currency: GBP payment_reference: Barcelona Tryp locale: en-GB test_transaction: true rewards: extra_rewards: 150 total_rewards: 300 description: Loyalty bonus + base rewards device_type: ios billing_address: address_line1: 12 West Common Drive address_line2: Flat 1 apartment: Apt 5B city: London state_province: Greater London country: GB postal_code: SE1 1AA company_name: Acme Ltd simulation: straddle: customer_outcome: standard paykey_outcome: standard charge_outcome: standard balance_check: required flinks: outcome: happy mfa: skip redirect_urls: success_url: https://tryp.com/checkout/success failure_url: https://tryp.com/checkout/error webhook_endpoints: - wizzair-prod responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/embeddedPaymentRequest_Response' example: success: true data: payment_token: ptok_efghijklm... expires_in: 900 '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/shared_Error400' example: success: false error: message: Invalid input provided '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/shared_Error401' example: success: false error: message: Invalid input provided security: - bearerAuth: [] components: schemas: embeddedPaymentRequest_Input: type: object required: - customer - order - redirect_urls properties: merchant_id: format: uuid description: >- Merchant ID. Defaults to the logged-in merchant if not provided. Required for admin tokens. examples: - 550e8400-e29b-41d4-a716-446655440000 type: string customer: title: Payment Customer Input description: Customer information for payment flows additionalProperties: false type: object required: - name - email - phone - country properties: name: minLength: 1 description: Full name of the customer examples: - John Doe type: string email: format: email description: Email address of the customer examples: - john@example.com type: string phone: minLength: 3 description: E.164-formatted phone number examples: - '+351960123456' type: string country: pattern: ^[A-Za-z]{2}$ minLength: 2 maxLength: 2 description: ISO 3166-1 alpha-2 country code examples: - GB - US - FR - DE type: string order: type: object required: - order_id - amount - currency - payment_reference - locale properties: order_id: minLength: 1 examples: - ORD-123456 description: Merchant's order identifier type: string amount: minimum: 1 examples: - 9300 description: Minor-unit amount (e.g. cents) type: integer currency: pattern: ^[A-Za-z]{3}$ minLength: 3 maxLength: 3 description: ISO 4217 currency code examples: - GBP - USD - EUR - JPY type: string payment_reference: maxLength: 18 examples: - Barcelona Tryp description: Up to 18 chars, appears on customer bank statement type: string locale: minLength: 2 examples: - en-GB description: BCP-47 locale tag type: string test_transaction: examples: - true description: Flag to force sandbox mode type: boolean rewards: additionalProperties: false description: Optional reward information for the customer type: object required: - extra_rewards properties: extra_rewards: minimum: 0 examples: - 150 description: Reward points for this transaction type: number total_rewards: minimum: 0 examples: - 300 description: >- Total reward points including base and extra rewards (optional) type: number description: maxLength: 255 examples: - Loyalty bonus + base rewards description: Optional description of the reward offer type: string device_type: enum: - web - ios - android default: web examples: - ios description: Platform/device type for the payment request type: string billing_address: title: Address description: A physical address additionalProperties: false type: object required: - address_line1 - city - country - postal_code properties: address_line1: description: The first line of the address examples: - 12 West Common Drive type: string address_line2: description: The second line of the address examples: - Flat 1 type: string apartment: description: The apartment, unit, or suite number examples: - Apt 5B - Unit 12 - Suite 200 type: string city: description: The city examples: - London type: string state_province: description: The state or province examples: - Greater London type: string country: pattern: ^[A-Za-z]{2}$ minLength: 2 maxLength: 2 description: ISO 3166-1 alpha-2 country code examples: - GB - US - FR - DE type: string postal_code: description: The postal code examples: - SE1 1AA type: string company_name: description: The company name (if applicable) examples: - Acme Ltd type: string simulation: additionalProperties: false description: >- Sandbox simulation config. Honoured only when the upstream provider is a fake/sandbox backend; live providers ignore it. type: object properties: straddle: additionalProperties: false type: object properties: customer_outcome: description: Simulated identity verification outcome anyOf: - const: standard type: string - const: verified type: string - const: rejected type: string - const: review type: string paykey_outcome: description: Simulated bank account link outcome anyOf: - const: standard type: string - const: active type: string - const: rejected type: string charge_outcome: description: Simulated charge outcome anyOf: - const: standard type: string - const: paid type: string - const: on_hold_daily_limit type: string - const: cancelled_for_fraud_risk type: string - const: cancelled_for_balance_check type: string - const: failed_insufficient_funds type: string - const: reversed_insufficient_funds type: string - const: failed_customer_dispute type: string - const: reversed_customer_dispute type: string - const: failed_closed_bank_account type: string - const: reversed_closed_bank_account type: string balance_check: description: Balance verification behaviour anyOf: - const: required type: string - const: enabled type: string - const: disabled type: string flinks: additionalProperties: false type: object properties: outcome: description: Simulated bank-linking lifecycle and data shape anyOf: - const: happy type: string - const: async type: string - const: no_us_account type: string - const: partial_data type: string - const: webhook_only type: string - const: rate_limit type: string - const: unreachable type: string account: additionalProperties: false type: object required: - total properties: total: minimum: 1 description: Total accounts to return type: number existing: description: >- Ids of existing accounts to include; (total - existing.length) new ones are minted type: array items: type: string mfa: description: Whether an MFA challenge is presented and how it is answered anyOf: - const: skip type: string - const: correct type: string - const: wrong type: string redirect_urls: type: object required: - success_url - failure_url properties: success_url: format: uri examples: - https://tryp.com/checkout/success type: string failure_url: format: uri examples: - https://tryp.com/checkout/error type: string webhook_endpoints: maxItems: 10 description: >- 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. type: array items: description: >- Name or id of a registered webhook endpoint to route this payment's webhooks to. examples: - wizzair-prod type: string embeddedPaymentRequest_Response: type: object required: - success - data properties: success: description: Indicates if the request was successful examples: - true type: boolean data: type: object required: - payment_token - expires_in properties: payment_token: examples: - ptok_efghijklm... description: Opaque token to be embedded into iframe src type: string expires_in: description: Seconds until token expiry minimum: 1 examples: - 900 type: integer shared_Error400: title: Bad Request Error description: 400 Bad Request Error Response type: object required: - success - error properties: success: description: Always false for error responses examples: - false const: false type: boolean error: type: object required: - code - message properties: code: allOf: - description: Error code for the specific error type examples: - INVALID_INPUT type: string - description: Error code for the specific error type examples: - VALIDATION_ERROR type: string message: description: Human-readable error message examples: - Invalid input provided type: string metadata: additionalProperties: true description: >- Additional error context. For VALIDATION_ERROR, includes a per-field `errors` array. type: object properties: errors: type: array items: type: object required: - field - message properties: field: type: string message: type: string shared_Error401: title: Unauthorized Error description: 401 Unauthorized Error Response type: object required: - success - error properties: success: description: Always false for error responses examples: - false const: false type: boolean error: type: object required: - code - message properties: code: allOf: - description: Error code for the specific error type examples: - INVALID_INPUT type: string - const: UNAUTHORIZED type: string message: description: Human-readable error message examples: - Invalid input provided type: string securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ````