--- title: "Create a new telephone charge for gateway account." method: POST path: "/v1/api/accounts/{accountId}/telephone-charges" tags: ["Charges"] --- # Create a new telephone charge for gateway account. `POST /v1/api/accounts/{accountId}/telephone-charges` ## Request - The document declares no server URL. - Auth: none declared Create a new telephone charge for gateway account. These are externally taken payments and the outcome is reported to this endpoint. provider_id is used as an idempotency key for API calls. If a payment already exists with the provider_id provided, the API will not store a record about a new payment, or update or change the record about a payment previously stored. ## Path parameters - `accountId` integer, required ## Request body `*/*` - TelephoneChargeCreateRequest - `amount` integer, required: Amount in pence - `auth_code` string: Authorisation ID received from payment provider when the payment was authorised - `authorised_date` string: Date and time when payment service provider authorised the payment. Must be in ISO 8601-1 datetime format, including the time zone - `card_expiry` CardExpiryDate: The expiry date of the card the user paid with. - `fourDigitYear` string - `twoDigitMonth` string - `twoDigitYear` string - `card_type` string: card_type and must be one of the following strings: master-card, visa, maestro, diners-club, american-express, jcb - `created_date` string: Date and time the payment was initiated. Must be in ISO 8601-1 datetime format, including time zone - `description` string, required: The payment description - `email_address` string: user's email address - `first_six_digits` string: First 6 digits of user's payment card - `last_four_digits` string: Last 4 digits of user's payment card - `name_on_card` string: user's name on the front of their payment card - `payment_outcome` PaymentOutcome, required: Only applicable for telephone payments reported. Outcome after the payment has been authorised with payment provider - `code` string: Error code - `status` string - `supplemental` Supplemental - `error_code` string - `error_message` string - `processor_id` string, required: unique supplier internal reference number associated with the payment - `provider_id` string, required: Gateway transaction ID - `reference` string, required: service payment reference - `telephone_number` string: user's telephone number ## Response `200` OK - returns existing charge for provider_id - ChargeResponse - `agreement_id` string: Application for Recurring card payments. Agreement ID that the payment is associated with - `agreement_payment_type` 'instalment' | 'recurring' | 'unscheduled': Reason for taking a recurring payment - `amount` integer: Amount of this charge - `auth_3ds_data` Auth3dsData - `htmlOut` string: Applicable for ePDQ 3DS payments. If the transaction goes via the challenge flow, the response contains the additional field HTML_ANSWER (from ePDQ) which is a BASE-64 encoded code block - `issuerUrl` string: Issuer 3DS url to direct users to complete 3DS authentication - `md` string: payment session identifier returned by the card issuer - `paRequest` string: Holds 3D secure request data for the issuer. - `worldpayChallengeJwt` string: When the charge is in status 'AUTHORISATION 3DS REQUIRED' state and the 3DS data on the charge contains challenge data, Json Web Token is calculated and returned to the frontend. - `auth_code` string: Only applicable for telephone payments reported. Authorisation ID received from payment provider when the payment was authorised - `authorisation_mode` 'web' | 'moto_api' | 'agreement' | 'external': How the payment will be authorised. Payments created in `web` mode require the paying user to visit the `next_url` to complete the payment. - `authorisation_summary` AuthorisationSummary: Object containing information about the authentication of the payment - `three_d_secure` ThreeDSecure: Object containing information about the 3D Secure authentication of the payment - `required` boolean: Flag indicating whether the payment required 3D Secure authentication. - `version` string: 3DS version used to authorise payment - `authorised_date` string, date-time: Only applicable for telephone payments reported. Date and time Payment service provider authorised the payment. - `card_brand` string - `card_details` PersistedCard - `billing_address` Address - `city` string - `country` string - `county` string - `line1` string - `line2` string - `postcode` string - `card_brand` string - `card_type` 'CREDIT' | 'DEBIT' - `cardholder_name` string: The cardholder name the user entered when they paid. - `expiry_date` CardExpiryDate: The expiry date of the card the user paid with. - `fourDigitYear` string - `twoDigitMonth` string - `twoDigitYear` string - `first_digits_card_number` FirstDigitsCardNumber: The first 6 digits of the card the user paid with. - `last_digits_card_number` LastDigitsCardNumber: The last 4 digits of the card the user paid with. - `charge_id` string: Unique identifier for the charge - `corporate_card_surcharge` integer - `created_date` string, date-time - `delayed_capture` boolean: Set to true, if payment is to be captured separately - `description` string: The payment description - `email` string - `exemption` Exemption: Object containing information about 3DS exemption request of the payment. - `outcome` Outcome: Object containing information about the outcome of the 3ds exemption request - `result` 'not requested' | 'honoured' | 'rejected' | 'out of scope': Indicating the result if 3ds exemption was requested for the payment. - `requested` boolean: Flag indicating whether 3ds exemption was requested for the payment. - `type` string: Indicating the type of the 3ds exemption was requested for the payment if applicable. - `fee` integer: processing fee taken by the GOV.UK Pay platform, in pence. Only available depending on payment service provider - `gateway_transaction_id` string: The reference number the payment gateway associated with the payment. - `language` 'en' | 'cy': The language of the user’s payment page. - `links` object[]: Array of relevant resource references related to this charge - `metadata` ExternalMetadata - `metadata` object, required - `moto` boolean: Mail Order / Telephone Order (MOTO) payment flag - `net_amount` integer: amount including all surcharges and less all fees, in pence. Available depending on payment service provider - `payment_outcome` PaymentOutcome: Only applicable for telephone payments reported. Outcome after the payment has been authorised with payment provider - `code` string: Error code - `status` string - `supplemental` Supplemental - `error_code` string - `error_message` string - `payment_provider` string: The payment provider used for this transaction - `processor_id` string: Only applicable for telephone payments reported. unique supplier internal reference number associated with the payment - `provider_id` string: Only applicable for telephone payments reported. Gateway transaction ID - `reference` ServicePaymentReference: Service reference for the payment - `refund_summary` RefundSummary: Provides refund amount available and the amount that has already been submitted for refund - `amount_available` integer: Amount available for refund in pence - `amount_submitted` integer: Amount submitted for refunds on this Payment in pence - `status` string: Availability status of the refund - `user_external_id` string: User external ID issuing refund - `return_url` string: service return url - `settlement_summary` SettlementSummary: Provides a settlement summary of the charge containing date and time of capture, if present - `capture_submit_time` string: Date and time capture request has been submitted. May be null if capture request was not immediately acknowledged by payment gateway. - `capturedTime` string, date-time - `captured_date` string: Date of the capture event - `state` ExternalTransactionState: A structure representing the current state of the payment in its lifecycle - `can_retry` boolean: If a failed payment, whether it may be possible to retry it - `code` string: Error code for failed payments - `finished` boolean - `message` string: Message describing error code if payment failed - `status` string - `telephone_number` string: Only applicable for telephone payments reported. User's telephone number - `total_amount` integer: Amount your user paid in pence, including corporate card fees. total_amount only appears if corporate card surcharge is applied to the payment. - `wallet_type` 'APPLE_PAY' | 'GOOGLE_PAY': Indicates if the payment was completed using wallet payment (GOOGLE_PAY or APPLE_PAY) ## Other responses - `201`: Created - `403`: Forbidden - `404`: Not found - `422`: Missing required fields or invalid values ## Changes - **2026-10-02** `042ba06d9017`: 1 info - removed the `AMOUNT_BELOW_MINIMUM` enum value from the `error_identifier` response property for the response status `422` - **2026-10-01** `4e93196bd6aa`: 2 warning - added the new `AMOUNT_BELOW_MINIMUM_FOR_ADYEN` enum value to the `error_identifier` response property for the response status `422` - added the new `AMOUNT_BELOW_MINIMUM_FOR_STRIPE` enum value to the `error_identifier` response property for the response status `422` - **2026-05-18** `cc3bf913e89d`: 2 info - the response property `metadata/metadata` became required for the status `200` - the response property `metadata/metadata` became required for the status `201` - **2025-10-14** `f6b3b7c3c86e`: 2 info - added the optional property `agreement_payment_type` to the response with the `200` status - added the optional property `agreement_payment_type` to the response with the `201` status - **2025-01-16** `c12941ae518b`: 1 warning - added the new `AMOUNT_BELOW_MINIMUM` enum value to the `error_identifier` response property for the response status `422` [Operation history](https://skmtc.dev/government-digital-service/apis/connector-api/changes/v1/api/accounts/:accountId/telephone-charges/post.md) --- [API](https://skmtc.dev/government-digital-service/apis/connector-api.md) - [All operations](https://skmtc.dev/government-digital-service/apis/connector-api/llms.txt) - [OpenAPI document](https://skmtc.dev/government-digital-service/apis/connector-api/revisions/7f294e492d3c?raw)