GOgovernment-digital-service
Charges

Create new charge for gateway account

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

Request

  • The document declares no server URL.
  • Auth
    none declared

Path parameters

accountIdinteger required

Gateway account ID

Headers

Idempotency-Keystring nullable

Request body */*

agreement_idstring

Agreement ID to associate charge with

agreement_payment_type'instalment' | 'recurring' | 'unscheduled'

Reason for taking a recurring payment

amountinteger 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_idstring

Credential external ID to which charge to be associated. Used when verifying a live payment during PSP switch

delayed_captureboolean
descriptionstring required

The payment description (shown to the user on the payment pages)

emailstring
language'en' | 'cy'
motoboolean

Mail Order / Telephone Order (MOTO) payment flag

referencestring required

The reference issued by the government service for this payment

return_urlstring

The url to return the user to after the payment process has completed. Required when authorisation_mode is 'web'

save_payment_instrument_to_agreementboolean

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).

Example request

{
  "agreement_id": "md1mjge8gb6p4qndfs8mf8gto5",
  "amount": 100,
  "description": "payment description",
  "email": "joe.blogs@example.org",
  "language": "en",
  "moto": true,
  "prefilled_cardholder_details": {
    "billing_address": {
      "city": "London",
      "country": "GB",
      "county": "country",
      "line1": "address line 1",
      "line2": "address line 2",
      "postcode": "AB1 2CD"
    },
    "cardholder_name": "Joe B"
  },
  "reference": "payment reference",
  "return_url": "https://service-name.gov.uk/transactions/12345",
  "source": "CARD_API"
}

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"
}

Changes

  • 042ba06d9017Revision changes
    • info

      removed the AMOUNT_BELOW_MINIMUM enum value from the response property for the response status

  • 4e93196bd6aaRevision changes
    • warning

      added the new AMOUNT_BELOW_MINIMUM_FOR_ADYEN enum value to the response property for the response status

    • warning

      added the new AMOUNT_BELOW_MINIMUM_FOR_STRIPE enum value to the response property for the response status