v50

latestOpenAPI 3.0.1raw.githubusercontent.com2026-07-169377194.1 KB

Charges

Create new charge for gateway account

post/v1/api/accounts/{accountId}/charges

Path parameters

accountIdinteger required

Gateway account ID

Headers

Idempotency-Keystring nullable

Response

Created

agreement_idstring

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

amountinteger

Amount of this charge

auth_codestring

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.

authorised_datestring date-time

Only applicable for telephone payments reported. Date and time Payment service provider authorised the payment.

card_brandstring

charge_idstring

Unique identifier for the charge

corporate_card_surchargeinteger

created_datestring date-time

delayed_captureboolean

Set to true, if payment is to be captured separately

descriptionstring

The payment description

emailstring

feeinteger

processing fee taken by the GOV.UK Pay platform, in pence. Only available depending on payment service provider

gateway_transaction_idstring

The reference number the payment gateway associated with the payment.

language'en' | 'cy'

The language of the user’s payment page.

linksobject[]

Array of relevant resource references related to this charge

motoboolean

Mail Order / Telephone Order (MOTO) payment flag

net_amountinteger

amount including all surcharges and less all fees, in pence. Available depending on payment service provider

payment_providerstring

The payment provider used for this transaction

processor_idstring

Only applicable for telephone payments reported. unique supplier internal reference number associated with the payment

provider_idstring

Only applicable for telephone payments reported. Gateway transaction ID

referenceServicePaymentReference

Service reference for the payment

return_urlstring

service return url

telephone_numberstring

Only applicable for telephone payments reported. User's telephone number

total_amountinteger

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)

Example response

{
  "agreement_id": "md1mjge8gb6p4qndfs8mf8gto5",
  "amount": 100,
  "auth_3ds_data": {
    "issuerUrl": "https://3ds-secure-redirect-url.example.org",
    "md": "NnheOml4nhgrnx...pP6oBb3KQqKXiYGL3X8=",
    "paRequest": "eNpVUttygjAQ/R...jI+ts3+f4Afk4a3Y"
  },
  "auth_code": "91011",
  "authorisation_mode": "web",
  "authorisation_summary": {
    "three_d_secure": {
      "required": true,
      "version": "2.1.0"
    }
  },
  "authorised_date": "2022-06-28T16:05:33Z",
  "card_brand": "Visa",
  "card_details": {
    "billing_address": {
      "city": "London",
      "country": "GB",
      "county": "county",
      "line1": "Address line 1",
      "line2": "Address line 2",
      "postcode": "AB1 2CD"
    },
    "card_brand": "Visa",
    "card_type": "debit",
    "cardholder_name": "Joe B"
  },
  "charge_id": "b02b63b370fd35418ad66b0101",
  "created_date": "2022-06-28T09:24:45.715Z",
  "description": "payment description",
  "email": "Joe.Bogs@example.org",
  "exemption": {
    "exemption": {
      "requested": true
    }
  },
  "fee": 10,
  "gateway_transaction_id": "5422624d-12b1-4821-8b26-d0383ecf1602",
  "language": "en",
  "links": [
    {
      "href": "https://connector.example.com/v1/api/charges/b02b63b370fd35418ad66b0101",
      "method": "GET",
      "rel": "self"
    },
    {
      "href": "https://frontend.example.com/charges/1?chargeTokenId=82347",
      "method": "GET",
      "rel": "next_url"
    },
    {
      "href": "https://connector.example.com//v1/api/accounts/1/charges/b02b63b370fd35418ad66b0101/refunds",
      "method": "GET",
      "rel": "refunds"
    }
  ],
  "net_amount": 90,
  "payment_outcome": {
    "code": "P0010",
    "status": "failed",
    "supplemental": {
      "error_code": "E1234",
      "error_message": "The payment card does not exist"
    }
  },
  "payment_provider": "sandbox",
  "processor_id": "12345",
  "provider_id": "45678",
  "refund_summary": {
    "amount_available": 100,
    "status": "available",
    "user_external_id": "sk03k2pojvsojd1po2joij92pspodrkwpenl"
  },
  "return_url": "https://service-name.gov.uk/transactions/12345",
  "settlement_summary": {
    "capture_submit_time": "2022-06-28T09:26:45.715Z",
    "captured_date": "2022-06-28"
  },
  "state": {
    "can_retry": true,
    "code": "P0010",
    "finished": true,
    "message": "Payment method rejected",
    "status": "success"
  },
  "telephone_number": "+44000000000",
  "wallet_type": "APPLE_PAY"
}