--- title: "Create new charge for gateway account" method: POST path: "/v1/api/accounts/{accountId}/charges" tags: ["Charges"] --- # Create new charge for gateway account `POST /v1/api/accounts/{accountId}/charges` ## Request - The document declares no server URL. - Auth: none declared ## Path parameters - `accountId` integer, required ## Headers - `Idempotency-Key` string, nullable ## Request body `*/*` - ChargeCreateRequest - `agreement_id` string: Agreement ID to associate charge with - `agreement_payment_type` 'instalment' | 'recurring' | 'unscheduled': Reason for taking a recurring payment - `amount` integer, required: Amount in pence - `authorisation_mode` 'web' | 'moto_api' | 'agreement' | 'external': Mode of authorisation for the payment. Payments created in `web` mode require the paying user to visit the `next_url` to complete the payment. - `credential_id` string: Credential external ID to which charge to be associated. Used when verifying a live payment during PSP switch - `delayed_capture` boolean - `description` string, required: The payment description (shown to the user on the payment pages) - `email` string - `language` 'en' | 'cy' - `metadata` ExternalMetadata - `metadata` object, required - `moto` boolean: Mail Order / Telephone Order (MOTO) payment flag - `prefilled_cardholder_details` PrefilledCardHolderDetails - `billing_address` PrefilledAddress: A structure representing the billing address of a card - `city` string - `country` string - `county` string - `line1` string - `line2` string - `postcode` string - `cardholder_name` string: prefilled cardholder name - `reference` string, required: The reference issued by the government service for this payment - `return_url` string: The url to return the user to after the payment process has completed. Required when authorisation_mode is 'web' - `save_payment_instrument_to_agreement` boolean: Applicable for recurring card payments. Indicated whether the payment method should be saved to agreement - `source` 'CARD_API' | 'CARD_PAYMENT_LINK' | 'CARD_AGENT_INITIATED_MOTO' | 'CARD_EXTERNAL_TELEPHONE': Source of payment (e.g. CARD_PAYMENT_LINK) - defaults to CARD_API (which cannot be specified explicitly). ## Response `201` Created - 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 - `400`: Bad Request - `403`: Gateway account is disabled - `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`: 1 breaking, 1 info - the request property `metadata/metadata` became required - the response property `metadata/metadata` became required for the status `201` - **2025-10-14** `f6b3b7c3c86e`: 1 info - added the optional property `agreement_payment_type` to the response with the `201` status - **2025-10-13** `0ff6ca5eab78`: 1 info - added the new optional request property `agreement_payment_type` [Operation history](https://skmtc.dev/government-digital-service/apis/connector-api/changes/v1/api/accounts/:accountId/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)