Hosted Payment Pages

Create Hosted payment request

Changed on Jul 13, 2026

Used to initiate a payment request using Yapily Hosted Pages.

post/hosted/payment-requests

Request

Base URL
https://api.yapily.com
Auth
HTTP basic

Headers

sub-applicationstring uuid

The sub-application ID to which event type is being subscribed to

Request body

userIdstring uuid

Conditional. Yapily Identifier for the User returned by the create user step POST /users. You must provide either a userId or applicationUserId.

applicationUserIdstring

Conditional. Your own User reference. This field allows you to use your own unique references for individual users. Where the User reference doesn't have an associated Yapily userId, a new userId is created and linked to it. You must provide either a userId or applicationUserId.

redirectUrlstring required

URL of your server to redirect the user after completion of the payment flow.

Example request

{
  "institutionIdentifiers": {
    "institutionCountryCode": "GB"
  },
  "userSettings": {
    "language": "en",
    "location": "GB"
  },
  "redirectUrl": "https://tpp-application.com",
  "paymentRequestDetails": {
    "paymentIdempotencyId": "04ab4536gaerfc0e1f93c4f4",
    "reference": "Bill payment",
    "payee": {
      "name": "Jane Doe",
      "accountIdentifications": [
        {
          "identification": "401016",
          "type": "SORT_CODE"
        },
        {
          "identification": "71518920",
          "type": "ACCOUNT_NUMBER"
        }
      ],
      "address": {
        "country": "GB"
      },
      "merchantId": "24589303",
      "merchantCategoryCode": "0742"
    },
    "payer": {
      "name": "John Doe",
      "accountIdentifications": [
        {
          "type": "SORT_CODE",
          "identification": "401016"
        }
      ],
      "address": {
        "country": "GB"
      }
    },
    "amountDetails": {
      "amountToPay": 10.5,
      "currency": "GBP"
    }
  }
}

Response

Created

Example response

{
  "data": {
    "institutionIdentifiers": {
      "institutionCountryCode": "GB"
    },
    "userSettings": {
      "language": "en",
      "location": "GB"
    },
    "redirectUrl": "https://tpp-application.com",
    "paymentRequestDetails": {
      "paymentIdempotencyId": "04ab4536gaerfc0e1f93c4f4",
      "reference": "Bill payment",
      "payee": {
        "name": "Jane Doe",
        "accountIdentifications": [
          {
            "identification": "401016",
            "type": "SORT_CODE"
          },
          {
            "identification": "71518920",
            "type": "ACCOUNT_NUMBER"
          }
        ],
        "address": {
          "country": "GB"
        },
        "merchantId": "24589303",
        "merchantCategoryCode": "5551"
      },
      "payer": {
        "name": "John Doe",
        "accountIdentifications": [
          {
            "type": "SORT_CODE",
            "identification": "401016"
          }
        ],
        "address": {
          "country": "GB"
        }
      },
      "amountDetails": {
        "amount": 10,
        "currency": "GBP"
      }
    }
  }
}

Changes

Jul 13, 2026f229468213dd Revision changes
- warning
  removed the optional property / from the response with the status
- warning
  removed the optional property / from the response with the status
- warning
  removed the optional property / from the response with the status
- warning
  removed the optional property / from the response with the status
- warning
  removed the optional property / from the response with the status
- warning
  removed the optional property / from the response with the status
- warning
  removed the optional property / from the response with the status
- warning
  removed the optional property / from the response with the status
- warning
  removed the optional property from the response with the status
- warning
  removed the optional property from the response with the status
- warning
  removed the optional property from the response with the status
- warning
  removed the optional property from the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status
- info
  the response property / became required for the status
- info
  the response property / became required for the status
- info
  the response property / became required for the status
- info
  the response property / became required for the status
- info
  the response property / became required for the status
- info
  the response property / became required for the status
- info
  the response property / became required for the status
- info
  the response property / became required for the status
- info
  the response property / became required for the status
- info
  the response property / became required for the status
- info
  the response property / became required for the status
- info
  the response property / became required for the status
- info
  added the required property / to the response with the status
- info
  added the required property / to the response with the status
- info
  added the required property / to the response with the status
- info
  added the required property / to the response with the status

Operation history