---
title: "Create a Web POS payment"
method: POST
path: "/v1/webpos/{webpos_device_id}/payments"
tags: ["Web POS"]
---

# Create a Web POS payment

`POST /v1/webpos/{webpos_device_id}/payments`

Create a Web POS payment. This is used to initiate a new payment acceptance process.

**Required scopes: `business/webpos:read`, `business/webpos:write`**

## Path parameters

- `webpos_device_id` string, uuid, required

## Request body

- CreateWebPOSPaymentRequest
  - `amount` Money, required — `Money` represents a monetary value denoted by both an amount and a currency. The `amount` is always going to be the smallest denomination of the given currency. As an example, when dealing with South African Rands (ZAR), the amount is in cents. eg: R150.45 is therefore represented by `Money(amount=15045, currency="ZAR")`.
    - `amount` integer, required — The amount of money in the smallest denomination of the currency. For example, when the `currency` is `ZAR`, the `amount` is in cents.
    - `currency` string, required — The currency code in ISO 4217 format.
  - `client_reference` string, required — Any reference value as determined by the host POS. It is associated with the payment and will be echoed back.
  - `metadata` object, nullable — Any map of metadata as determined by the host POS. It is associated with the payment and will be echoed back.

## Response `201`

Successful Response

- WebPOSPayment
  - `id` string, uuid, required — The unique ID for the Web POS payment. Can be used to fetch Web POS payment.
  - `status` 'failed' | 'pending' | 'successful', required
  - `redirect_url` string, required — The URL that can be loaded into an iFrame, window, or new tab to accept merchant input via their browser. The loaded web application can be used by the merchant to confirm the payment session and monitor its progress.
  - `webpos_device_id` string, uuid, required — The Web POS Device which created the payment.
  - `amount` Money, required — `Money` represents a monetary value denoted by both an amount and a currency. The `amount` is always going to be the smallest denomination of the given currency. As an example, when dealing with South African Rands (ZAR), the amount is in cents. eg: R150.45 is therefore represented by `Money(amount=15045, currency="ZAR")`.
    - `amount` integer, required — The amount of money in the smallest denomination of the currency. For example, when the `currency` is `ZAR`, the `amount` is in cents.
    - `currency` string, required — The currency code in ISO 4217 format.
  - `client_reference` string, required — The reference value provided by the host POS when the Web POS payment was created.
  - `created_at` string, date-time, required — The date and time the Web POS payment was created, in ISO 8601 format.
  - `updated_at` string, date-time, required — The date and time the Web POS payment was last updated, in ISO 8601 format.
  - `metadata` object, nullable — The metadata provided by the host POS when the Web POS payment was created.
  - `terminal` Terminal
    - `model` string, required — Payment terminal model name.
    - `serial_number` string, required — Terminal's unique serial number.
  - `payment_details` WebPOSPaymentDetails
    - `authorization_id` string, nullable — 'AuthID' provided by the issuer for the card transaction. Only available if a response is received from upstream banks and issuers.
    - `retrieval_reference_number` string, nullable — 'RRN' used to identify the transaction exchange with the acquirer. Only available if the terminal has submitted card data to upstream services.
    - `card_details` CardDetails
      - `scheme` string, required — The card issuing network.
      - `masked_pan` string, required — Masked representation of the cardholder's primary account number.
      - `pan_entry_mode` 'bar_code' | 'chip_with_cvv' | 'chip_without_cvv' | 'contactless_icc' | 'contactless_mag_stripe' | 'mag_stripe_with_cvv' | 'magnetic_stripe' | 'manual' | 'ocr' | 'unknown', required
      - `cardholder_verification_method` 'approve_cvm_processing' | 'failed' | 'no_cvm_performed' | 'offline_enciphered_pin' | 'offline_enciphered_pin_and_signature' | 'offline_plain_text_pin' | 'offline_plain_text_pin_and_signature' | 'online_pin' | 'paper_based_signature_only', required
    - `emv_application_info` EmvApplicationInfo
      - `application_identifier` string, nullable — Application Identifier 'AppID' used for the card transaction
      - `application_name` string, nullable — The name associated with the application identifier

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `429` — Too Many Requests

---

[API](https://skmtc.net/yoco/apis/yoco-api.md) · [All operations](https://skmtc.net/yoco/apis/yoco-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/yoco/yoco-api/revisions/1ee03e82bc45/schema)