Skip to main content

Use an external system to take MOTO payments by sending card details through the API

You can send a user’s card payment details through our API to authorise a Mail Order / Telephone Order (MOTO) payment. You may want to do this if your service uses an external system to collect users’ payment information, such as an interactive voice response (IVR) telephony system.

This is different from the standard GOV.UK Pay payment flow, where users enter their own details through a web page.

This is also different from standard MOTO payments created through the API, where an agent from your service collects the paying user’s details over the phone and enters the paying user’s details.

Make sure you’ve turned on MOTO (telephone or post) payments on your account first.

Set up sending card details through the API

Before you can send users’ card details through the GOV.UK Pay API, you need to set up the feature on your account.

You can set this up on a test account or a live account.

Set up sending card details through the API on a test account

Email govuk-pay-support@digital.cabinet-office.gov.uk and ask us to turn on API payment authorisation.

We’ll let you know when we have turned on the feature on your test account.

Set up sending card details through the API on a live account

How you set up sending card details through the API on a live account differs depending on what payment service provider (PSP) you use.

You’ll be using one of the following PSPs:

  • Stripe
  • Worldpay

Set up sending card details through the API on a live account with Stripe

  1. Make sure you comply with the Payment Card Industry Data Security Standards (PCI DSS).

  2. Email govuk-pay-support@digital.cabinet-office.gov.uk to confirm you are PCI DSS compliant and would like to turn on sending card details through the API for MOTO payments. We’ll email you to let you know we’ve turned on sending card details through the API payment for your service.

  3. You can now create payments that accept card details that are sent through our API.

Set up sending card details through the API on a live account with Worldpay

  1. Create a new MOTO service that is separate from your online payments service by signing in to the GOV.UK Pay admin tool and selecting Add a new service.

  2. You need to process MOTO payments on a separate MOTO merchant code to the one you use for online payments. If you do not already have a merchant code for MOTO payments, ask for one by contacting Government Banking. You’ll use this merchant code when you connect your new service to your PSP.

  3. Make sure you comply with the Payment Card Industry Data Security Standards (PCI DSS).

  4. Email govuk-pay-support@digital.cabinet-office.gov.uk to confirm you are PCI DSS compliant and would like to turn on sending card details through the API for MOTO payments. We’ll email you to let you know we’ve turned on sending card details through the API payment for your service.

  5. You can now create payments that accept card details that are sent through our API.

Create a payment that accepts card details sent through the API

To send a user’s card details through the API, you need to set the payment’s authorisation mode when you create that payment.

Create a payment using the POST /v1/payments endpoint and include "authorisation_mode": "moto_api" in the request body. You do not need to include a return_url in your request because there’s no user to return.

You’ll receive a response that includes the auth_url_post object within the _links object. auth_url_post contains the URL (href), method (method), and unique token (one_time_token) you need to authorise the payment through our API. auth_url_post looks like this:

"auth_url_post": {
  "type": "application/json",
  "params": {
    "one_time_token": "9a084cca-2f23-4938-92ca-d7ebd1db537e"
  },
  "href": "https://publicapi.payments.service.gov.uk/v1/auth",
  "method": "POST"
}

You now need to collect the paying user’s card details and send the details through the GOV.UK Pay API.

You can see request and response examples and full definitions of every attribute for the create payment endpoint in the GOV.UK Pay API reference.

Send card details through the API

To send the paying user’s card details through our API, you’ll first need to collect your user’s:

  • card number
  • card expiry date
  • card verification code (CVC) or card verification value (CVV)
  • name from their card

When you have your user’s card details, use the POST /v1/auth endpoint to authorise the payment.

You must include the following parameters in the request body:

  • one_time_token
  • card_number - the full card number from the paying user’s card
  • cvc - the CVC or CVV on the paying user’s card
  • expiry_date - the expiry date of the paying user’s card in MM/YY format
  • cardholder_name - the name on the paying user’s card

This endpoint does not need an API bearer token. The request is instead secured with the one_time_token you received when you created this payment.

This example request sends the details of a card with the number 1111222233334444, CVC 123, and expiry date 02/24. This example authorises the MOTO payment that returned the one_time_token of 9a084cca-2f23-4938-92ca-d7ebd1db537e when that payment was created:

curl "https://publicapi.payments.service.gov.uk/v1/auth" \
-H 'Content-Type: application/json' \
-d '{
  "one_time_token": "9a084cca-2f23-4938-92ca-d7ebd1db537e",
  "card_number": "4444333322221111",
  "cvc": "123",
  "expiry_date": "02/24",
  "cardholder_name": "Sherlock Holmes"
}'

If the authorisation request is successful, you’ll receive a 204 response. The response body will be empty.

If the authorisation request is unsuccessful, you’ll receive a 4xx HTTP status code and an error code in the code attribute. You can see the meanings of GOV.UK Pay API error codes in our API reference.

We time out requests to /v1/auth after about 10 seconds. If your request times out, you’ll receive a 500 HTTP status code and a P0050 API error code.

If you add your own request timeout to your integration, it should be at least 15 seconds. Shorter timeouts risk disrupting the expected payment flow. This can result in GOV.UK Pay taking money from the paying user’s bank account after your service tells the user their payment failed.

You can see request and response examples and full definitions of every attribute for this endpoint in the GOV.UK Pay API reference.